Understanding branches

  • 12 August 2022
  • 4 replies

Userlevel 3

Hi there, my goal is to understand better the “Branches” functionality that CS has available. I am struggling to understand a few concepts after reading the documentation.


  1. This link here has the following: 

    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.

    What is unclear to me, is how the developer actually previews changes. I have created a branch off of main: “development”. Inside this development branch, I want to update an entry (this entry already exists because it came from main). I make my updates, and then I go to publish to the development environment.

    From my understanding, however, publishing to an environment seems useless unless you are using an alias. Unless you add the alias to the contentstack.Stack() sdk, you will always get the main branch’s content. Is my understanding correct here? What is the purpose of publishing on a separate branch if there is no alias?

  2. From the same link, the following is mentioned:

    Once you are entirely sure of the changes made, you can make the development branch act as the source branch for the production environment using an alias. Create a new alias and assign it to the development branch.

    So from my understanding, if I have an alias called “deploy”, and my intention is that the production website is always using this alias. The idea is that you make your new changes on your branch (in this case named Development), and when you’re happy with the changes, you swap the alias’s branch from main to development. 

    This is a bit of a weird concept to me, because now your production website will have an alias with the “development” branch applied to it. In actuality, do most people use release tags for branch names, vs development/production? I would think it would be weird to have production’s content coming from a source called “development”.

Hoping someone can help understand these usecases!


Thanks in advance!


Best answer by nick.nguyen 15 August 2022, 19:10

View original

4 replies

Userlevel 3

Just a quick FYI that the team is looking into this and should get back to you by Monday or so. Thanks!

Userlevel 4

Hey Tyler,

Branches are still in the early stages of development, and we are actively learning and improving the feature as time goes. 

Each branch has modules that are specific to its branch. 

Any child branch inherits all of the data from the source branch, including content typesglobal fieldsentriesassetslanguageswebhooksworkflowsextensions and tokens.

  1. To see publishing changes you would make the exact same API request as you would regularly but add in the additional parameter to specify the branch or alias you want to fetch from. Also you need to update the tokens you currently use to have access to that branch or alias you are looking to fetch from. 
    • You do not need an Alias. So you can post to a separate branch and pull directly from the Branch UID rather than an Alias UID.
    • An Alias helps you switch content between branches without having to update your code to point to a new branch because Contentstack handles that for you.
  2. The current use case that is supported is what you are describing. Others have named branches like production_one & production_two. Then they alternate between the two via an Alias. Mainly for content type changes.
    •  Right now we are working on creating better ways to migrate and bring changes from one branch into another. The process is not too user friendly at the moment, and would involve writing scripts to merge & update content types and entries into another branch. As stated though, the process of migration is being improved and hopefully will have some updates to share in the near future.



Userlevel 3

Hi @nick.nguyen 


Okay so my follow up question was going to be about the merging.


If my Developer is working on new content models in Branch A, and then the client is working on new content in Branch B, when it comes time to push Branch A live, there is no smooth way of getting content on Branch B into Branch A, correct?


So this would mostly have to be used if you were updating your website in stages… I would be interested in learning more about that road map feature for migrating between branches.

Userlevel 4

@Tyler correct, there is no one click migrations or in platform migrations today. It would all have to be done through our API’s at the moment. We are working on a user friendly way to migrate changes seamlessly. 

It definitely works best in incremental stages rather than continuous deployment. I can check with our product team, and get back to you with updates about the roadmap.