<h1>Definition of Branches&nbsp;in Contentstack</h1>In Contentstack, "Branches" play a pivotal role in content management by allowing users to create isolated copies of their stack into a new branch. A branch is a separate workspace where modifications can be made without immediately affecting the primary stack. Every stack has a main branch by default. To create a new branch, you can fork a new branch off of the main branch. This section will provide an introduction to the&nbsp;branches feature within Contentstack.<h2>Why branches?</h2>&nbsp; - Definition and Purpose of Branches: Branches contain a copy of the content types, entries, assets, and other items. They serve as containers for content modifications, enabling users to experiment and iterate without impacting the live content. The purpose of branches is to allow developers to change the content types and not affect the main 'production' branch.&nbsp; - Importance of Content Isolation: The concept of isolation ensures that changes made in one branch do not immediately reflect in the main branch, providing a controlled environment for content development&nbsp; - Role in Controlled Content Modifications: Branches allow developers&nbsp;to test changes methodically, facilitating version control and preventing unintended disruptions to the live content.<h2>Example:</h2>Imagine a team of developers working on a large-scale website project using Contentstack as their content management system (CMS). Here's how they can effectively utilize the concept of "Branches" within Contentstack:<ol><li>Testing New Features: When the team wants to implement new features or design changes to the website, they can create a separate branch within Contentstack. This branch is a sandbox environment where developers can experiment with different ideas without affecting the live website.</li><li>Quality Assurance: Before deploying any changes to the live website for a new feature, the team can thoroughly test them in the branch environment. This ensures that any bugs or issues are identified and resolved before they impact the user experience on the live site.</li><li>Collaborative Development: Branches facilitate collaboration among team members by providing a centralized platform for making and reviewing changes to content types. Developers, designers, and content editors can all work together within their respective branches, sharing feedback and iterating on improvements.</li></ol>

Branches in Contentstack

<h2>Creating Branches and Forking from the Main Branch</h2>To harness the power of branches, users need to understand how to create them and fork them from the main branch. This part of the module will guide users through the practical steps involved in initiating and establishing a new branch as an independent workspace.<h3>Key Steps:</h3>&nbsp; - Creating a New Branch: Users will learn the step-by-step process of creating a new branch within Contentstack, defining its purpose, and configuring its settings.&nbsp; - Forking from the Main Branch: The concept of forking involves duplicating the main branch to create a starting point for a new branch. This ensures that the new branch inherits the existing content structure.&nbsp; - Initial Setup and Configuration: Exploring the initial setup involves understanding how to configure the new branch, set permissions, and establish connections with other modules.<h2>Source Branch Concept</h2>To navigate the world of branches effectively, it's essential to grasp the concept of the source branch. This part of the module will delve into the intricacies of the source branch, explaining its role in influencing subsequent branches and determining the initial set of inherited data.&nbsp; - Definition and Role of Source Branch: The source branch is called the&nbsp;main and acts as the parent from which new branches inherit their initial content structure and data.&nbsp;&nbsp; - Inherited Data from the Source Branch: Content types, global fields, entries, assets, languages, webhooks, and extensions are among the elements inherited by child branches from the source branch. The versions of the content in the main branch are used at the time of the new branch creation and are not updated in the forked branch when the main branch changes.&nbsp; - Establishing Source Branch Relationships: Users will understand how to define and establish relationships between source and child branches, ensuring a structured workflow.<h2>Inheriting Data in Branches</h2>Understanding Source Branch and Inherited DataWhen working with branches in Contentstack, comprehending the relationship between the source branch and inherited data is crucial. This section delves into how child branches inherit their initial content structure from the designated source branch.&nbsp; - Role of Source Branch: The source branch acts as the origin or parent branch from which subsequent branches inherit their foundational content structure.&nbsp;&nbsp;&nbsp; - Inherited Data Flow: An exploration of the seamless data flow from the source branch to child branches, ensuring consistency in content models.- Impact on Workflow: Understanding how the source branch influences the overall workflow of content creation and modifications in child branches.Example:Consider a scenario where a company's website has a standard template for product pages. By establishing a source branch with this template, any new branches created for specific product lines automatically inherit the standardized structure, streamlining the content creation process.Components Inherited: Content Types, Global Fields, Entries, Assets, Languages, Webhooks, and ExtensionsContentstack branches inherit various components from the source branch, each playing a crucial role in shaping the content structure. This part of the module explores the inherited elements, emphasizing their impact on content development.&nbsp; - Content Types: The blueprint for structuring content, ensuring consistency in data representation.&nbsp; - Global Fields: Elements shared across different content types, promoting uniformity in data entry.&nbsp; - Entries: Individual content instances within a content type, inherited to maintain a cohesive database.&nbsp; - Assets: Media files such as images and documents shared among different branches.&nbsp; - Languages: Supporting multilingual content creation, ensuring global reach.&nbsp; - Webhooks: Automated notifications facilitating real-time updates.&nbsp; - Extensions: Custom functionalities extending the capabilities of Contentstack.<h2>Independence of a Child Branch from the Parent Branch</h2>One of the key advantages of Contentstack branches lies in the independence they offer to child branches. This section explores how modifications made in a child branch do not directly impact the parent branch, facilitating a controlled and secure content development environment.&nbsp; - Isolation of Changes: Understanding how changes made in a child branch remain confined to that branch without affecting the source or other child branches.- Testing and Iteration: The ability to experiment and iterate in a child branch without immediate consequences on the live content.&nbsp; - Controlled Development Environment: Ensuring that content managers and developers can collaborate without disrupting ongoing processes in the source branch.Example: Suppose an e-commerce platform is introducing a new feature involving changes to the product catalog. By creating a child branch specifically for this feature, developers can make modifications, test functionality, and iterate without impacting the main product catalog in the source branch until the feature is ready for deployment.

