Configure web hooks to trigger Continuous Integration builds

- By Abhijit Kini on June 01, 2016

Web hooks on source control providers, such as GitHub and Bitbucket, are commonly used to trigger actions. This is achieved by setting up integrations that listen to specific events on the source control provider, where the source control provider sends a HTTP POST payload to the web hook's configured URL. Examples include notifying a user or a channel of an event, updating an external issue tracker, deploying code to a production server and triggering Continuous Integration builds. 

In this tutorial, I'll go over configuring web hooks to trigger for five scenarios - commits, pull requests, tags, releases and temporarily pausing all web hooks to the project.

Before you begin

Ensure you have:

  • Have signed into Shippable using your GitHub or BitBucket credentials
  • Completed the previous tutorial of running continuous integration for a Node.js app
  • Have an enabled project on Shippable platform, to run continuous integration

I'll continue to use the Node.js project (available for download from GitHub) for this tutorial.

Code commits

When a local code change is pushed to the source control repository, it is a code commit. When you sign into Shippable the first time, you authorize access to your public repositories (and your private repositories). By doing so, a web hook is established to that repository that enables Shippable to actively listen for any code commits or pull requests. When a code commit or pull request happens (independent of the user who created it), a CI build is automatically triggered on Shippable, by default.

To see it in action, do the following:

  • Ensure you have signed into Shippable and have an enabled project. Read this tutorial, if you need help.
  • Make a change in the code on your local directory and save it.
  • Run the following commands to push this code change to your source control repository.
    • git add .
    • git commit -m "made a change in code"
    • git push origin master
  • Check for the automated build that got triggered for this project on Shippable.

Now if we need to disable the automatic build trigger on Shippable, we can do so taking the following actions:

  • From your home page, select your 'Subscription'.
    • 'Shippable-Demo' in this case.
  • In your subscription select your enabled project that you want to disable automatic build triggers for code commits.
    • 'sample_nodejs' in this example.
  • Click the 'Settings' tab of your project.
  • Scroll down to the 'Configure Web hook Events for Triggering Builds' section.
  • Click the 'Disable' button next for 'Commits'.

This setting will ensure no builds are triggered for code commits.

Configure web hook to disable code commits from triggering a CI build

Pull Requests

Next, let's look at Pull Requests (PR). PR happens between two branches or two forks of a repository. It is a request to commit code from one fork/branch to another fork/branch. Once the PR is initiated from the source fork/branch, a user can review the code & merge the PR into the target fork/branch. Shippable, by default, triggers a build each time for initiating and merging a PR.

To demonstrate a PR, I have created a branch called 'sample_nodejs_branch' on the Node.js application. I will make a change to the code locally on the branch and initiate a PR from the branch to be merged into 'Master' branch. Since I have enabled this project on Shippable, the PR initiation from 'sample_nodejs_branch' and the merging on 'Master' will trigger two separate builds. The steps I follow are:

  1. Ensure the 'sample_nodejs' repository on my GitHub is an enabled project on Shippable.
  2. Using Terminal, I navigate to my local directory where the GitHub has been cloned.
  3. Run git checkout sample_nodejs_branch to switch to the branch 'sample_nodejs_branch'.
  4. Make a change to the README file on the sample_nodejs_branch.
  5. Run git add .; git commit -m "changed ReadMe on branch to show PR"; git push origin sample_nodejs_branch to push this change to my GithHub 'sample_nodejs_branch' repository.
  6. In the GitHub UI, initiate a PR from the 'sample_nodejs_branch'.
  7. Merge the PR into the 'Master' branch.

 Creating and merging a Pull Request on GitHub

 

This automatically triggers three CI builds on Shippable as shown below. Bottom one is when I pushed the code from my local branch to GitHub branch. Second one is when I initiated a PR and the third/top one is when I merged the PR.

 Continuous Integration builds on code commit, initiate pull request, merge pull request

Remember, by default, PRs will trigger builds automatically on Shippable. Now, I'll show you how to disable the triggering of builds all Pull Requests. Follow these steps:

  • From your home page, select your 'Subscription'.
    • 'Shippable-Demo' in this case.
  • In your subscription select your enabled project that you want to disable automatic build triggers for pull requests.
    • 'sample_nodejs' in this example.
  • Click the 'Settings' tab of your project.
  • Scroll down to the 'Configure Web hook Events for Triggering Builds' section.
  • Click the 'Disable' button for 'Pull Requests'.

This setting will ensure no builds are triggered for Pull Requests.

Tags and Releases

Releases are typically used for updated versions of a software project. In such scenarios, the version number is tagged for each release.

By default, Releases and Tags will not trigger builds automatically on Shippable. Currently configuring Releases and Tags to trigger web hook builds is supported for GitHub only.

Now, I'll show you how to enable the triggering of builds for all releases and tags. Follow these steps:

  • From your home page, select your 'Subscription'.
    • 'Shippable-Demo' in this case.
  • In your subscription select your enabled project that you want to enable automatic build triggers for Releases/Tags.
    • 'sample_nodejs' in this example.
  • Click the 'Settings' tab of your project.
  • Scroll down to the 'Configure Web hook Events for Triggering Builds' section.
  • Click the 'Enable' button for 'Releases' and 'Tags'.

This setting will ensure builds are triggered for all Releases and Tags.

Pausing all web hooks to trigger CI builds

If you want to pause all web hooks to trigger CI builds, follow the steps below:

  • From your home page, select your 'Subscription'.
    • 'Shippable-Demo' in this case.
  • In your subscription select your enabled project that you want to pause all web hooks.
    • 'sample_nodejs' in this example.
  • Click the 'Settings' tab of your project.
  • Scroll down to the 'Pause/Resume' section.
  • Click on 'Pause'. This will stop all CI build triggers and there will be no action taken by Shippable for any event for this project.
  • Click on 'Resume' to re-establish the web hooks & have builds triggered for code commits, PRs.

Pausing a project from triggering Continuous Integration builds

We've successfully gone through all the scenarios for configuring web hooks to trigger Continuous Integration builds for a project. Configuring them based on your scenario will help you manage Continuous Integration on your projects more effectively.

For questions or feedback on this topic, leave a comment below or open a support issue. We're glad to help.


Try Shippable

Topics: continuous integration (CI), how-to, tutorial, tips, Webhooks