Publishing & Git Workflows
Customize Stackbit to work with your existing workflows.
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.
A Stackbit project works with a target and working 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.
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.)
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
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.
Changing Working Branch
You can also adjust the working branch after creating a project through the advanced settings:
- Click gear icon next to project name.
- 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.
Be sure to verify you're working with the correct branches before starting to edit and publish content.
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.