How do Sites connect to Git branches?

Every Site connected to a Git Repository reads from exactly one branch of it. That branch holds the files your team edits in CloudCannon, and CloudCannon commits their saved changes back to it. Choosing the branch is part of connecting the repository, and you can change it later without disconnecting.

Choosing a branch when you connect a repository#

You choose a branch on the Syncing page under Site Settings, in the same step where you pick a repository. CloudCannon offers two ways to do it.

Select the Use an existing branch option to connect to a branch that already exists, then pick it from the Branch dropdown. The dropdown is searchable, which helps in a repository with a long branch list.

Select the Create a new branch option to have CloudCannon make the branch for you. The Source branch dropdown sets the branch to copy from, and the New branch name field names the branch CloudCannon creates.

If the Branch dropdown shows a warning instead of your branches, your Permission Group is missing the org:settings:git:branch:read permission. Listing repositories needs org:settings:git:repository:read in the same way.

[docshot] The branch section of the Syncing page under Site Settings, showing the Use an existing branch and Create a new branch options above the Branch dropdown.

For the full connection walkthrough for your Git Provider, please read our documentation on connecting a GitHub repository as your source, connecting a GitLab repository as your source, or connecting a Bitbucket repository as your source.

Switching the branch a Site connects to#

A Site is not tied to the branch you first chose. On the Syncing page under Site Settings, click the Switch branch button to open the Switch branch modal, pick the new branch the same way you picked the first one, then click the Switch branch button in the modal to confirm.

CloudCannon syncs the files from the new branch as soon as you confirm, so the Site shows the new branch's content straight away. Anything CloudCannon already deployed from the previous branch stays where it is; switching does not remove it.

[docshot] The Switch branch modal, showing the branch options and the Switch branch button.

Connecting several Sites to the same branch#

The relationship between branches and Sites is normally one-to-one, but nothing in CloudCannon enforces it. You can connect any number of Sites to the same branch of the same repository.

This is worth doing when one Git Repository holds more than one website, an arrangement often called a monorepo. Each website lives in its own directory, and each gets its own Site.

To tell those Sites apart, give each one its own Configuration File. The CloudCannon Configuration File path field on the Details page under Site Settings points a Site at a configuration file outside the root of the repository, and the source key in that file scopes the Site to one directory. Without this, Sites sharing a branch are duplicates of each other. For more information, please read our documentation on defining a custom Configuration File path.

How changes reach your Sites#

When anything pushes to a branch, your Git Provider notifies CloudCannon, and CloudCannon pulls that change into every Site connected to that repository and branch. A developer pushing from their local environment, a merged pull request, and an Organization Member saving in CloudCannon all take the same path.

This is what makes several Sites on one branch behave as a group. A change saved on one of them reaches the others, because all of them are reading the branch it was committed to.

If a Site receiving the change has unsaved changes to an affected file, CloudCannon pauses Syncing on that Site rather than overwriting the work in progress. The Organization Member editing it sees a Syncing paused warning and has to save or discard before Syncing resumes. For more information, please read our documentation on why Syncing pauses.

Which repositories you can connect#

Connecting a GitHub, GitLab, or Bitbucket repository is available on every Subscription Plan. Self-hosted GitLab and GitHub Enterprise Server repositories are available on our Enterprise plan. For more information, please read our documentation on connecting a self-hosted GitLab repository as your source.