Deploy from Git

Connect a repository once, then every push builds — the production branch activates, every other branch gets a preview.

Connect a site to a Git repository and pushing becomes your deploy step. The platform installs dependencies, runs your build, and creates a new deployment; a push to the production branch activates it, and a push to any other branch gets a preview instead.

This is the path to use for day-to-day work. The alternatives — the CLI and an upload — exist for a first push, a CI step, or a repository you can't connect.

Connect a repository

A site is connected once, either when you create it or afterwards:

When creating the site. In Cockpit under Experience Studio → Sites, start a new site and choose the Git path. Authorise the GitHub account or organisation, pick the repository, then set the production branch and the root directory. The framework quick-starts cover this per framework.
On an existing site. Open the site's settings and connect a repository there. A site created by upload can be connected later; its earlier deployments stay as they are. The connected repository is shown in the site's settings with Reconnect and Disconnect actions.

You choose the production branch at connect time — usually main. Everything below follows from that one setting.

Deploy triggers

Two controls in the site's settings decide when a push turns into a build. Both save together, with Save triggers:

Control	What it does
When to deploy	`On every push` builds on every push to the production branch.
Preview deployments	When on, builds a preview and comments the status on every pull request.

Leave both on for the standard workflow. Turning Preview deployments off is what you want when a repository gets a high volume of pull requests you don't need built.

What a push does

You push to	What happens
The production branch	A deployment is created, built, and activated. It replaces the running one on your domains as soon as the build finishes.
Any other branch	A deployment is created and built, but not activated. It gets preview hostnames instead, and with Preview deployments on, a pull request from that branch gets its build status as a comment.

A production push has no confirmation step, which is the point — and the reason to be deliberate about which branch you named. If a build turns out to be wrong, activating the previous deployment takes effect immediately; see Instant rollbacks.

Preview hostnames are reachable only by members of your tenant, so a branch build is not public before you activate it.

Deploy a specific branch or commit

A connected site doesn't only build on push. You can trigger a build for any branch or commit from the CLI, which is what a CI job usually wants:

Shell

# Build the current tip of a branch and make it live
revenexx sites create-vcs-deployment \
    --site-id <SITE_ID> \
    --type branch \
    --reference main \
    --activate true

Shell

# Build one specific commit, without activating it
revenexx sites create-vcs-deployment \
    --site-id <SITE_ID> \
    --type commit \
    --reference <SHA> \
    --activate false

Nothing is uploaded — the platform fetches from the connected repository, so this works from a machine that has no checkout.

Build settings are on the site, not in the repository

The install command, build command, output directory, framework, adapter and environment variables belong to the site. They are not read from a file in your repository, which surprises people exactly once:

A change applies from the next deployment. Editing the build command does not change the running build. Push again, or trigger a build with the CLI.
Cockpit, the CLI and the API write the same fields. There is no second source of truth to reconcile.

A theme is the exception worth knowing: its theme.json#site block carries these as defaults, which is how a scaffolded theme deploys correctly with nothing configured. See Theme anatomy and Build configuration.

Debugging

The build succeeded but the site serves nothing. The output directory doesn't match what your build wrote. Check it against the per-framework defaults — only files inside that directory are served.
A configuration change had no effect. Build settings apply to the next deployment. Create one.
The build fails on the platform but works locally. The build runs a plain install against the public npm registry. Commit your lockfile, and check that no dependency resolves only from a private registry or a workspace.
A push to a feature branch went live. That branch is the site's production branch. Check the Git settings.
Nothing built at all. Either When to deploy is not set to build on push, or the repository connection lost its authorisation — use Reconnect in the site's settings.

Read the failure itself in the build logs, on the deployment: Deployments.

Deploy from the CLI — the one-command path, and per-step control
Deploy manually — uploading a build with no repository attached
Build configuration — install command, build command, output directory
Environment variables — and why a change needs a redeploy
Previews — the hostnames a non-production branch gets
Deployments — statuses and build logs

Was this page helpful?