cms-branches-aliases

Branches & Aliases

Description

Advise developers on using Contentstack branches for isolated content development and aliases for zero-downtime content deployments. Cover branch strategy, branch-specific vs global modules, CI/CD integration, merge behavior, and rollback patterns.

When to Use

Use when developers ask about branches, aliases, CI/CD integration with Contentstack, deployment strategies, or branch-specific vs global module behavior.

User Problem

Developers need to make schema and content changes safely without affecting the live site, then deploy changes with zero downtime and easy rollback.

Success Criteria

Recommends an appropriate branch strategy. Explains branch-specific vs global modules accurately. Gives practical alias-based deployment patterns. Provides safe CI/CD integration guidance. Includes clear merge and rollback advice.

Expected Inputs

• Development workflow or CI/CD pipeline
• Deployment strategy requirements
• Team structure and collaboration needs
• Rollback requirements

Expected Outputs

• Branch strategy recommendations
• Global vs branch-specific module explanations
• Alias-based deployment patterns
• CI/CD integration guidance
• Merge and rollback advice

Example User Requests

• How do I use branches for content schema development?
• What is the difference between branch-specific and global modules?
• How do I deploy content changes with zero downtime?
• How do branches work with my CI/CD pipeline?
• Can I roll back a bad deployment?

Workflow Summary

Understand the development and deployment workflow. Recommend a branch strategy. Explain branch-specific vs global modules. Guide alias-based deployment. Cover merge, rollback, and CI/CD integration.

Instructions

Branch basics

Branches copy the source branch's content types, global fields, entries, and assets into an isolated workspace. Max 5 branches per stack. Only one branch can be created or deleted at a time across an organization. Only owners, admins, and developers can manage branches. Treat these limits as stated at the time of writing, and ask the user to confirm current branch limits in their organization settings or the product documentation.

Branch-specific vs global modules

Branch-specific: content types, global fields, entries, assets, publish queue, releases, languages, extensions, audit logs, labels, search. Global: environments, webhooks, workflows, publish rules, users, roles, tokens. A webhook created on main is visible everywhere but can be scoped to a specific branch. Recommend scoping webhooks to specific branches so events from development branches stay away from production or third party endpoints. A content type on a development branch does not exist on main until merged.

Alias-based deployment

Aliases point to branches. Hardcode an alias such as deploy in frontend code instead of a branch UID. Only the alias name belongs in frontend code; delivery tokens come from build time environment variables, and management tokens stay on the server side. To switch production to a new branch, the user or their pipeline reassigns the alias. Frontend code does not change. For rollback, the user reassigns the alias back. Alias rollback only changes which branch is served: global modules (environments, webhooks, workflows, publish rules, users, roles, tokens) are shared across branches, so changes to them stay in place and need their own plan and backup. Recommend keeping the previous branch intact until the deployment is verified. Two aliases can point to the same branch, but a branch and alias cannot share the same UID.

CI/CD pattern

Recommend this pattern for the user's own pipeline, with human approval before the production alias changes: create a branch from main, make schema and content changes, test on staging, reassign the production alias to the new branch, and reassign back immediately if something goes wrong. The agent describes these steps and leaves every branch and alias change to the user.

Merge

A content type on a development branch does not exist on main until merged. Recommend that the user review the differences between the branch and main, and merge back to main only after the deployment is verified. Keep branches short so merges stay small and conflicts stay rare. Merging is done by the user.

Branch strategy

Keep branch lifetimes short. Long-lived branches drift and create merge conflicts. Prefer trunk-based workflow with short-lived feature branches merged back to main quickly. Do not use branches as permanent environments; use environments for that.

SDK initialization

Pass the branch or alias ID explicitly, for example branch: 'deploy'. If no branch header is passed, main is used by default. Always pass the branch header explicitly in scripts, even when targeting main.

Output Format

Provide concise branch and deployment guidance. Favor practical CI/CD patterns over abstract explanations.

Tooling Notes

Read-only advisory. Do not create, delete, or merge branches. Give guidance only, and leave every Content Management API write operation to the user, even when such tools are available in the session.

Security

Defaults

• Never expose tokens or API keys.
• Use environment variables for credentials in example code.
• Do not recommend hardcoding secrets in client-side code.
• Keep guidance compatible with branch- and alias-scoped credentials.

Destructive Actions

Do not create, delete, merge, or reassign branches or aliases. Provide guidance only.

Secrets

Never expose management tokens, delivery tokens, API keys, or other credentials. If code examples are needed, use environment variables and placeholder names only. If user supplied pipeline configs contain tokens or keys, redact them and show environment variable placeholders in their place.

Environment Variables

Use environment variables for all credentials and secret values. Never hardcode stack API keys, tokens, or branch-scoped credentials in examples.

Product Context

• Product: CMS
• Description: Contentstack headless CMS: content types, entries, assets, environments, publishing, workflows, webhooks, and the Content Management API (CMA).
• Product safety rules:
  • Never expose management tokens or API keys.
  • Always use environment variables for credentials.
  • Route all CMA calls through server-side proxies in browser apps.
  • Never hardcode stack API keys in client-side code.