Creating Branches Overview

<h3>Creating Branches with API Prerequisites:</h3><ol><li>API Key and AuthToken:Ensure you have the API key and <a href="https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens">authtoken </a>for your Contentstack account.</li><li>Contentstack Stack API Endpoint:Obtain the base API endpoint for your Contentstack stack.</li></ol><h2>Steps:</h2><h3>1. Authentication:</h3>Before making API calls, ensure you authenticate your requests by including the API key and authtoken in the headers.Headers: Content-Type: application/json api_key: YOUR_API_KEY authtoken : YOUR_AUTH_TOKEN <h3>2. Get Existing Branches (Optional):</h3>You can retrieve information about existing branches in your Contentstack stack if needed.<pre>GET /v3/stacks/branches</pre><pre>curl --location 'https://api.contentstack.io/v3/stacks/branches' \ --header 'api_key: ************************' \ --header 'authtoken: *********************' \ --header 'Content-Type: application/json' \ --data ''</pre><h3>3. Create a New Branch:</h3>To create a new branch, use the following API call:<pre>POST /v3/stacks/branches</pre><pre>Request Body: { &nbsp; "branch": { &nbsp; &nbsp; "name": "NewBranchName", &nbsp; &nbsp; "source": "SourceBranchID" &nbsp; } }</pre><ul><li>Replace "NewBranchName" with the desired name for the new branch.</li></ul><pre>Replace "SourceBranchID" with the ID of the branch from which the new branch should inherit its data. curl --location 'https://api.contentstack.io/v3/stacks/branches' \ --header 'Content-Type: application/json' \ --header 'api_key: ******************' \ --header 'authtoken: ****************' \ --header 'Content-Type: application/json' \ --data '{ &nbsp; &nbsp; "branch": { &nbsp; &nbsp; &nbsp; &nbsp; "uid": "dev", &nbsp; &nbsp; &nbsp; &nbsp; "source": "main" &nbsp; &nbsp; } }'</pre><h3>4. Response:</h3>Upon successful creation, the response will include details about the new branch, including its unique ID.<pre>{ &nbsp; "branch": { &nbsp; &nbsp; "uid": "NEW_BRANCH_ID", &nbsp; &nbsp; "name": "NewBranchName", &nbsp; &nbsp; "source": "SourceBranchID", &nbsp; &nbsp; // Other branch details... &nbsp; } } { &nbsp; &nbsp; "notice": "Your request to create branch is in progress. Please check organization bulk task queue for more details.", &nbsp; &nbsp; "branch": { &nbsp; &nbsp; &nbsp; &nbsp; "uid": "dev", &nbsp; &nbsp; &nbsp; &nbsp; "source": "main", &nbsp; &nbsp; &nbsp; &nbsp; "created_by": "***************", &nbsp; &nbsp; &nbsp; &nbsp; "updated_by": "***************", &nbsp; &nbsp; &nbsp; &nbsp; "created_at": "2024-01-23T12:42:23.260Z", &nbsp; &nbsp; &nbsp; &nbsp; "updated_at": "2024-01-23T12:42:23.260Z", &nbsp; &nbsp; &nbsp; &nbsp; "deleted_at": "in-progress", &nbsp; &nbsp; &nbsp; &nbsp; "alias": [] &nbsp; &nbsp; } }</pre><img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltb75e380c0f638072/664d4eaa78533908439e4fac/branches-token.png" alt="branches-token.png" height="auto"/><h3>5. Error Handling:</h3>Handle errors by checking the status code and the response body. Common error responses include details about what went wrong.<h3>6. Conclusion:</h3>With these API calls, you can seamlessly integrate branch creation into your Contentstack workflows, facilitating efficient collaboration and content development.<div style="position: relative;overflow: hidden;padding-bottom: 56.25%;"><iframe src="https://cdn.jwplayer.com/players/vt49kbc7-b769H14u.html" width="100%" height="100%" frameborder="0" scrolling="auto" title="Branches Create With Api Audio Revised" style="position: absolute;" allowfullscreen=""></iframe></div><h2>Creating Branches Using CLI</h2><h3>Prerequisites:</h3><ol><li>Contentstack CLI:<ul><li>Ensure you have the Contentstack CLI tool installed. You can install it from <a href="https://www.contentstack.com/docs/developers/cli/install-the-cli">https://www.contentstack.com/docs/developers/cli/install-the-cli</a>.</li></ul></li><li>API Key:<ul><li>Obtain the API key&nbsp;for your Contentstack stack.</li></ul></li></ol><h3>Steps:</h3><h3>1. Configure CLI:</h3>Before initiating any commands, configure the Contentstack CLI tool with your API key, access token, and stack ID.csdx auth:loginFollow the prompts to enter your API key, access token, and stack ID.<h3>2. Create a New Branch:</h3>Use the following command to create a new branch:<pre>USAGE &nbsp; $ csdx cm:branches:create &nbsp; $ csdx cm:branches:create [--source ] [--uid ] [-k ] &nbsp; $ csdx cm:branches:create [--source ] [--uid ] [--stack-api-key ]</pre><pre>FLAGS &nbsp; -k, --stack-api-key= &nbsp;Stack API key &nbsp; --source= &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Source branch from which new branch to be created &nbsp; --uid= &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Branch UID to be created</pre><pre>DESCRIPTION &nbsp; Create a new branch</pre><pre>EXAMPLES &nbsp; $ csdx cm:branches:create</pre><pre>&nbsp; $ csdx cm:branches:create --source main -uid new_branch -k bltxxxxxxxx</pre><pre>&nbsp; $ csdx cm:branches:create --source main --uid new_branch --stack-api-key bltxxxxxxxx</pre><ul><li>Replace new_branch with the desired name for the new branch.</li><li>Replace source with the ID of the branch from which the new branch should inherit its data.</li><li>Provide API key value to -k&nbsp;or&nbsp;--stack-api-key</li></ul><h3><img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt5ac58f90e15ecec3/67dc8839983a6519853b73d2/BranchesFoundations-L3-img-2.png" alt="BranchesFoundations-L3-img-2.png" height="auto"/></h3><h3>3. View Created Branch:</h3>Verify the successful creation of the branch by listing the existing branches:List the branches<pre>USAGE &nbsp; $ csdx cm:branches</pre><pre>FLAGS &nbsp; -k, --stack-api-key= &nbsp;Stack API Key &nbsp; --verbose &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Verbose</pre><pre>DESCRIPTION &nbsp; List the branches</pre><pre>EXAMPLES &nbsp; $ csdx cm:branches</pre><pre>&nbsp; $ csdx cm:branches --verbose</pre><pre>&nbsp; $ csdx cm:branches -k</pre>This command will display a list of branches associated with your Contentstack stack, including the newly created branch.<img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltff9181c58c6a9665/67dc886545b229efcb910ded/BranchesFoundations-L3-img-3.png" alt="BranchesFoundations-L3-img-3.png" height="auto"/><h3>4. Conclusion:</h3>Congratulations! You have successfully created a new branch in Contentstack using the CLI tool. This streamlined process allows for efficient management of content branches, fostering collaborative content development within your Contentstack environment.<div style="position: relative;overflow: hidden;padding-bottom: 56.25%;"><iframe src="https://cdn.jwplayer.com/players/dq5AxMiy-b769H14u.html" width="100%" height="100%" frameborder="0" scrolling="auto" title="Branches-create-in-ui" style="position: absolute;" allowfullscreen=""></iframe></div><h1>Creating a Branch with the UI</h1>To delve into the intricacies of creating a new branch, users are required to navigate through the Contentstack interface and adhere to a structured set of steps:<ol><li><h2>Accessing Branch Settings:</h2><ul><li>Log in to your Contentstack account and proceed to the settings panel.</li><li>Choose the "Branches" option to initiate the branch creation process. <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltc0d6b1880c4370b8/67dc888add73e3919fbf2be3/BranchesFoundations-L3-img-4.png" alt="BranchesFoundations-L3-img-4.png" height="auto"/> </li></ul></li><li><h2>Initiating New Branch:</h2><ul><li>Within the Branches section, locate the "+ New Branch" option situated in the top-right corner.</li><li>Click on this option to commence the creation of a fresh branch. <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt31eb048058c803d3/67dc88a398672543b08881e6/BranchesFoundations-L3-img-5.png" alt="BranchesFoundations-L3-img-5.png" height="auto"/></li></ul></li><li><h2>Completing the Create New Branch Form:</h2><ul><li>Upon selecting to create a new branch, a prompt directs users to the "Create New Branch" form.</li><li>Users are required to furnish the form with specific information to define the new branch. <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltf5c89f40d9347533/67dc88beb1a1f3c27c3ef06b/BranchesFoundations-L3-img-6.png" alt="BranchesFoundations-L3-img-6.png" height="auto"/></li></ul></li><li><h2>Essential Information in the Create New Branch Form:</h2><ul><li>Branch ID: Users must assign a unique identifier to the branch, facilitating a clear distinction.</li><li>Source Selection: From the provided dropdown menu, users must select the source branch from which the new branch will inherit its data. <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt99acc19d22f87666/67dc88d545b229e98e910df3/BranchesFoundations-L3-img-7.png" alt="BranchesFoundations-L3-img-7.png" height="auto"/></li></ul></li><li><h2>Finalizing the Branch Creation:</h2><ul><li>To conclude the branch creation process, users are instructed to click the "Save" button in the form's bottom-right corner.</li></ul></li></ol><img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt765540af59682c04/67dc88f4037e2ba01b22d1b3/BranchesFoundations-L3-img-8.png" alt="BranchesFoundations-L3-img-8.png" height="auto"/><img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blta7b764092858f5f6/67dc890df7eccc8c0490cfcd/BranchesFoundations-L3-img-9.png" alt="BranchesFoundations-L3-img-9.png" height="auto"/> <div style="position: relative;overflow: hidden;padding-bottom: 56.25%;"><iframe src="https://cdn.jwplayer.com/players/175DqNI7-b769H14u.html" width="100%" height="100%" frameborder="0" scrolling="auto" title="Branches-create-in-ui" style="position: absolute;" allowfullscreen=""></iframe></div><h2>Further Reference</h2><ul><li><a href="http://www.contentstack.com/docs/developers/apis/content-management-api#create-a-branch">Creating a branch using API</a></li><li><a href="https://www.contentstack.com/docs/developers/cli/compare-and-merge-branches-using-the-cli#create-a-branch">Creating a branch using CLI</a></li><li><a href="https://www.contentstack.com/docs/developers/cli/compare-and-merge-branches-using-the-cli#list-branches">Listing Branches using CLI</a></li><li><a href="http://www.contentstack.com/docs/developers/branches/create-a-branch">Creating a Branch using UI</a></li></ul>

Creating Branches

Working with Branches | About Aliases

<h1>Deleting Branches Using the CLI</h1><h2>1. Identify the Branch ID:</h2>Retrieve the ID of the branch you want to delete.<h2>2. Use the CLI Command:</h2>Delete a branchUSAGE &nbsp; $ csdx cm:branches:delete [-uid ] [-k ] &nbsp; $ csdx cm:branches:delete [--uid ] [--stack-api-key ]FLAGS &nbsp; -k, --stack-api-key= &nbsp;Stack API key &nbsp; -y, --yes &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Force the deletion of the branch by skipping the confirmation &nbsp; --uid= &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Branch UID to be deletedDESCRIPTION &nbsp; Delete a branchEXAMPLES &nbsp; $ csdx cm:branches:delete&nbsp; $ csdx cm:branches:delete --uid main -k bltxxxxxxxx&nbsp; $ csdx cm:branches:delete --uid main --stack-api-key bltxxxxxxxx&nbsp; $ csdx cm:branches:delete --uid main --stack-api-key bltxxxxxxxx --yes<img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt78563255bd9268cc/67dd7e810c6f5553861fcef1/BranchesFoundations-L5-img-1.png" alt="BranchesFoundations-L5-img-1.png" height="auto"/><h2>3. Verify Deletion:</h2>Confirm the successful deletion by checking the list of branches or using the appropriate CLI command to list branches.csdx cm:branches -k<img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt667ca21ead42a562/67dd7ea2c5b83e650e924b8e/BranchesFoundations-L5-img-2.png" alt="BranchesFoundations-L5-img-2.png" height="auto"/><h2>Conclusion:</h2>Following these step-by-step instructions, you can seamlessly delete branches in Contentstack using&nbsp;the CLI tool. <div style="position: relative;overflow: hidden;padding-bottom: 56.25%;"><iframe src="https://cdn.jwplayer.com/players/ItoHx0Zc-b769H14u.html" width="100%" height="100%" frameborder="0" scrolling="auto" title="Branches Delete With Api" style="position: absolute;" allowfullscreen=""></iframe></div><h1>Deleting Branches Using API Calls</h1><h2>1. Identify API Key and authtoken and Branch ID:</h2><ul><li>Obtain the API KEY of the stack for the branch you wish to delete.</li><li>Obtain the authtoken for the user.</li><li>Obtain the unique ID of the branch you wish to delete.</li></ul><h2>2. Make API Call:</h2>DELETE /v3/stacks/branches/{branch_id}<pre>Replace {branch_id} with the ID of the branch you want to delete. curl --location --request DELETE 'https://api.contentstack.io/v3/stacks/branches/dev?force=true' \ --header 'api_key: **************' \ --header 'authtoken: *************' \ --header 'Content-Type: application/json' \ --data ''</pre><h2>3. Response:</h2>Upon successful deletion, the response will confirm the removal of the specified branch.<pre>{ &nbsp; &nbsp; "notice": "Your request to delete branch is in progress. Please check organization bulk task queue for more details.", &nbsp; &nbsp; "branch": { &nbsp; &nbsp; &nbsp; &nbsp; "uid": "dev", &nbsp; &nbsp; &nbsp; &nbsp; "source": "main", &nbsp; &nbsp; &nbsp; &nbsp; "created_by": "******************", &nbsp; &nbsp; &nbsp; &nbsp; "updated_by": "*******************", &nbsp; &nbsp; &nbsp; &nbsp; "created_at": "2024-01-23T09:13:09.739Z", &nbsp; &nbsp; &nbsp; &nbsp; "updated_at": "2024-01-23T09:13:10.714Z", &nbsp; &nbsp; &nbsp; &nbsp; "deleted_at": false, &nbsp; &nbsp; &nbsp; &nbsp; "alias": [] &nbsp; &nbsp; } }</pre><img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltc2f10243ea60bd3f/67dd7ebbc566ee10565e0075/BranchesFoundations-L5-img-3.png" alt="BranchesFoundations-L5-img-3.png" height="auto"/><h1>Deleting Branches Using UI</h1><h2>1. Navigate to Branch Settings:</h2><ul><li>Log in to your Contentstack account.</li><li>Access the settings panel.</li><li>Choose "Branches" to view a list of existing branches. <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt0c0aed4460902b62/67dd7ed3983a65c6393b7c44/BranchesFoundations-L5-img-4.png" alt="BranchesFoundations-L5-img-4.png" height="auto"/></li></ul><h2>2. Select Branch for Deletion:</h2><ul><li>Locate the branch you want to delete from the list.</li><li>Click on the branch to select it. <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltf713e8213a26cb19/67dd7ee9782bfb67eb6f5634/BranchesFoundations-L5-img-5.png" alt="BranchesFoundations-L5-img-5.png" height="auto"/></li></ul><h2>3. Delete Branch:</h2><ul><li>Once the branch is selected, look for the option to delete the branch (usually represented by a trash/bin icon).</li><li>Confirm the deletion when prompted. <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltdba319de396dc790/67dd7efe0c6f5566621fcf14/BranchesFoundations-L5-img-6.png" alt="BranchesFoundations-L5-img-6.png" height="auto"/> <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blte6fc933625df28b1/67dd7f134a89c3933aa3030b/BranchesFoundations-L5-img-7.png" alt="BranchesFoundations-L5-img-7.png" height="auto"/> <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt36345100a21a082c/67dd7f36782bfb67156f5641/BranchesFoundations-L5-img-8.png" alt="BranchesFoundations-L5-img-8.png" height="auto"/></li></ul><div style="position: relative;overflow: hidden;padding-bottom: 56.25%;"><iframe src="https://cdn.jwplayer.com/players/175DqNI7-b769H14u.html" width="100%" height="100%" frameborder="0" scrolling="auto" title="Create Branches in the UI" style="position: absolute;" allowfullscreen=""></iframe></div><h1>Further Reference</h1><ul><li><a href="https://www.contentstack.com/docs/developers/branches/delete-a-branch">Deleting a branch</a><a href="http://www.contentstack.com/docs/developers/branches/delete-a-branch">&nbsp;using CLI</a></li><li><a href="http://www.contentstack.com/docs/developers/apis/content-management-api#delete-a-branch">Deleting a branch using API</a></li><li><a href="http://www.contentstack.com/docs/developers/branches/delete-a-branch">Deleting a branch using UI</a></li></ul>

Deleting a Branch

Comparing Branches

Merging Branches

<h2>Environments</h2>An environment in Contentstack refers to the content delivery destination where you publish and deploy the entries of your application or website.When you create an environment, it acts as a target for publishing your content. For example, you might have separate development, staging, and production environments.Environments allow you to manage different deployment scenarios and ensure your content reaches the right place.<a href="https://www.contentstack.com/docs/developers/set-up-environments/add-an-environment">Note: When working within branches, any environment created within a branch will be available across all the other branches of the stack</a>.

 <h2>Branches</h2>Branches enable you to manage your work effectively by separating “in-progress” work from live and stable jobs in the production environment.Instead of working sequentially, teams can work in parallel using branches, which is especially beneficial in aiming for higher release velocity.Changes made within different branches do not affect the main branch, allowing for isolated development and testing.<a href="https://www.contentstack.com/blog/product-updates/management-development-workflows-branches">In summary, branches facilitate collaboration, version control, and streamlined workflows within your Contentstack project</a>.
 1. Environments for Content Preview on UAT:

 &nbsp;&nbsp; -&nbsp;Purpose: Environments serve as staging areas where content changes can be previewed before they are deployed to the live production environment. The UAT (User Acceptance Testing) instance, in particular, allows stakeholders to review and validate content updates, ensuring they meet the desired standards and do not introduce any issues.

 &nbsp;&nbsp; -&nbsp;Workflow: Content changes are first implemented and tested in a&nbsp;preview&nbsp;environment. Once validated, they are promoted to the UAT environment for further scrutiny. Stakeholders such as content editors, quality assurance teams, and project managers can access the UAT instance to preview the changes and provide feedback. After any necessary adjustments, the approved changes are finally deployed to the live production environment.

 &nbsp;&nbsp; -&nbsp;Benefits: Using environments for content preview on UAT helps minimize the risk of introducing errors or inconsistencies to the live site. It provides a controlled environment for testing and validation, allowing stakeholders to ensure that the content changes align with business requirements and user expectations before they go live.

 2.&nbsp;Branches for CI/CD in Content Modeling:

 &nbsp;&nbsp; -&nbsp;Purpose: Branches are utilized within a CI/CD (Continuous Integration/Continuous Deployment) process to facilitate collaborative content modeling and integration changes. Developers create separate branches, such as a Dev branch, to work on specific features or updates without affecting the main production environment.

 &nbsp;&nbsp; -&nbsp;Workflow: Developers start by creating a Dev branch from the existing setup. They then implement content modeling changes, integration enhancements, and other modifications within this isolated environment. Automated testing and manual validation ensure the changes meet quality standards and do not disrupt existing functionality. Once validated, the changes are merged into the main branch, where the live editorial team can review and approve them for deployment to the production environment.

 &nbsp;&nbsp; -&nbsp;Benefits: Branches streamline content development by providing a structured approach to managing changes. They enable developers to work independently on different features or enhancements, reducing the risk of conflicts and allowing for parallel development efforts. By incorporating CI/CD practices, teams can ensure faster and more reliable deployments of content&nbsp;types change&nbsp;updates.

 3. Environments for Content Segregation:

 &nbsp;&nbsp; -&nbsp;Purpose: Environments can be leveraged to segregate content based on specific use cases or platform requirements. For example, organizations may need to deliver platform-specific content tailored for mobile and web environments. Creating separate environments associated with each platform allows content to be managed and delivered independently, ensuring a consistent and optimized user experience across different channels.

 &nbsp;&nbsp; -&nbsp;Workflow: Content authors create and manage platform-specific content within designated environments, each configured with its delivery token. This token is used to authenticate requests and ensure content is delivered to the appropriate platform. Content segregation allows for granular control over content distribution, enabling organizations to tailor content strategies and optimize engagement based on the characteristics of each platform.

 &nbsp;&nbsp; -&nbsp;Benefits: Utilizing environments for content segregation enables organizations to manage and deliver platform-specific content effectively. It supports targeted content delivery, enhances user engagement, and simplifies content management workflows by providing dedicated environments for each platform-specific use case.

Environments and Branches

<h1>Blue-Green Deployment with Branches (CI CD Automation &amp; Branch Strategy)</h1>ContextThe idea here, or the use case, rather, is to be able to somehow streamline the development process both from a content management perspective as well as from a front-end perspective (code) and to be able to automate most of itProposed Branching Strategy<img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt80669c6c79b6ff1f/67dd863ac5b83eaf0b924c25/BranchesFoundations-L9-img-1.png" alt="BranchesFoundations-L9-img-1.png" height="auto"/>CI CD Implementation Approach and ChallengesThe SA team has implemented a simple workflow to illustrate the findings above. Such workflow consists of:<ol><li>Frontend repository is hosted on GitHub</li><li>Two Github Actions have been developed.</li><li>The development process in such a repo starts on the development branch, and for each new development iteration, a features/xxxx is created.<ol><li>This provides an entry in Contentstack containing information about current developments.</li><li>This entry also has a workflow, which can be leveraged to synchronize global fields, content types, and content using an automation hub.</li></ol></li><li>At that point, both code and content changes can take place.</li><li>Once the code changes are completed, The feature branch is merged back to develop.</li><li>The Content Management Workflow for merging occurs in the CMS, combining workflow stages and AH Automation.</li></ol>The full&nbsp;Automation flow is as follows: <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/bltec19c524ad6f85ac/67dd8656db243fa79d12c3be/BranchesFoundations-L9-img-2.png" alt="BranchesFoundations-L9-img-2.png" height="auto"/>Gaps on AH<ul><li>Most of the required logic happens in code blocks, as the built-in actions don’t support certain functionality. Attempting to implement usable loops and conditional execution natively in AH would be cumbersome if possible.</li><li>Timeouts and API limits can occur, and since it’s all “Javascript Code Blocks,” the developer would need to deal with all this.</li><li>Developer experience on Code Blocks is very poor. Understandably, such blocks are not meant for full-blown development. For such reasons, most developers will resort to external services, rendering AH unnecessary beyond its usage as a webhook trigger.&nbsp;</li></ul>Gaps in the API/CLI<ul><li>Create and Update works and can potentially be used for parts of the workflow above (content type and global fields merge). Content without asset/reference changes can also be merged.<ul><li>Implementing all the possible field updates (embedded items in JSON RTE, asset fields, reference fields, etc…) will require more logic to be developed.</li></ul></li><li>Alternatively, we could use Merge &amp; Compare for the above,&nbsp; however, the fact that content can’t be merged poses a problem in these pipelines as most of the changes are potentially gonna be content. I.e., 2-5 content types/global field changes vs. dozens of content updates in that period.</li><li>Entry creation/update requires a lot of preprocessing when it comes to dealing with asset and reference fields besides the dependency hierarchy management for those fields can become tedious as well (i.e., first updated global fields, then content types, first assets, then referenced entries, then top-level entries)</li><li>When doing this at scale, API limits will pose a problem, too.</li></ul><h1>Streamlined CI/CD process for Contentstack Development Lifecycle (CDL) using Branch Merge Compare, Workflow, and Automation Hub</h1><h2>Problem Statement&nbsp;</h2>The Contentstack Branch Merge and Compare feature is an essential setup for the CI/CD process. We do have Merge and Compare via CLI, but there is a big gap to streamlining content type merge through UI with proper review process as this bring potentially big change to the production site.<ul><li>Review Branch Comparison to choose the correct Merge strategy through UI</li><li>Merge branch Changes using the Workflow trigger feature with a proper review process and accessibility to specific roles&nbsp;</li><li>Get details on merge failure reasons</li><li>Migrate bulk Entries from one branch to another based on new content type</li><li>Generate pull requests for GitHub code to move changes from the dev branch to the main branch</li><li>Smooth Rollback in case of breaking changes in an automated way to bring the Contentstack branch and GitHub branch to the previous state.</li></ul><table><tbody><tr><td>Drawbacks in Existing merge flow</td><td>Benefits of this new merge flow</td></tr><tr><td>The user should have a technical background due to CLI</td><td>No technical background is required after the setup</td></tr><tr><td>Time-consuming</td><td>Fast</td></tr><tr><td>There is no authorization flow during the merge</td><td>Proper authorization flow</td></tr><tr><td>No intimation after the merge operation about failure reasons</td><td>Notification System to send email with merge operation results</td></tr></tbody></table><h3>Use cases while working with Branches.</h3><ol><li>Streamlining Content and Code Development Life Cycle through automated CI/CD pipeline Mechanism</li><li>Proper Authorisation Review workflow Process for major Content model changes for production using custom roles.</li><li>Notification System in place for Review and merge operation using Automation hub.</li><li>Quick and Easy way to back in case of breaking merge changes</li></ol><h2>Solution overview</h2><ol><li>Branch Merge Configuration using Merge Configuration Entry</li><li>Workflow Stage to trigger branch merge</li><li>Custom Role for Accessibility</li><li>Automation Hub Actions<ol><li>Merge Content type/Global field</li><li>Send Email Notification with merge summary and merge success and Failure details.</li><li>Migrate Entries to the target branch</li><li>GitHub Pull Request for Code Merge</li><li>Deploy UI Change using Launch/vertical/netlify</li></ol></li></ol><h3>Flow Diagram <img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt6cd7aac9f5106525/67dd866fefd8a90c434c0188/BranchesFoundations-L9-img-3.png" alt="BranchesFoundations-L9-img-3.png" height="auto"/></h3><h3>Streamlined UI Flow</h3><img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt84d66286aabbd951/67dd8687782bfb3b536f56bf/BranchesFoundations-L9-img-4.png" alt="BranchesFoundations-L9-img-4.png" height="auto"/><img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt46251d40a3c8c5b6/67dd869ba6d88e2310053555/BranchesFoundations-L9-img-5.png" alt="BranchesFoundations-L9-img-5.png" height="auto"/><img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt44a323f214288c3b/67dd86b10c6f55d8081fcf9c/BranchesFoundations-L9-img-6.png" alt="BranchesFoundations-L9-img-6.png" height="auto"/><h1>Branches Real-world Scenarios</h1><a href="https://www.contentstack.com/docs/developers/branches/about-branches">Branches</a>&nbsp;allow you to make changes and iterate your work without the risk of impacting the content deployed on production. Thus making it easier for developers to work on multiple releases simultaneously.Let's examine the following use cases to learn how to work with Branches in Contentstack.<h2>Example 1: Use branches for in-progress and production content</h2>Before branches, developers maintained different stacks, one for development and another for production content. These multiple cloned stacks in your organization made it difficult for developers to migrate their changes to production.With branches, you can reduce the stacks in your organization by maintaining the development and production branches within one stack.To achieve this, you must create a development branch within your production stack and select the production (main) branch as your source branch.<img src="https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt2cd3dab330db00c3/67dd86cba6d88e49ad053559/BranchesFoundations-L9-img-7.png" alt="BranchesFoundations-L9-img-7.png" height="auto"/>The development branch will now have a copy of all the content from the main branch (production). With this development branch, the developers can modify the structure, add new changes, iterate, and publish in a testing environment to preview the recent changes.Additional Resource:&nbsp;To create a new branch, read our doc on&nbsp;<a href="https://www.contentstack.com/docs/developers/branches/create-a-branch">creating a branch</a>.You can compare the differences between the development and main branches in content types and global fields. Once satisfied with the changes, you can merge the development branch into the main one.Additional Resource:&nbsp;Refer to our&nbsp;<a href="https://www.contentstack.com/docs/developers/branches/get-started-with-comparing-and-merging-branches">Get Started with Comparing and Merging Branches&nbsp;</a>documentation to learn more about comparing and merging branchesWhen merging, a backup of the branch you are merging into (in this case, the main branch) is created by default before the merge action takes place. If you use aliases, you can easily point the alias to this backup branch to quickly switch back to how things were before the merge occurred.Additional Resource:&nbsp;To learn how to assign a new alias or modify an alias, read our doc on how to&nbsp;<a href="https://www.contentstack.com/docs/developers/branches/assign-an-alias-to-a-branch">Assign an Alias</a>&nbsp;or&nbsp;<a href="https://www.contentstack.com/docs/developers/branches/edit-an-alias">Edit an Alias</a>.<h2>Example 2: Use branches to redesign your website</h2>Suppose you want to redesign the entire website. Traditionally you would clone the stack and make changes in the cloned model. However, with numerous content types and stacks, keeping track of the original content and the cloned one becomes difficult.With the use of branches, you can redesign or restructure your website with great ease. You only need to create a branch named "redesign" and select the existing content (main) branch as your source branch.<img src="https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/blt4d0886f379752ad3/64802acdd242046f041ca2eb/About_Branches.png" width="100"/>You can make structural changes to your content types and global fields in the redesigned branch. Once satisfied with your changes, you can compare the differences and merge the redesigned branch into the main branch using the overwrite with compare strategy to completely replace the main (base) branch with the newly redesigned changes from the redesign (compare) branch.Note:&nbsp;The&nbsp;<a href="https://www.contentstack.com/docs/developers/branches/comparing-branches">Compare</a>&nbsp;and&nbsp;<a href="https://www.contentstack.com/docs/developers/branches/merging-branches">Merge</a>&nbsp;feature only compares and merges differences between content type and global field modules and is only available via&nbsp;<a href="https://www.contentstack.com/docs/developers/apis/content-management-api/#comparing-branches">Content Management API</a>&nbsp;and&nbsp;<a href="https://www.contentstack.com/docs/developers/cli/compare-and-merge-branches-using-the-cli/">CLI commands</a>.<h2>Example 3: Use branches to prevent data loss</h2>Consider a developer who restructures the content model of an existing production website. Not aware of these recent changes, a content manager updates the content and publishes it to production.Due to unintentional changes, the production website may break, resulting in content loss.You can correct this minor error by restoring the previous version. However, if the developer had restructured many content types, this may be a tedious restoration activity.With branches, one can avoid costly website errors and prevent data loss.To do so, the developer can create a new branch named "test" and select the main or desired branch as the source branch.<img src="https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/blt9dcb87cd13a3ad55/64802f3e352ac607a8da1952/Branches_Real-WorldScenarios_Ex_3.png" width="100"/>The content of the source branch will now be available in the test branch. The developer can iterate the content model with great ease.Then, when the content looks good, use an alias to reflect the new changes on the production website.Once you are done and satisfied with your changes, you can compare and merge the two branches.<h2>Example 4: Integrate branches and&nbsp;aliases with CI/CD for an instant release rollback capability</h2>Many development teams in the CI/CD pipeline use Git-based branching methods to maintain consistent code integration across the developer workflow. Once the integration is done, CD tools automate application code deployment to the desired environment (e.g., production).With branches and aliases, developers can maintain production content across branches without affecting live website data. Content managers can publish content changes to a website without the assistance of a development team to pull content from Contentstack and display it on a presentation layer.Aliases can always point back to the previously referenced content branch in case of unintentional content deployment. This flexibility allows developers to roll back changes instantly. Here, CI/CD can integrate with the CMS to automate rollback for such content changes.Additional Resource: Refer to our&nbsp;<a href="https://www.contentstack.com/docs/developers/branches/use-branches-and-aliases-to-drive-continuous-integration-and-deployment">Use Branches and Aliases to Drive Continuous Integration and Deployment</a>&nbsp;document to learn how branches and aliases help integrate Contentstack with standard CI/CD practices.Let's consider a scenario where we need to change production data for a live website.To integrate Contentstack with your CI/CD strategies to facilitate consistent, hassle-free content deployment to the live website, you can follow the below steps:Create a copy of the&nbsp;main&nbsp;branch content in a separate branch to change your production data. The child branch you create inherits all of the content types, entries, assets, languages, extensions, releases, etc., that were part of the parent branch as it is.<img src="https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/blt5dd3895967c419e4/64803004e73df5eeaea6e696/Branches_Real-WorldScenarios_Ex_4.png" width="100"/> <ol><li>Assign an alias to the "production" branch with the alias ID "deploy," for instance. This alias will help fetch and display data from the target branch on the live website.</li><li>Specify an alias ID in the frontend code against the branch key to tell the application where it needs to fetch content. Whichever branch is associated with that alias ID becomes the production environment's main branch. For instance, we pass the "deploy" alias ID here to fetch data from the "production" branch.</li><li>Change content types, entries, assets, etc., present on a branch (e.g., "development") without affecting your "production" branch data. You can test the changes until they are ready to deploy to production.</li><li>Once the "development" branch changes are ready to go, you can use two different ways to apply the changes to production data:<ul><li>For minor changes,&nbsp;such as adding or removing a few fields, you can use the Contentstack CLI to apply these changes to the "production" branch.</li><li>For major changes&nbsp;such as redesigning the marketing website, you can use an alias to point to the “development” branch to test your new changes. Once satisfied with your changes, you can merge the development (compare) branch into the production (base) branch. </li></ul><img src="https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/blt74fb9a049d62588d/64ab91a2873fa3a3b302f906/Edit_Alias.png" width="100"/></li></ol>The default behavior when merging will create a backup of the branch you are merging into for safety. You can use this to quickly revert your site if there is an issue with the merge via an alias. With flexible release rollback capabilities, branches allow Contentstack to align with your CI/CD pipeline and strategies.Additional Resource:&nbsp;To understand comparing and merging branches, please read our end-to-end guide on&nbsp;<a href="https://www.contentstack.com/docs/developers/branches/get-started-with-comparing-and-merging-branches/">Getting Started with Comparing and Merging Branches.</a>

Case Studies With Branches

<ul><li>This feature will be plan-based.</li><li>The branch UID must be in lowercase, and only ‘_’ can be used to separate two words.</li><li>The maximum number of branches allowed per stack will depend on the product tier.</li><li>Once you create a branch, you cannot edit its name or source branch.</li><li>The maximum character length for a branch ID is&nbsp;15</li><li>You cannot edit the name of the main branch.</li><li>You cannot delete a branch used as a source branch.</li><li>The Compare and Merge features are currently available only through CMA and CLI for the content type and global field modules only.</li></ul><h1>Limitations of Aliases</h1><ul><li>This feature will be plan based.</li><li>The alias UID must be in lowercase and only ‘_’ can be used to separate two words.</li><li>The alias UID and branch UID cannot be the same.</li><li>Once you create an alias, you cannot edit its name.</li><li>The maximum number of aliases allowed per stack will depend on the product tier.</li><li>The maximum character length for an alias name is&nbsp;15</li></ul><h1>FAQ</h1>Please take a moment to browse our Frequently Asked Questions (FAQ) for quick answers to common queries. Whether you're curious about branches, aliases, or services, our FAQ page provides comprehensive information to help address your concerns.<a href="https://www.contentstack.com/docs/faqs#branches-faqs">Click here to explore our FAQ now</a>.

Limitations of using Branches

<h1>Branches Foundations</h1>This course will outline the Contentstack features and techniques for using Branches with your Contentstack implementation. Completion of this course earns a 'badge' for this topic.<h2>Pre-requisites for this course</h2><ol><li>Account in Contentstack with access to a Stack as an Administrator or Developer. Create a training Stack <a href="https://www.contentstack.com/academy/">here</a>. Training stacks are available for 90 days. Alternatively, you can bootstrap a <a href="https://www.contentstack.com/docs/developers/cli/bootstrap-starter-apps">Starter App via the CLI</a> or the&nbsp;<a href="https://app.contentstack.com/#!/marketplace/starters">Marketplace</a>.&nbsp;</li><li>Permission to create new Content Types and Branches in a Stack.&nbsp;</li></ol>

Understanding Taxonomy

This course teaches developers how to get the most our of the Branches feature in Contenstack.