Deploy from Git

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. Choose the provider and connect it (see Git providers), 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 Connect another repository and Disconnect actions.

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

Git providers

Git deploys work with GitHub, GitLab (gitlab.com) and Bitbucket (bitbucket.org). Self-hosted GitLab instances are not supported. The provider decides how you connect:

• GitHub connects through the revenexx GitHub App. Choose Continue to GitHub and authorise the account or organisation.
• GitLab and Bitbucket connect with an access token. When you pick the repository, or under Settings → Git Accounts, choose Add installation, pick the provider and enter the Namespace: the GitLab group or user (for example acme or acme/web) or the Bitbucket workspace. Then enter the Access token. For Bitbucket this is a workspace access token, or an Atlassian API token entered as email:api-token. Atlassian has retired Bitbucket app passwords, so a username:app-password pair no longer works. Only repositories directly in the namespace are listed, not those in GitLab subgroups below it.

The token needs permission to read repository contents, manage webhooks and write commit status. The platform checks it against the provider before it keeps it, and stores it encrypted. Connecting a repository from GitLab or Bitbucket creates a webhook on that repository; disconnecting leaves the webhook in place. A delivery to it then builds nothing; delete it in the repository's settings on the provider if you no longer want it.

To replace an expiring token, open Settings → Git Accounts, choose Renew token on the installation and save the new one with Save token. Linked apps and sites keep working.

A pull request from a fork is never built on its own. On GitHub it is not built until it is authorized, and the pull request shows a failed status, Authorization required for external contributor. On GitLab and Bitbucket it is not built at all: the platform has no step where a maintainer approves it first.

Deploy triggers

Two controls in the site's settings decide when a push turns into a build. Both sit on the Git repository card: choose Edit, change them, then Save Git repository.

For the standard workflow, keep Deployment trigger on On every push and Preview deployments on. 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

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 signed-in members of your tenant, so a branch build is not public before you activate it. See Previews.

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:

# 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

# 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 Deployment trigger is set to Only on tags and releases, or the repository connection lost its authorisation: connect it again with Connect another repository in the site's settings, and for GitLab or Bitbucket renew the token under Settings → Git Accounts.

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

Related

• 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