Setup Branches and Releases

With Storyblok’s branches you can set-up a content staging workflow. To run a reliable production environment it is crucial to define different stages to test your content on pre stages to make sure that the production content is ready for public. To do so we’ve introduced our content staging feature, allowing you to define a strict content pipeline through different stages, where each stage can be accessed from the API.

Branches / Stages

Branches define a stage of your content. Each space already ships with a default branch, which is the Preview branch once this feature has been activated.

Branches and Releases

You can setup more branches, eg. stages in the settings of each space. Above you can see an example setup with the Preview Branch where you can apply different Releases, and Branches that can be used for test and production content stages.

You’re not forced to create the same structure as above, sometimes an easier setup with one the Preview and a Production Stage might be enough.

How to get content from a specific branch

To get the content from a specific branch you need to create a new access token for that branch. After you configured your branches you will see a select-box to choose your branch when creating an api-key in the space settings. We recommend using a different preview URL for each branch and use environment variables to set the right api-key for each domain.

How to configure the preview URL

For each stage you can define a preview URLs in the branch settings. A simple setup could look like this:

Preview url for branch

The Preview Branch

By design the preview branch is the place where all the editors and developers work will happen. Content will be created, updated, and even whole structural changes are going to be made in this stage. The Preview stage will be the one place that can be deployed throughout the other Stages. Branches, with the exception of this Preview Stage, are read only and each of the branch can have multiple releases and api-keys.

The Custom Branch

Custom Branches can be created in the settings of your space. By defining new Stages. Every custom branch is read only and can only be changed by deploying it’s source. Deploying content does not affect the draft or published state of each content entry.


Before changing content in the Preview Branch you’re able to create a new Release to bundle your changes so they won’t apply directly. Doing that allows you to prepare product launches or startpage changes. The content of a release can be accessed by appending the URL parameter from_release with the release id, as every release lives within the Preview Stage you will still need the token for that Preview Stage.

To setup releases when using the visual preview you need to check the value of the url parameter _storyblok_release and adapt your api calls to include the parameter from_release.

Example request getting a single content item from the release with the id 29:

$ curl -X GET \

Starting a new Release

Starting a new release

  1. Press “New Release” before making any changes
  2. Enter the new of the Release you’re about to start
  3. If you already know the release date, schedule it
  4. Press “Create” to create the new Release

The new Release

The new release

  1. Tab navigation through multiple releases, identified using the release name
  2. Edit button to allow changes to schedule date, name and even deleting a release
  3. As there are currently no changes to your release you won’t see any entry if you select the “Show only items from this release” checkbox. Once you’ve created ne entries or updated existing stories this checkbox will allow you to see only content entries you either created and those you’ve changed.
  4. Pressing “Send Approval” will allow you to send an approval request to another collaborator of your space, to make sure your changes are okay to be applied back to the first stage: Preview.
  5. To apply your changes back to the Preview Stage you can use the “Release Now” feature or wait till the release schedule is fulfilled.

You can now work in the release as you would normally do in the default Preview stage. Your changes will not affect the Preview stage and therefore won’t be deployed on later Stages that use the Preview Stage as it’s source.