CircleCI is a Continuous Integration platform for GitHub projects.

CircleCI can run the projects' tests automatically whenever new code is pushed to the repo. This ensures that existing functionality and features have not been broken by the changes.

The current CircleCI set up performs the following things whenever someone push code to the repo:

  • Runs the gradle checkstyleMain checkstyleTest headless allTests coverage coveralls asciidoctor command (see UsingGradle for more details on what this command means).

  • Runs additional repository-wide checks.

If you would like to customise your CircleCI build further, you can learn more about CircleCI from CircleCI Documentation.

Setting up CircleCI

  1. Fork the repo to your own organization.

  2. Go to https://circleci.com/signup/ and click Sign Up with GitHub, then enter your GitHub account details if needed.

    Signing into CircleCI

  3. On the Dashboard, select your organization in the drop-down box at the top left corner.

    Select your organization

    • If the organization is not shown, go to the Account Integrations page, and click on Check permissions as shown below:

      Check permissions

      This should bring you to a GitHub page that manages the access of third-party applications. Depending on whether you are the owner of the repository, you can either grant access

      Grant access

      or request access

      Request access

      to CircleCI so that it can access your commits and build your code.

  4. Select Add Projects from the left sidebar.

    Add projects

  5. Find the forked repository that you wish to add, and select Set Up Project.

    Set up project

  6. The next page explains how to configure your project so that CircleCI can test your commits. Since this repo comes with a CircleCI config.yml, there is no need for you to create one yourself.

  7. Click on Start building.

    Start building

  8. CircleCI will start building your latest commit on master.

    Building project

    • Go to the repository and see the pushed commit. There should be an icon which will link you to the CircleCI build.

      Commit build

    • As the build is run on a provided remote machine, we can only examine the logs it produces:

      CircleCI build

  9. Update the link to the 'build status' badge at the top of the README.adoc to point to the build status of your own repo.

    • For a more consistent styling, you can use the badges from Shields.io. Simply copy the code below, and replace the <username> with your GitHub username (or GitHub organization, if your repository belongs to one) and <repo> with your repository name.

      https://circleci.com/gh/<username>/<repo>/tree/master[image:https://img.shields.io/circleci/project/github/<username>/<repo>.svg?label=circleci[Build Status]]

Building pull requests

In order to allow CircleCI to build and test pull requests, there are a few options we need to enable.

  1. Go to your Dashboard and click on the cog beside your repository.

    Project settings

  2. Select the Advanced Settings tab.

    Advanced settings

  3. Turn On the following options: Build forked pull requests, Pass secrets to builds from forked pull requests, and Only build pull requests. This last option lets CircleCI skip the building of the gh-pages branch.

    Enable options

Repository-wide checks

In addition to running Gradle checks, we also configure CircleCI to run some repository-wide checks. Unlike the Gradle checks which only cover files used in the build process, these repository-wide checks cover all files in the repository. They check for repository rules which are hard to enforce on development machines such as line ending requirements.

These checks are implemented as POSIX shell scripts, and thus can only be run on POSIX-compliant operating systems such as macOS and Linux. To run all checks locally on these operating systems, execute the following in the repository root directory:

./config/travis/run-checks.sh

Any warnings or errors will be printed out to the console.

Implementing new checks

Checks are implemented as executable check-* scripts within the config/travis/ directory. The run-checks.sh script will automatically pick up and run files named as such.

Check scripts should print out errors in the following format:

SEVERITY:FILENAME:LINE: MESSAGE

where SEVERITY is either ERROR or WARN, FILENAME is the path to the file relative to the current directory, LINE is the line of the file where the error occurred and MESSAGE is the message explaining the error.

Check scripts must exit with a non-zero exit code if any errors occur.