Building a Feature Branch Configuration Template in TeamCity

Tweet

I don’t know about you, but sometimes we have frequent feature branches on our projects. Sometimes we don’t go through the trouble of setting up a build configuration in TeamCity if it’s a quick feature, but sometimes we like to see the pretty green checkbox in TeamCity when our build finishes successfully…especially when more than one person is working on the feature. We also like to deploy straight to our testing environments from a feature branch occasionally for testing, so it’s important for adding a build configuration quickly and accurately in TeamCity. I thought I’d give a demonstration on how to create one.

There are two ways to make a template. From scratch and from an existing build configuration. I will not talk about the “Extract Template” option because it’s literally clicking a button and giving a name from within the “Edit Build Configuration” screen. However, there are two things you’ll need to look at in order to use the extracted template as a feature branch template. So look at steps 2 and 4 below for the details if you have an existing build to use as a template.

Step 1: Click “Create template” under “Edit Project Settings” (I’m using version 7.0.4 of TeamCity btw)

Step 2: Fill in the name…I called mine Feature Branch Template (original I know). If you have a different build number per feature branch, which we do on this project, you can put %BuildNumber%.{0}.0 for the “Build number format”, otherwise, just leave it as the default (like below). Specify your “Artifact paths”, ours usually looks something like “build\latest\*.zip”. Click “VCS settings”.

Step 3: Here’s where the fun comes in…click “Create and attach new VCS root”.

Here you will select your VCS and fill in the appropriate information. The only VERY important thing you need to do is input “%BranchName%” into the Branch name. What this does is creates a parameter that will be required by your build configurations that use this template. Obviously we are using Mercurial, but you would just do the same as above for the equivalent of a branch in your source control.

When you’ve completed filling out the required information and tested the connection, Save. (Pro Tip: Don’t put %BranchName% in that field until after you’ve done “Test connection” with a real branch name.)

You should see this after saving:

Step 4: I’ll just leave all the defaults on the “Version Control Settings” screen, but if you require any of those settings, please set them if they apply to all your feature branches. Click “Add Build Step”.

Step 5: Configure your build steps. We only have two steps because we use psake…so basically we call the build.bat in our repo root with specific params and the other step just runs our unit tests with coverage.

Step 6 (optional): Configure fail conditions if needed…the most common condition I’ve seen is looking for specific text in the build log.

Step 7: Configure Build Triggering…we use the VCS Trigger, which detects when code is checked in. After clicking “Add new trigger”, you should see this:

I just use the default values. Click Save.

Step 8: Click Build Parameters – You should see BranchName <value is required> and BuildNumber if you specified that one in step 1.

If no BuildNumber specified:

If BuildNumber specified:

Okay, you’re done. Now you can start using the template…here’s how:

Under “Edit Project Settings”, click “Feature Branch Template”. In the bottom right, you should see this:

Step 1: Click “Create Build Configuration from Template”

Step 2: Give it a name…typically I name it the branch name.

Step 3: Now click Build Parameters on the right

Step 4: Click the <value is required> for the parameters you specified above and set the value. Click Save.

You’re done.

The way we were handling this before was by copying the build configuration and then creating a new VCS root with the appropriate branch name and add to remember to change the build number…now it forces us to tell it and we don’t have to create the new VCS root.

Please provide any feedback or post a comment if you have any questions.