September 12, 2017

Jenkins Integration to Feature Branch Workflow

Version Control
Continuous Delivery

We wrote earlier about how code reviews work in Helix TeamHub. The blog post covered how the successful Git branching model and its derivates can be implemented efficiently in Helix TeamHub with code reviews and mandatory approvals. In this blog post, we are going to build another feedback cycle on top of the basic code review workflow that relies only on another human reviewer. The new feedback cycle is feedback from automatic build tools such as Jenkins. This blog post covers how to set up a feature branch workflow that requires a successful (green) build from Jenkins before the feature branch can be merged into the target branch in Helix TeamHub.

Initial Setup

This post assumes that we are in a situation where we left off at the previous blog post. In the previous post, we set up a Helix TeamHub project and created a new Git repository. We also added some feature branches to the Git repository.

What we want to do next is to set up a Jenkins job to be triggered for the feature branches in this repository. We also want Jenkins not just to execute the build, but also to notify Helix TeamHub whether the build succeeded or failed. To set this up, we need to:

  1. Set up a Helix TeamHub bot account for programmatic access.
  2. Set up Helix TeamHub Jenkins hook for triggering the Jenkins build.
  3. Configure the Jenkins job to build feature branches.
  4. Install and configure Jenkins Helix TeamHub Plugin.

1. Set up a bot account for programmatic access.

Helix TeamHub has a unique concept called bot accounts, or simply bots. Bots are used for external access to Helix TeamHub APIs as well as version control systems. Configuring a continuous integration server is an ideal example for using bots instead of your personal credentials.

Setting up a bot account in Helix TeamHub is done through the bots' UI. Bots can be created by users who have access to Helix TeamHub. When a bot is created, the creator becomes the owner of the bot. Multiple users can share ownership of bot accounts. In this example, you don't need to assign owners or members of the bot, but simply add the bot to the project.


Adding a bot to a given project is done in the team view of the project. For this purpose, we assign the bot as a guest, since only read access to the code is required, and bots with guest access are able to publish build events. For a complete description of bot credentials, see the Helix TeamHub user guide.


2. Set up Jenkins hook for triggering the build.

Next, we want to set up a Jenkins hook for triggering our build for each new change to our feature branches. Hooks are managed in the project hooks view. Helix TeamHub supports over 75 hooks to different services. After adding a Helix TeamHub Jenkins hook to a Git repository, a commit hook posts a request to http://yourserver/git/notifyCommit after each change. You can get more information in the Jenkins Git Plugin documentation.


3. Configure a Jenkins Job.

After we have everything set up from the Helix TeamHub point of view, let's jump into Jenkins and create a new job, and configure necessary job-related settings.

Add the clone URL for the repository to the job configuration. Helix TeamHub supports both SSH and HTTPS protocols for repository access and while SSH is typically preferred over HTTPS, in this example we use HTTPS for simplicity.

Configure branches to build to refs/heads/features/**. This makes Jenkins run the job only upon changes to branches that are prefixed with features/, e.g. features/login, features/logging, features/foo, and so on.


Next, add your bot credentials to the configuration. You can find the bot credentials in Helix TeamHub, either from the project team view or in the company bots view, by clicking the cogwheel icon next to the bot name.


In order for the Helix TeamHub Jenkins hook to start the execution of this job, you will need to enable the Poll SCM option in the Job configuration. No polling schedule is required to be set, however. This is needed for Jenkins to distinguish which builds should be started upon changes and which should not.

Setting up the actual build steps are project specific and are thus skipped in this post. 

4. Configure the Jenkins Helix TeamHub Plugin.

The Helix TeamHub Jenkins Plugin can be installed from the Jenkins plugin manager. It should be configured according to the plugin. After installing and configuring the plugin, there should be a new post build action available in the Jenkins job configuration named Helix TeamHub notification.

In order to configure Jenkins to send the build information successfully, you need to add the Helix TeamHub notification post build action and configure the account key of the bot account to it. This way, the Helix TeamHub Jenkins Plugin utilizes the correct credentials when creating the event. After setting the post build action and saving the Jenkins job settings, everything is set for proper testing.

Testing the Setup

We can now test the setup by creating a feature branch named features/new-feature. We can create a couple of commits to the branch, and push it to Helix TeamHub. Once the branch is pushed we can create a new code review with the branch against the master branch and choose the Require passing build option.

Choosing the require passing build option disables merging the changes through the Helix TeamHub web interface until there is a successful build notification sent to Helix TeamHub for the given branch. The changes can be still merged manually via command line, which is sometimes useful.


When we click the Create button and open the code review, we should see that the Build event is already green and that merging the changes is possible. Naturally, when doing actual automated builds and verifications, the build might take longer, and the successful or unsuccessful status would only be shown after the build is executed.



Setting up a Jenkins integration with your feature branch workflow provides a quality gate for new features under development. In this pos we explained how to set it up in Helix TeamHub and Git repositories. Similar workflows can also be achieved in Mercurial repositories.

If you would like to test the functionality yourself, sign up for free.