# Why branches exist and when to use them

### About this export

| Field | Value |
| --- | --- |
| **content_type** | lesson |
| **platform** | contentstack-academy |
| **source_url** | https://www.contentstack.com/academy/courses/workflow-branches-and-collaboration/why-branches-exist-and-when-to-use-them |
| **course_slug** | workflow-branches-and-collaboration |
| **lesson_slug** | why-branches-exist-and-when-to-use-them |
| **markdown_file_url** | /academy/md/courses/workflow-branches-and-collaboration/why-branches-exist-and-when-to-use-them.md |
| **generated_at** | 2026-08-03T11:49:54.389Z |

> Part of **[Workflow, Branches, and Collaboration](https://www.contentstack.com/academy/courses/workflow-branches-and-collaboration)** on Contentstack Academy. **Academy MD v3** — structured for retrieval; no quiz or assessment keys.

<!-- ai_metadata: {"lesson_id":"06","type":"text","duration_minutes":1,"topics":["Why","branches","exist","and","when","use"]} -->

#### Lesson text

# Why branches exist and when to use them

> **TL;DR:**
> 
> *   Contentstack branches fork content type schemas (not code) so you can iterate on structural changes without disrupting production.
> *   Stack-level resources (environments, webhooks, workflows, roles) are shared across all branches.
> *   Use branches for breaking schema changes; use workflow stages and environments for content-only isolation.

Branches in Contentstack are not git branches. Misunderstanding this leads to architectural mistakes that take weeks to unwind. Git branches create parallel versions of code files. Contentstack branches create parallel versions of your content model - the content type definitions, global fields, and optionally the entries that conform to those schemas. They exist to solve a specific problem: how do you make structural changes to your content types without disrupting the production content that editors are actively publishing?

## The problem branches solve

Imagine you have a “Product” content type with 12 fields, and your production e-commerce site renders products based on that schema. Your frontend code expects those 12 fields, in that structure, with those data types. Now your team needs to restructure the Product content type: add a “specifications” modular block, rename the “description” field to “short\_description,” add a new “long\_description” rich text field, and remove the deprecated “legacy\_sku” field.

Without branches, you have two options:

**Option 1:** Make changes directly on the live content type. The moment you add “specifications” and remove “legacy\_sku,” every delivery API response for Product entries changes shape. Your frontend code, which expects the old schema, breaks. If your site is server-rendered, pages start throwing errors. If it is statically generated, the next rebuild fails. Your editors, who are trying to publish product updates during a sale event, are blocked.

**Option 2:** Coordinate a synchronized cutover. You plan the content type changes, prepare the frontend code, and deploy everything simultaneously during a maintenance window. This works for small changes but becomes a high-risk, high-coordination effort for significant schema restructuring. If anything goes wrong during the cutover, you are rolling back both CMS changes and frontend code under pressure.

Branches provide a third option: create a branch, make all your schema changes there, test them, update your frontend code against the branch's API, and merge when everything is validated. The production content model remains untouched until you are ready.

## What branches include

A branch in Contentstack is a fork of specific stack resources at a point in time. When you create a branch from main, the branch receives copies of:

*   Content type definitions: every content type's schema (fields, field types, validations, options) is duplicated on the branch. Changes to content types on the branch do not affect main, and vice versa.
*   Global field definitions: shared field groups used across content types are also branched. Modifying a global field on a branch does not change the global field on main.
*   Entries (optionally): depending on your configuration, entries can be included in the branch. This gives you content to test against your modified schemas.

After creation, the branch evolves independently. If you add a field to the “Product” content type on the branch, the main branch's “Product” content type still has the original schema. The two versions diverge, and reconciling them is a deliberate merge operation (covered in the next lesson).

## What branches do NOT include

> **Common pitfall:** Stack-level settings (environments, webhooks, workflows, roles) are not branched. Modifying a webhook on the stack affects events on all branches, plan accordingly.

Several stack-level resources are not branched:

*   Environments: development, staging, production - these are stack-wide. A branch does not get its own set of environments.
*   Delivery tokens: tokens are scoped to environments, not branches. However, you use a branch-specific delivery URL or parameter to fetch content from a specific branch.
*   Webhooks: webhook configurations are stack-level. Creating a branch does not duplicate your webhook setup.
*   Workflows: workflow configurations exist at the stack level. Entries on a branch follow the same workflow rules as entries on main.
*   Roles and permissions: user roles and their permissions apply across all branches.
*   Automation Hub configurations: automations operate at the stack level.

This design reflects the fact that branches are for content model development, not for creating isolated operational environments. If you need separate environments for testing, use Contentstack environments (covered in Course 3). If you need separate content for different regions, use localization. Branches solve the schema evolution problem specifically.

## The main branch

Every Contentstack stack has a main branch by default. This is the production branch - the one your delivery tokens serve content from, the one your editors work in, and the one your frontend application queries against. The main branch is always present and cannot be deleted.

All other branches are created from main (or from other branches). When you create a branch called feature/product-redesign, it forks from the current state of main. From that point forward, the two branches are independent.

The main branch is special in one important way: it is the default target for API queries. When you make a delivery API request without specifying a branch, you get content from main. This means your production site continues working exactly as before when you create a new branch - nothing changes until you explicitly merge branch changes back to main.

## Creating a branch

You create branches through the Contentstack UI or the API.

Through the UI: navigate to **Settings > Branches** and click “Add Branch.” You provide:

*   A branch name (unique within the stack)
*   A source branch to fork from (usually main)

Through the API: use the Content Management API to create a branch programmatically.

// Creating a new branch via the Management API
const response = await fetch(
  "https://api.contentstack.io/v3/stacks/branches",
  {
    method: "POST",
    headers: {
      api\_key: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY!,
      authorization: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_MANAGEMENT\_TOKEN!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      branch: {
        uid: "feature-product-redesign",
        source: "main",
      },
    }),
  }
);

