Continuous Integration with TeamCity – supporting multiple branches

Everybody will agree that nowadays Continuous Integration (CI) process established on project is as usual as Version Control System (VCS) for source code. Actually both are tightly coupled – CI server takes source code from VCS and runs all the pre-configured by build engineer magic: source code compilation, automated tests run, installation package preparation, etc.

Here at ELEKS we get used to TeamCity. In this and following posts I’ll share our experience with using TeamCity. When mentioning VCS I’ll refer to Git. Still, most of described also apply to Subversion and other VCS.

First common problem that we'll discuss – establishing CI process for multiple branches of source code: usually for development and release branches.

The beginning

Development is started. Source code repository setup completed. After several days of development, when there is something to build, we add a TeamCity Project and several configurations to this Project:

Time flows; more code is being committed into source control. More TeamCity configurations are being added:

After half a year of development we already have 40 configurations. These configurations were created and evolved together with source code. Because all the time we worked only on single development branch (called master) everything was simple and fine. But now we have to make code-freeze and introduce a release branch which brings new problems to solve:

1. We have to run continuous integration process for both master and release branches.
2. From time to time we have to merge fixes from release branch into master branch and vise-versa.

Continuous Integration for release branch

For a single branch we had 40 TeamCity configurations. For two branches we must have 40 + 40 = 80 ones. Or can we have only 40 configurations but run them either for master or release branch? Short answer: we didn’t find a reliable way how to do this. Besides, it is nice to have configurations for different branches running in parallel and for this feature we must have a copy of these configurations so each branch can be independent. 

How can we quickly get these 40 extra configurations? At the time we make a release branch from master branch it is obvious that they must be the exact copy of existing 40 configurations developed for master branch. Thankfully, TeamCity offers a way to clone whole Project with all its configurations.

Before cloning Project1 project make sure that VCS root referenced by configurations of this project is shared. Look at the bottom of Edit VCS Root page:

Now go to Project1 settings:

Click Copy:

Name new project as Project1-release and confirm. Rename old Project1 to Project1-master.

At this point Project1-release is the exact copy of Project1-master. The last thing to do is to change VCS root branch. Click on any configuration in Project1-release (for example on build-app-debug), click Edit Configuration Settings and select Version Control Settings:

Edit VCS root – change VCS root name to repo-release and Ref name to release (Ref name stands for branch name there). Scroll to the very bottom of Edit VCS Root page:

Make sure “Apply to all templates & configurations of Project1-release project where this VCS root is used (a copy of this VCS root will be created)” option is selected! Click Save.
Now all configurations from Project1-release project have VCS root that points to release branch. If you have more than one source code repository, for example you are using git sub-modules, you have to perform VCS root editing steps for each VCS root.
Please note that described technique works as long as all your configurations reside within single TeamCity Project! If, for some reason, you split configurations between two TeamCity Projects (say Project1-build and Project1-tests) – you are in trouble when applying copy project technique, especially if you have more than one VCS root.
Congratulations. We have two TeamCity projects and two VCS roots, each references different code branch. We can commit code either to master or release branch and run corresponding TeamCity configurations in parallel (...if you have multiple Build Agents, otherwise they’ll be queued).
Of course having two almost exact clones of TeamCity configurations doesn’t feel “right”. But it works!

New development and new release

First version of the product released. Developers continue to work on master branch. They add new code, write new tests. As a result more TeamCity configurations are created; some existing configurations are changed (extra build step added, some steps changed, new artifacts dependencies used, etc.). Master branch and Project1-master TeamCity project are evolving together – when some TeamCity configuration is broken build engineer fixes it. What is important is all this evolving process – source code is under source control but your TeamCity projects and configurations are not.

Sometimes we make fixes to release branch. Usually these are only bug-fixes, no new functionality is introduced – no reason to touch Project1-release configuration.

Three months later a new release comes. Team lead merges code from master branch into release branch and… a lot of configurations in Project1-release project do not work! Moreover, some configurations are missing. Of course they are missing – they were added to Project1-master but not to Project1-release.

Here is the most simple and reliable way of fixing Project1-release – just remove it and create a new copy of Project1-master! But consider following side effects: Project ID, Configurations IDs and VCS root IDs will change. If your automation tools rely on these IDs you have to reconfigure these tools. Actually, these are ways to preserve VCS root IDs – the most quick and reliable solution envisions manual editing of TeamCity project XML configuration file and TeamCity server restart. 

Alternatively you may reapply changes made in Project1-master to Project1-release manually using TeamCity WEB interface. But if number of changes is high the work quickly becomes tedious and error prone.

Conclusion

In this post we reviewed one of the possible ways of supporting CI process for multiple branches of source code. I do not say that described approach is ideal and you should immediately start using it; I blogged about it because it worked (and works) well on rather large project. We tried other ways of achieving flawless multiple branches CI – for example using TeamCity templates feature. But time showed that “clone whole project and VCS roots approach” is the most optimal solution by complexity/features criteria. If you’ve successfully applied "better" solution that solves multiple branches support issue – please share it in comments.