Adding Build Statuses to Pull Requests with TeamCity and GitHub

I’m always looking for ways to improve our build server setup and improve our overall efficiency. So a recent change I’ve made is to get Team City to start building pull requests and pushing the resulting status back to GitHub.

This improves our dev flow by eliminating the need to do any testing on a pull request if we can already see it will fail a build. Previously someone doing a code review would only find out once they’ve checked out the change and built it locally, or even worse after approving the request and then breaking the build.

Pull Request Build Status

What’s particularly good with this setup, is it’s testing the resulting merge rather than just the branch being merged in.

Team City Setup

As this is covering a different scenario to our normal build processes which are focused on preparing a build version to be deployed, I set this up as a second build configuration on our projects.

Version Control Settings Root (VCS Root)

The VCS Root needs to be configured to fetch each pull request that is creating in GitHub. To do this, you will need to add a Branch specification which will tell Team City to monitor additional branches rather than just the default branch specified.

Branch Specification

I’m using the branch specification +:refs/pull/(*/merge) .

This syntax is telling Team City to monitor references to pull for pull request, the * refers to any pull request, and the merge indicates that we only want to resulting merge of the pull request.

When you create a pull request in GitHub, this merge reference is automatically created for what the resulting merge would look like.

In the projects list, builds will now get labels indicating what they were for:

Pull Requests on dashboard

Build Steps

I created my build configurations by duplicating the existing ones we have that take care of creating builds to be passed onto Octopus Deploy for release. If you do this, it’s important to remember to disable all the steps you no longer need.

Build Steps

The less steps you have the quicker your build will run and the quicker the pull request will be updated with a status. Ideally you want the process to finish before someone starts doing a code review! Steps like running Inspections may prove counter productive if the builds are never finished on time.

Triggers

Having a build running automatically for your releases can be a drain on server resources, particularly if you never have any intention of actually doing a deploy for most of them. For this reason our builds are set to manual.

However for statuses to be of any use, they’re going to need to be running automatically so that the status is ready for the code reviewer, so we need to add a VCS Trigger.

Triggers

Build Features

To get Team City to start posting status updates back to GitHub we need to add a build feature. If your on a version of TeamCity prior between 7.1 and 10 then there is a plugin you can grab here https://github.com/jonnyzzz/TeamCity.GitHub. If your on a newer version of TeamCity. i.e. 10+ then the build feature is now built in and is called Commit status publisher. The built in version also has support for Bitbucket, Gerrit, GitLab, JetBrains Upsource and Visual Studio Team Services.

Add the build feature and fill in the config settings.

CommitStatusPublisher.PNG

And that’s it. Your pull requests will now automatically build and have the status sent back to GitHub.

Pull Status Pass.PNG

Not only will you be able to see this status in GitHub, you’ll also be able to click a details link to see the build. Useful in the event that it’s failed and you want to see why.

 

The importance of build numbers

If I were to make a prediction, I would say that build numbers are something that are rarely treated as being important in the agency world of web development. That’s not to say milestone releases aren’t given names like “Phase 2”, “August Release” or a major feature name, but every build / release of a project in between, I’d sense largely have build numbers either ignored or never created.

It’s also easy to see why, after all it’s not like we’re producing software that’s going out to the masses to be installed. The solution is essentially just ending up having 1 install on a set of servers. When a new version is built, that replaces everything that came before it and if a bug is found we generally roll forward and fix the bug rather than ever reverting back.

Why use build numbers?

So when we’re constantly coding and improving applications in an agile world why should we care about and use build numbers?

To put it quite simply its just an easy way to identify a snapshot of code that could have actually have been built and then released to a server. This becomes hugely useful in scenarios such as:

  • A bug being reported by an end user
  • An issue being identified by some performance monitoring
  • An issue being picked up in some functionality further on from the site. e.g. in an integration

Without build numbers the only way to react to these scenarios is to look at commit dates in source control or manual release notes that may have been created to try and work out where an issue may have been created and what changed at that time. If the issue had subsequently been fixed you also can’t really give a version description when it was fixed other than a rough date.

Other advantages of build numbers can include:

  • Being able to reference a specific version that has been pen tested
  • Referencing a version that’s been tested with integrations
  • Having approval to release a specific version rather than just the latest on master
  • Anywhere you want to have a conversation referencing releases

Build numbers for deploys

The first step to use build numbers and with the rise in CI, possibly the one thing most people are doing is to start creating build numbers via a build server. By using any type of build server you will end up with build numbers. This instantly gives you a way to know when a build was created and what commits were new within the build.

Start involving an automated deployment setup either using your build server or with other tools like Octopus Deploy and you will now start to get a record of when each build was deployed to each server.

