Branches and promotion

The branch model, how content enters the system, and how promotion moves published content forward.

A branch is an environment: a complete, independent copy of your content, addressed by its own delivery tokens. This is the same model Storyblok uses for pipeline stages, reproduced on plans that do not include the Pipelines app.

Two kinds of branch

Parameter	Type	Description
`PREVIEW`	branch kind	The only branch that ingests content. It mirrors your Storyblok space, in both published and draft states, and there is exactly one per space.
`STAGE`	branch kind	Frozen. Changes only through promotion, and receives published content only. Staging and Production are both of this kind.

PREVIEWbranch kind

The only branch that ingests content. It mirrors your Storyblok space, in both published and draft states, and there is exactly one per space.

STAGEbranch kind

Frozen. Changes only through promotion, and receives published content only. Staging and Production are both of this kind.

Branches are copies, not pointers

Each branch holds its own rows, exactly as Storyblok does. That is why id differs for the same story across branches, while uuid stays constant. Folder relationships are rebuilt per branch, so parent_id is always valid within the branch you queried.

How content moves

text

Storyblok space
      │  sync — published + draft
      ▼
  Preview  ──── promote (published only) ────▶  Staging
                                          └──▶  Production

Content is one-directional. Nothing flows back from a stage branch into preview, and stage branches never talk to each other unless you promote between them.

Sync

Sync reconciles the preview branch against your Storyblok space. It is idempotent — running it twice changes nothing the second time.

New and changed stories are written; unchanged ones are skipped without a database write.
Folders are captured from the Management API, which is the only source that lists them.
Content deleted in Storyblok is removed from preview. It stays on downstream branches until you promote.

Promotion

Promotion copies published content from a source branch to a target. It compares content hashes, so only stories that actually changed are written, and it reports what it did.

Promotion result

Parameter	Type	Description
`added`	integer	Stories that did not exist on the target.
`updated`	integer	Stories whose content differed from the target’s copy.
`removed`	integer	Stories deleted from the target because they no longer exist on the source.

addedinteger

Stories that did not exist on the target.

updatedinteger

Stories whose content differed from the target’s copy.

removedinteger

Stories deleted from the target because they no longer exist on the source.

Promotion bumps the target branch’s cache version, which is what tells CDNs and clients that a new version is live. Every promotion is recorded with its counts, its actor and its outcome.