When working locally, you have full control over your code and can implement workflows as necessary. But with a Stackbit project, Stackbit needs to know which branches to work, along with how to handle publishing content.

Git Branches

A Stackbit project works with a target and working branch:

Target Branch

The target branch is the one Stackbit uses to deploy the live site, as part of our managed hosting. (You can also implement your own deployment solution.)

Typically, this is the default branch of the repository (e.g. main or master).

If your content is stored as files in Git rather than an external headless CMS, this branch is also the one that content changes are merged into when content editors hit Publish. (See below for customizing this behavior.)

Working Branch

Stackbit uses the working branch to run your site in our visual editor (i.e. when you open the Stackbit project from the dashboard). This is the branch that content editors will work on.

Typically, this branch is created automatically by Stackbit as part of project creation and is named preview.

Configuring Branches

In many cases, you will not need to change the default settings for these branches. Stackbit automatically selects the repository's default branch as the target branch and will automatically create a preview branch for the working branch (or use an existing preview branch if available).

You can override these defaults in the advanced settings when creating a new project from GitHub.

Target & working branch setting

Changing Working Branch

You can also adjust the working branch after creating a project through the advanced settings:

Open advanced settings

  1. Click gear icon next to project name.
  2. Select Advanced tab.

Then you'll be able to choose an existing branch to use as the Stackbit working branch. Note that you will not see the target branch as an option. You must work on a separate branch.

Select working branch

Be sure to verify you're working with the correct branches before starting to edit and publish content.

Publishing Workflow

When working with files as the content source (Git CMS), Stackbit handles every change to code or content as an individual git commit, and pushes that commit to GitHub.

When publishing, Stackbit merges the working branch (default: preview) into your main branch.

Customize Publishing Workflow

You can customize this behavior to either:

  • Open a pull request in GitHub, rather than merging.
  • Merge into a specific branch.

To set your preference, open advanced settings (see above) and adjust the Publish Action section.

Publish action settings