How To Require Circle CI Builds For Pull Requests

You are a software developer and/or a project manager. You and your team want to make sure that new code changes don’t break your project before pushing to production. Great! Well, how do we go about making sure that we do everything we can to make sure that doesn’t happen? I’ll walk you through how to require successful Circle CI builds before pull requests can be merged!

One great thing to add to you workflow is requiring successful builds with the new code before merging. If you are using GitHub and Circle CI, I am going to lay out how you can leverage the GitHub’s status API to block pull requests if new code breaks your builds.

Setup GitHub And Circle CI

First thing we need to setup is GitHub. If you don’t already have a repository setup in GitHub, do that first thing. Next, you’ll want to head over to Circle CI and sign in with GitHub. Once you are logged in to Circle CI, you should see a screen similar to the following:

Setting Up Configuration File

Next, click Set Up Project next to the repository you wish to setup automated builds with. This will show a menu of the different default programming languages that Circle CI integrates with and has default images for. It will look like the following:

Select your desired programming language, which will then show a default base configuration file for that particular language. For example, if you select Node as your desired programing language, it will show you a default Circle CI configuration file that resembles the following:

# Javascript Node Circle CI 2.0 configuration file
#
# Check https://circleci.com/docs/2.0/language-javascript/ for more details
#
version: 2
jobs:
  build:
    docker:
      # specify the version you desire here
      - image: circleci/node:7.10

      # Specify service dependencies here if necessary
      # CircleCI maintains a library of pre-built images
      # documented at https://circleci.com/docs/2.0/circleci-images/
      # - image: circleci/mongo:3.4.4

    working_directory: ~/repo

    steps:
      - checkout

      # Download and cache dependencies
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package.json" }}
            # fallback to using the latest cache if no exact match is found
            - v1-dependencies-

      - run: yarn install

      - save_cache:
          paths:
            - node_modules
          key: v1-dependencies-{{ checksum "package.json" }}      # run tests!
      - run: yarn test

In your repository on GitHub, create a file .circleci/config.yml in your master (or current default)branch and paste the example config file into that file. After you have done that, go back to Circle CI and in the setup screen where you copied the default config file from, click the button Start Building. If your first build fails, it may be because you don’t have any unit tests setup yet. You can remove the - run: yarn test line and replace it with — run: echo "Hello World" in order just to get the build passing.

After getting your first successful build on Circle CI, we need to go back to GitHub and go to your repo, then click Settings in top menu list > Branches in left menu list. Next to Branch Protection Rules, click Add Rule. This will bring up a screen that looks like the following:

GitHub repository branch protection rules

As you can see from the above photo, you will need to select Require status checks to pass before merging option. This is what we need in order to block any PRs from being merged if builds fail with new changes. If you also want to make sure the new changes being merged aren’t missing any code that has been pushed since the current changes have been checked out, you’ll also want to select Require branches to be up to date before merging. As you can also see, you will need to select ci/circleci: build to be one of the statuses that has to be successful before merging.

Conclusion

After applying these changes to GitHub, any future pull requests for the repository and for the specified branch(es). This should help keep errors from reaching your production environments.