Semantic Git Branching for Android apps

Maxi Rosson
Jun 23, 2016 · 6 min read

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 about 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 to take into account some considerations when defining your git branches.

Main branches

I call main branches to the ones that represents a certain phase on 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 hot fixes.
  • beta This is the branch where the beta testing version is located. It is also used to commit your beta testing hot fixes.
  • rollout This is the branch where the staged rollout version is located. You also use it to commit your staged rollout hot fixes.
  • production This is the branch where the production version is located. Your production hot fixes commits goes 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 to 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 to checkout 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 of your development phase you need to freeze the code on the master branch in order to start a 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 in order to continue your alpha testing. And don’t forget to merge all your hot fixes, 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 in order to continue your beta testing. After this, you should merge your hot fixes 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 hot fix 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 stage 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 hot fix if they are currently active.

Full Rollout Release

When you finished the staged rollout and released the APK to the 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 hot fixes on each version. If you need to release a hot fix 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 some advices.

  • 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 a consistence between the content of your main branches and the published APKs.

Did you like this story?
Please recommend (by clicking the clap
👏 button) or share this story so other people can read it! You can also donate (by clicking the following Donate button) and help me to continue writing. Thanks!

I invite you to play Geo Seeker, my brand new android game.

Thanks to Julieta Milaragna

Maxi Rosson

Written by

Freelance Android Developer | My projects:, &

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade