Do this with AI
Install the cms-branches-aliases skill from Contentstack agent skills and connect the Content Modeler profile in MCP Profile Hub. Then ask your agent:
Compare the content types on my feature branch with main and list every field that was added, removed or changed type, without merging anything.
New to this? Set up your AI workbench first.
Safe content model changes with branches and aliases
Changing a content type on a live stack is the riskiest thing most teams do in Contentstack. Delete a field and every entry loses that data. Rename one and your frontend breaks until the next deploy. Branches give you a place to make those changes in isolation, and aliases let you switch the frontend to the new model without touching your code.
This guide walks through the full loop: fork a branch from main, change the model with a migration script, diff it, merge it back, and decide when to repoint an alias instead. At the end you have a CI workflow that runs the same steps on every pull request.
What you'll learn
How branches and aliases relate to each other
Which modules a branch copies and which stay global
How to script content type changes with cm:stacks:migration
How to diff and merge branches with the CLI and the API
When to merge and when to repoint an alias
How to scope tokens and run the flow from CI
Branches, aliases, and how they fit together
Contentstack concept: A branch is an isolated copy of a stack's content model and content. Every stack starts with a main branch, and you fork new branches from main or from any other branch.
If you are coming from Git, the mental model is close. You branch off main, make changes, compare, and merge back. The difference is what merges: Contentstack merges content types and global fields, not entries. More on that below.
Contentstack concept: An alias is a named pointer to one branch. Your frontend reads from the alias, for example production, instead of a branch UID. Repointing the alias to another branch changes what the frontend renders without a code change or a redeploy.
Think of an alias as a symlink. The frontend always opens the same path. You decide where it points.
What a branch copies and what stays global
A new branch inherits the content of its source branch. Changes on the child do not touch the parent, and the other way around. Not everything is branch-scoped, though, and that list matters more than people expect.
Branch-specific | Global across all branches |
|---|---|
Content types and global fields | Taxonomies and terms |
Entries and assets | Environments |
Languages | Users and roles |
Extensions | Delivery and management tokens (scoped to branches or aliases) |
Releases and the publish queue | Webhooks (you pick which branch triggers each one) |
Labels | Workflows and publish rules (you pick which branches they apply to) |
Audit logs and global search | Marketplace apps |
The one that catches people most often is taxonomies. They are global. If your model change on a branch includes new taxonomy terms, adding those terms changes every branch, including the one your production site reads from. That is usually harmless, since unused terms do nothing, but deleting or moving a term is not something you can test in isolation.
When you create a branch you also choose which environments to clone: all of them, none, or a specific set. Cloning an environment copies its published content into the new branch, so the branch can serve real content the moment you point an alias at it.
Create a branch from main
Create the branch with the CLI. The --uid is the branch name, and --source is the branch you fork from.
csdx cm:branches:create --source main --uid model-v2 -k <stack-api-key>Branch creation runs in the background. List the branches to see when it is ready:
csdx cm:branches -k <stack-api-key> --verboseThe verbose table shows each branch with its source and aliases. Creating a branch requires a user session (an authtoken), so run this as a logged-in user, not with a management token.
Change the model with a migration script
You can edit content types in the UI on the new branch, and for exploration that is fine. For anything you want to repeat, review, or run in CI, write a migration script. The cm:stacks:migration command runs a JavaScript file against a branch and gives you a small API for content types and fields.
Here is a script that adds a summary field to the blog_post content type and moves it below the title:
// migrations/01-add-blog-summary.js
module.exports = ({ migration }) => {
const blogPost = migration.editContentType('blog_post');
blogPost
.createField('summary')
.display_name('Summary')
.data_type('text')
.mandatory(false);
blogPost.moveField('summary').afterField('title');
};Run it against the branch, never against main:
csdx cm:stacks:migration \
--file-path ./migrations/01-add-blog-summary.js \
--branch model-v2 \
-k <stack-api-key>To run every script in a folder, pass --multiple with the folder path. Prefix the filenames with numbers so the order is obvious when you read them, and keep each script small so a failure points at one change.
Migration scripts stay safe when you follow these rules:
Add before you remove. A new optional field never breaks a frontend. A deleted field does.
Keep new fields optional until existing entries have values, or the next save on every old entry fails validation.
Treat the script as code. Commit it, review it, and run it on a branch first.
The command runs your file with Node and with your own permissions, so only run scripts you have read.
Diff the branches
Before you merge, look at what actually changed. cm:branches:diff compares a compare branch (your changes) against a base branch (where they go).
csdx cm:branches:diff \
--base-branch main \
--compare-branch model-v2 \
--module content-types \
-k <stack-api-key>The default compact-text output lists added, modified, and deleted content types. For field-level changes, use --format detailed-text, which also writes a CSV report you can attach to a pull request:
csdx cm:branches:diff \
--base-branch main \
--compare-branch model-v2 \
--module all \
--format detailed-text \
--csv-path ./reports/model-v2-diff.csv \
-k <stack-api-key>--module accepts content-types, global-fields, or all. Those are the only modules compare and merge support.
Merge into main
cm:branches:merge shows the diff, asks for a merge strategy, and applies it.
csdx cm:branches:merge \
--base-branch main \
--compare-branch model-v2 \
--comment "Add summary field to blog_post" \
-k <stack-api-key>The strategy decides what happens with new items, modified items, and conflicts. These are the API values; the CLI prompt shows the same options by name.
Strategy | What it does |
|---|---|
merge_prefer_base | Adds compare changes to base. On conflict, keeps base. |
merge_prefer_compare | Adds compare changes to base. On conflict, keeps compare. |
overwrite_with_compare | Replaces base content with compare content. |
merge_new_only | Adds only new items from compare. Ignores modified items. |
merge_modified_only_prefer_base | Adds only modified items. On conflict, keeps base. |
merge_modified_only_prefer_compare | Adds only modified items. On conflict, keeps compare. |
ignore | Leaves base unchanged. Use it as the default and set per-item strategies. |
For a branch that only adds fields and content types, merge_prefer_compare is the usual choice. If editors also changed content types on main while you worked, merge_prefer_base keeps their changes and only brings in yours where there is no conflict.
Backup branches and merge status
By default, a merge first creates a backup of the base branch. That backup is your undo button: point your alias at it and the site renders the pre-merge model while you sort things out. The backup counts as one extra branch beyond your plan's limit, so delete it before the next merge if you are at the cap. Pass --no-revert to skip it, which you should only do on throwaway branches.
Merges run as background jobs. The command polls until the job finishes. If you lose the terminal or the polling times out, check the job by its UID:
csdx cm:branches:merge-status -k <stack-api-key> --merge-uid <merge-job-uid>Entries need their own migration
The merge moves content types and global fields. It does not move entries. If you filled in summary on twenty entries in model-v2, those values are still only on model-v2 after the merge.
The CLI can generate entry migration scripts for the content types you merged. It writes them to a merge_scripts folder and prints the command to run them. You run them with cm:stacks:migration against the base branch:
csdx cm:stacks:migration \
--multiple \
--file-path ./merge_scripts \
--inline-config compare-branch:model-v2 \
--branch main \
-k <stack-api-key>The generated scripts cover straightforward create and update cases. Read them before running, and edit them for anything more involved, such as splitting one field into two.
Point delivery at an alias
Merging is the right move when the change is additive and editors keep working on main. For a large rewrite, such as a new page model, you often want to build the new content on the branch and switch the whole site at once. That is what aliases are for.
Create an alias called production in Settings > Branches > Aliases and point it at main. Then configure the Delivery SDK with the alias instead of a branch UID:
import contentstack from '@contentstack/delivery-sdk';
export const stack = contentstack.stack({
apiKey: process.env.CONTENTSTACK_API_KEY!,
deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
environment: process.env.CONTENTSTACK_ENVIRONMENT!,
branch: 'production',
});The SDK sends production as the branch header on every request. Contentstack resolves the alias to its target branch.
When model-v2 is ready, repoint the alias. In the UI, edit the alias and pick the new target branch. Through the Content Management API, it is one request:
curl -X PUT "https://api.contentstack.io/v3/stacks/branch_aliases/production" \
-H "api_key: $CONTENTSTACK_API_KEY" \
-H "authtoken: $CONTENTSTACK_AUTHTOKEN" \
-H "Content-Type: application/json" \
-d '{ "branch_alias": { "target_branch": "model-v2" } }'The next request from your frontend reads from model-v2. Rolling back is the same call with main as the target. An alias points to exactly one branch at a time.
Production note: Deploy frontend code that handles both the old and the new model before you repoint the alias. If the new code only understands model-v2, rolling back the alias breaks the site instead of saving it.
If your site is statically generated, repointing the alias changes what the next build fetches. Trigger a rebuild or revalidation after the switch.
Scope tokens to branches and aliases
Tokens are global modules, but you choose which branches and aliases each token can reach.
Delivery tokens: scope the frontend's token to the alias it reads from, for example production. If the token does not include the alias, the request fails.
Management tokens: give CI a token scoped to the branches it migrates. A token for the feature branch workflow does not need write access to main until the merge step.
Keep a separate token for preview or staging deployments that read from a branch directly. That way a staging build never reads from the production alias by accident, and you can revoke one without touching the other.
Run the flow from CI
The pieces above map onto a pull request workflow. The developer creates the branch once with the CLI. CI then applies the migration scripts to that branch on every push, so the branch always matches the scripts in the repository.
# .github/workflows/content-model.yml
name: Content model
on:
pull_request:
paths: ['migrations/**']
jobs:
migrate-branch:
runs-on: ubuntu-latest
env:
CS_BRANCH: model-v2
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm install -g @contentstack/cli
- name: Save management token alias
run: >
csdx auth:tokens:add --management -y
--alias ci-token
--stack-api-key "${{ secrets.CS_API_KEY }}"
--token "${{ secrets.CS_MANAGEMENT_TOKEN }}"
- name: Run migrations on the feature branch
run: >
csdx cm:stacks:migration --multiple
--file-path ./migrations
--branch "$CS_BRANCH"
--alias ci-tokenWatch out for repeat runs. A script that calls createField('summary') assumes the field does not exist yet, and the migration command does not track which scripts already ran. Keep that record yourself, for example a list of applied filenames stored as a CI artifact or committed to the repository, and skip those files on the next push. Once a pull request merges, move its scripts to an applied folder so they never run again.
For the merge itself, the branches_merge endpoint accepts a management token, which makes it a good fit for a deploy job after the pull request merges:
curl -X POST "https://api.contentstack.io/v3/stacks/branches_merge?base_branch=main&compare_branch=model-v2&default_merge_strategy=merge_prefer_compare&merge_comment=Merge%20model-v2" \
-H "api_key: $CS_API_KEY" \
-H "authorization: $CS_MANAGEMENT_TOKEN"The response contains the merge job uid and merge_details.status. Poll GET /v3/stacks/branches_queue/{uid} until queue[0].merge_details.status is complete or failed, and fail the job on failed.
Keep the alias repoint as a manual step or a separate approved job. It needs a user authtoken, and it is the moment your production site changes, so a person should own it.
Where people get confused
Confusion 1: "Merge" means everything merges
It doesn't. Only content types and global fields merge. Entries, assets, releases, and labels stay on the branch where you created them. Plan the entry work as its own step.
Confusion 2: Editors keep working on main
A branch is a snapshot at fork time. Entries that editors create or publish on main after you fork do not appear on your branch. If you plan to switch the site by repointing an alias, agree on a content freeze for the switch, or copy the late changes over with a script. If you merge instead, this problem goes away, because editors never leave main.
Confusion 3: Taxonomies feel branch-scoped
They aren't. Taxonomies and terms are shared by every branch. Content types reference them per branch, but the terms themselves are global.
Confusion 4: The alias is the branch
An alias has no content of its own. Publishing, workflows, and releases happen on the target branch. Editors working "on production" are working on whatever branch the alias points to at that moment.
Limits to remember
The number of branches depends on your plan. The merge backup branch can exceed the limit by one, but you may need to delete it before the next merge.
Compare and merge cover content types and global fields only.
Creating a branch and assigning an alias require an authtoken. Merge, compare, and merge-status calls accept a management token.
Owners, admins, and developers can create branches and assign aliases.
Releases are branch-specific. A release created on model-v2 deploys items from model-v2 only.
Key takeaways
Fork with csdx cm:branches:create --source main --uid <branch> and never run migrations against main first.
Script model changes with cm:stacks:migration --branch <branch> and keep them additive.
Review cm:branches:diff --format detailed-text before every merge.
cm:branches:merge moves content types and global fields; run the generated merge_scripts for entries.
Point the Delivery SDK at an alias with branch: 'production' and repoint it to ship or roll back.
Taxonomies, environments, and tokens are global; scope tokens to the branches and aliases they need.
Next steps
Read Modular blocks, references or global fields before you plan a large model change.
Automate the deploy side with Deploy from CI with the Launch CLI and API.
Learn how the CLI plugin system works in Write your own csdx plugin.
Frequently asked questions
Does merging a branch also merge entries?
No. Compare and merge cover content types and global fields only. Entry changes need migration scripts, which the CLI can generate for the content types you merged.
Are taxonomies copied into a new branch?
No. Taxonomies are a global module, so every branch in the stack sees the same taxonomies and terms. Changing a taxonomy on one branch changes it everywhere.
How do I undo a merge?
By default a merge creates a backup of the base branch first. Point your alias at that backup branch to roll the site back while you fix things.
Can a delivery token read from an alias?
Yes. Delivery and management tokens can be scoped to specific branches or to aliases. A token that does not include the branch or alias you request cannot read from it.