---
title: "Safe content model changes with branches and aliases"
url: "https://developers.contentstack.com/guides/safe-content-model-changes-with-branches-and-aliases"
type: "guide"
level: "intermediate"
intent: "ship"
outcome: "You can change content types on a branch, merge them into main with a chosen strategy, and point your frontend at an alias you can repoint without a deploy."
prerequisites:
  - "A stack with branches enabled on your plan"
  - "The Contentstack CLI 2.x (csdx) installed and logged in"
  - "A management token you can scope to branches"
  - "A frontend that reads content with the Delivery SDK"
tags:
  - "cli"
  - "content_modeling"
  - "automation"
authors:
  - "Tim Benniks"
published: "2026-11-22T09:00:00.000Z"
updated: "2026-11-15T10:56:25.494Z"
---

# Safe content model changes with branches and aliases

- **Authors:** Tim Benniks
- **Published:** 2026-11-22T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:25.494Z
- **Level:** Intermediate
- **Intent:** Ship
- **Tags:** cli, content_modeling, automation

---

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.

flowchart LR  A[main] -->|fork| B[model-v2]  B -->|migration script| B  B -->|cm:branches:diff| C{Ship how?}  C -->|merge into main| A  C -->|repoint alias| D[alias: production]  A -.->|today| D## 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.

```bash
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:

```bash
csdx cm:branches -k <stack-api-key> --verbose
```

The 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:

```javascript
// 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:

```bash
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).

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```typescript
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:

```bash
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.

```yaml
# .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-token
```

Watch 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:

```bash
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](/guides/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](/guides/deploy-from-ci-with-the-launch-cli-and-api).


- Learn how the CLI plugin system works in [Write your own csdx plugin](/guides/write-your-own-csdx-plugin).





---

## Do this with AI

Install the cms-branches-aliases skill from [Contentstack agent skills](https://github.com/contentstack/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](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## 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.