feature-1

Now you have an easy way to not only reference what build was on each environment and when through the deploy history, but also a way to see what went into a build through the build servers change log.

Tag builds in source control

Being able to see the changes that went into each build on your build server is all very good, but it’s still not an ideal situation for finding the exact code version a build relates to.

Thankfully if your using Team City it’s really easy to set it up to create a tag in your source control with each build number. Simply go to the build features section of your projects configuration and add a feature called “VCS Labeling”. This is a step that happens post build in the background and will create a tag in source control including the build number. It has lots of other configuration options, so if you need different tag formats for different branches its got you covered.

If your using GitHub once this is turned on you will be able to see a list of all the tags in the releases section.

GitHub Releases Screen

Update Assembly info

Being able to identify a build in source control and view a history of what should have been on a server at a particular time is all very good, but its also a good idea to be able to easily identify a build for a published version of code. That way just by looking at the code on a server you can tell which build version it is, and not rely on your deployment tool to be correct.

If your using Team City this also also made super simple through a build feature called “Assembly info patcher”. When using this the build number will automatically get patched in without having to edit AssemblyInfo.cs.

Conclusion

By following these tips you will now be able to identify a version by looking at the published code, see a history of when each version was not only built but also released to each envrionment and also have an easy way to find the exact source for that build.

The build number can then be used in any conversations around when a bug was introduced and also be referenced in release notes so everyone can keep track of what versions included what fix’s in a simple to understand format.

Update local Git branch list

Ever had the issue where your Git repo has a branch that your local hasn’t picked up on? This can often happen when a branch has just been created.

The solution is simple just run…

$ git remote update origin

Team Development for Sitecore (TDS) with Github

If your using Team Development for Sitecore (TDS) and Github or Git as your source control you may experience an issue where TDS is unable to create/update some of the items in Sitecore, due to a content length issue.

The error will look something like this:

Failed to load version 1 for language en
Length of field content does not match the content-length attribute. File name: name, field id: {id}

What’s happening comes down to how Github encodes line ending. If your item contains a Rich Text field you can end up with data that has been serialized with both CRLF and LF as the line feed. This will have been included in the content length. However when you push to Git, the CRLF value will have been removed making the content length value incorrect.

To overcome this issue you need to update your .gitattributes file to treat these files differently. Just add this to your file:

# TDS files should be treated as binary
*.item -text

How do I create a .gitattributes file?

If you don’t have a .gitattributes file you may run into an issue with windows where it won’t let you create it, due to requiring a file-name rather than just an extension.

To create the file:

  1. Create the text file gitattributes.txt
  2. Open it in a text editor and add your rules, then save and close
  3. Hold SHIFT, right click the folder you’re in, then select Open command window here
  4. Then rename the file in the command line, with ren gitiattributes.txt .gitattributes

Alternatively you can download my .gitattributes file here

Using Visual Studio with Git Hub

This is one of those great examples of writing a blog post to yourself to remind you how to do something.

If your using Visual Studio 2012 then to add Git support you will need the Visual Studio Tools for Git plugin created by Microsoft’s TFS Power Tools Team (http://visualstudiogallery.msdn.microsoft.com/abafc7d6-dcaa-40f4-8a5e-d6724bdb980c), if your using a later version of Visual Studio then it’s already built in.

If you’re thinking in of using Git Hub as your source control provider then the most basic thing you’re going to need to know is how do you get the Git plugin to link up to GitHub. Here’s a couple of different methods;

Creating a Project in Git Hub

Click New Repository. Enter a new, Select Public or Private and click Create new Repository.

A new repository will be created in Git Hub

Clone the Project in Visual Studio

Now the project has been created in Git Hub you will need to clone it to your machine so that you can start adding files and sync then back.

Open a new instance of Visual Studio and do the following:

  1. Open the Team Explorer window
  2. Click the connect button
  3. In the list of Local Git Repositories click clone
  4. In the URL box enter the HTTP URL from Git Hub
  5. The second box should auto populate with a location on your hard disk
  6. Click Clone

Creating a Repository on Git Hub using the Git Hub app

Rather than creating the Git Hub repo through the GitHub website you can use their app. Once you’ve got the app installed and logged in do the following:

  1. Select the GitHub account you want to add the repo to on the left
  2. Click Create button at the top
  3. Enter a name and click create
  4. The repository will be created in GitHub and automatically sync with the folder on your machine

Adding an existing Repository to Visual Studio

If you already have a repository cloned on your machine but it’s not showing in Team Explorer you can add it by clicking on Add

  1. Click the Connect button to view the list of local repositories
  2. Click add an enter the path to the repository on your hard drive
  3. Click Add