Semantic Git Branching for Android apps

There are so many ways to work with git branches and they usually vary according to the kind of project, development process and technologies being used. In this story, I want to propose an approach to git branching for android apps that are published on Google Play.

As you know, Google Play offers the ability to have multiple releases of your app published at the same time and targeting different user segments. I’m talking about the Alpha/Beta testing and the Staged Rollout tools. If you are currently using them, I suggest you take into account some considerations when defining your git branches.

Main branches

I call main branches the ones that represent a certain phase in your development cycle. Let’s talk a little bit about my suggestions.

  • master This is the branch where the development progresses. It always contains the latest cutting-edge version of the project, but therefore may also mean the most unstable version.
  • staging This is the branch where the next version to be released is located. Here the code is stabilized before publishing to Google Play.
  • alpha This is the branch where the alpha testing version is located. It is also used to commit your alpha testing hotfixes.
  • beta This is the branch where the beta testing version is located. It is also used to commit your beta testing hotfixes.
  • rollout This is the branch where the staged rollout version is located. You also use it to commit your staged rollout hotfixes.
  • production This is the branch where the production version is located. Your production hotfixes commits go here.

These are the most important branches you will have, so you need to be very careful about them. For example, they should never be removed or force pushed. If your code is hosted at Github then I recommend you protect these branches to avoid unexpected operations against them. You can read more about protecting branches on Github here.


Every time you release a new version, no matter if it is an alpha, beta, staged rollout or full rollout, you should create a tag on git from the branch you used to release it. Use your android version name to identify each tag. For example: v0.1.0, v1.2.0, v3.0.1. You can read my previous story about versioning android apps here.

Following this good practice will let you check out the code of any version to reproduce a bug, inspect the source code or whatever you need.


Now that we introduced the different main branches, let’s talk about the development workflow.

Code Freeze

At any point in your development phase, you need to freeze the code on the master branch to start regression testing or any kind of validation to stabilize the code. So, you merge the master branch to the staging one. From now on your master branch can start receiving commits for a future version at the same time you stabilize the version at the staging branch.

Alpha Release

On staging, you perform all your tests and validations until you are ready for your alpha testing. At this point, you merge your code from the staging to the alpha branch and then upload your APK to the Google Play Alpha Testing Program.

If you find any critical bug on your alpha version once released, you should use this alpha branch to commit the fixes, increment the version and publish a new APK to continue your alpha testing. And don’t forget to merge all your hotfixes, first from the alpha to the staging branch and then from the staging to the master branch.

Beta Release

Once you finish your alpha testing you should merge from the alpha to the beta branch. Then you are ready to upload your APK to the Google Play Beta Testing Program.

If you find any critical bug on your beta version, you should use this beta branch to commit the fixes, increment the version and publish a new APK to continue your beta testing. After this, you should merge your hotfixes from the beta to the alpha branch, then from the alpha to the staging branch and finally from the staging to the master branch. Given that your alpha branch was updated, it could be a good idea to also release a new alpha version to Google Play, so your alpha users also get the hotfix found on the beta testing. This is only required if you have both alpha and beta versions active at the same time.

Staged Rollout Release

After your beta testing is finished you should merge the code from the beta branch to the rollout branch. Now you are ready to perform a staged rollout on Google Play.

A critical bug on the staged rollout is resolved in the same way. You commit the fix on the rollout branch, publish the APK on Google Play and finally, you merge the rollout branch to the beta, alpha, staging and master branches. You also may need to publish new alpha and beta versions with the hotfix if they are currently active.

Full Rollout Release

When you finished the staged rollout and released the APK to 100% of your users, then you should merge from the rollout to the production branch.

After that, every critical bug in this version should be resolved on the production branch and merged to the other main branches.

As you can see, you could have multiple active versions published to Google Play at the same time. In the more complex scenario you could have something like this:

  • v1.0.0 on full rollout
  • v1.1.0 on staged rollout
  • v1.2.0 on beta testing
  • v1.3.0 on alpha testing

You can also have critical bugs that need hotfixes on each version. If you need to release a hotfix on your full rollout version, it’s possible that you also need to fix it on your staged, beta and/or alpha versions, generating the following configuration:

  • v1.0.1 on full rollout
  • v1.1.1 on staged rollout
  • v1.2.1 on beta testing
  • v1.3.1 on alpha testing


To sum up, I would like to give you some advice.

  • Define your main branches according to your needs. For example, you may not need an alpha branch if you don’t use Alpha Testing.
  • Tag each released version, no matter if it is an alpha or beta.
  • Merge the proper branches every time you release a version.
  • Always keep consistency between the content of your main branches and the published APKs.

This article contains Affiliate Links. If you purchase anything after clicking an affiliate link, I may receive some compensation.

If you want to learn Android, here you have some recommended books


Popular Posts

Circle CI + Android configuration tips

Versioning Android apps

Say bye-bye to Android Jetifier