const result = await response.json();
console.log(\`Branch created: ${result.branch.uid}\`);
// Output: "Branch created: feature-product-redesign"

Branch creation is not instantaneous for large stacks. Contentstack needs to duplicate all content type definitions (and optionally entries) to the new branch. For a stack with 30 content types and thousands of entries, this may take a few minutes. The API returns immediately with the branch metadata, and the branch becomes available once the duplication process completes.

## Branch scope: a snapshot that evolves

A critical concept is that a branch is a snapshot of content types at the time of creation, which then evolves independently. This has two implications:

Changes on the branch do not affect main. You can add fields, remove fields, create new content types, and restructure schemas on the branch without any impact on the main branch. Editors working on main see no changes. The delivery API for main returns the same content in the same structure as before.

Changes on main do not affect the branch. If an editor adds a new entry on main, that entry does not appear on the branch. If a developer adds a field to a content type on main (for example, a quick fix), that field does not appear on the branch's version of that content type. The branch and main diverge from the moment of creation.

This divergence is both the power and the risk of branches. The longer a branch lives, the more it diverges from main, and the harder the eventual merge becomes. This lifecycle management challenge is addressed in the lesson on avoiding branch sprawl.

## Querying content from a branch

To test your schema changes against actual API responses, you need to query content from the branch rather than from main. The delivery API supports branch-specific queries through a request header.

// Fetching products from a specific branch
import contentstack from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY!,
  deliveryToken: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN!,
  environment: "development",
  branch: "feature-product-redesign",
});

// This returns entries using the branch's content type schema
const result = await stack
  .contentType("product")
  .entry()
  .query()
  .find();

// The response shape reflects the branch's schema,
// including the new "specifications" modular block
result.entries.forEach((product: any) => {
  console.log(product.title);
  console.log(product.specifications); // new field from the branch
});

By specifying the branch parameter, you get content shaped according to the branch's content type definitions. This is how your frontend development team can build and test against the new schema before it reaches main.

## When to use branches

Branches are the right tool when you need to make structural changes to your content model that cannot be done safely on main. Specific scenarios include:

**Adding a new content type that requires iteration.** You are building a “Video” content type with embedded metadata, transcription references, and platform-specific encoding fields. The content type needs several rounds of refinement before it is ready for editors to use. Creating it on a branch lets you iterate without polluting the main branch with half-finished content types.

**Restructuring an existing content type.** You need to convert the “Article” content type from a flat field structure to one that uses modular blocks for the body section. This is a breaking change - existing entries and frontend code depend on the current structure. A branch lets you make the change, migrate test entries, and validate the new structure before applying it to main.

**Running a large migration.** You are migrating from a legacy content model to a new one. The migration involves renaming fields, changing field types, and adding new required fields across multiple content types. A branch provides a sandbox for the entire migration, letting you validate the result before committing to main.

**Coordinating frontend and CMS changes.** Your frontend team needs to rebuild the homepage component to support a new layout. The new layout requires different fields in the “Page” content type. The frontend team works against the branch's API, building and testing the new component while the production site continues serving the old layout from main.

## When NOT to use branches

Branches are not a general-purpose isolation mechanism. They solve the content model evolution problem, and using them for other purposes creates confusion and overhead.

Do not use branches for content-only changes. If you need to create, edit, or delete entries without changing the content type schema, you do not need a branch. Work on main. Branches add complexity that is only justified when the content model itself is changing.

Do not use branches for environment isolation. If you need to test content in a staging context, use Contentstack environments (as covered in Course 3). Environments control where content is published. Branches control how content is structured. These are different concerns.

Do not use branches for small, non-breaking field additions. Adding an optional field to a content type does not break existing entries or API responses. The new field appears with a null value on existing entries, and the delivery API returns it only when populated. This kind of change can be made directly on main without risk.

Do not use branches for urgent hotfixes. If you need to add a field immediately to support a production fix, creating a branch, making the change, and merging back adds unnecessary delay. Make the change on main, deploy the frontend update, and move on.

## Example: restructuring content types for a media company

A media company runs a news website built on Contentstack. Their current content model has an “Article” content type with a single rich text field for the body and a “Video” content type that only stores a URL and a title. The development team needs to:

1.  Add a “Video” content type with full metadata: title, description, duration, thumbnail, platform (YouTube, Vimeo, self-hosted), transcript reference, and encoding specifications.
2.  Restructure the “Article” content type to use modular blocks for the body, allowing editors to mix text blocks, embedded videos, pull quotes, and image galleries.
3.  Add a “Gallery” content type for image collections.

All three changes are structural and would break the existing production site if applied directly to main. The team creates a branch called feature/media-redesign:

*   On the branch, they build the new “Video” content type with all its fields.
*   They modify the “Article” content type to use modular blocks.
*   They create the “Gallery” content type.
*   They create test entries to validate the new schemas.
*   The frontend team queries the branch's API to build new components for videos, modular article bodies, and galleries.
*   Once everything is validated, they merge the branch back to main and deploy the frontend changes simultaneously.

Throughout this process, the production site runs uninterrupted. Editors continue publishing articles with the old flat body field. The delivery API for main continues serving the existing schema. The branch changes are invisible to everyone outside the development team until the merge is executed.

## Common mistakes

### Mistake 1: Treating Contentstack branches like git branches

Git branches create parallel versions of code files and merge line-by-line. Contentstack branches create parallel versions of content type schemas and merge at the field level. The mental model, the merge mechanics, and the conflict resolution are all different. Do not assume your git branch workflow translates directly to Contentstack branches.

### Mistake 2: Creating branches for content editing rather than schema changes

If an editor wants to draft 20 articles without affecting the live site, they do not need a branch. They need to use the Draft workflow stage and not publish to production. Branches exist for content model changes, not content changes. Using branches for editorial isolation creates unnecessary merge complexity and confuses the team about what branches are for.

### Mistake 3: Forgetting that stack-level settings are not branched

A developer creates a branch and expects the branch to have its own webhook configurations, its own workflow stages, or its own delivery tokens. It does not. These are stack-level resources shared across all branches. If you modify a webhook on the stack, it applies to events on all branches. Plan accordingly.

#### Key takeaways

- Connect **Why branches exist and when to use them** back to your stack configuration before moving to the next module.
- Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment.
- Re-read the delivery versus management boundary for anything you changed in the entry model.

## Supplement for indexing

### Content summary

Why branches exist and when to use them. Why branches exist and when to use them TL;DR: Contentstack branches fork content type schemas (not code) so you can iterate on structural changes without disrupting production. Stack-level resources (environments, webhooks, workflows, roles) are shared across all branches. Use branches for breaking schema changes; use workflow stages and environments for content-only isolation. Branches in Contentstack are not git branches. Misunderstanding this leads to architectural mistakes that take weeks to unwind. Git branches create parallel versions of code files. Contentstack branches create parallel versions of your content model - the content type definitions, global fields, and optionally the en

### Retrieval tags

- Why
- branches
- exist
- and
- when
- use
- workflow-branches-and-collaboration
- lesson 06
- Why branches exist and when to use them
- workflow-branches-and-collaboration lesson

### Indexing notes

Index this lesson as a primary chunk tagged with lesson_id "06" and topics: [Why, branches, exist, and, when, use].
Parent course slug: workflow-branches-and-collaboration. Use asset_references URLs as thumbnail hints in search results when present.
Never surface LMS quiz content or assessment answers from this file.

### Asset references

_No image or video thumbnail URLs were extracted._

### External links

| Label | URL |
| --- | --- |
| Contentstack Academy home | `https://www.contentstack.com/academy/` |
| Training instance setup | `https://www.contentstack.com/academy/training-instance` |
| Academy playground (GitHub) | `https://github.com/contentstack/contentstack-academy-playground` |
| Contentstack documentation | `https://www.contentstack.com/docs/` |