Configure builds on CircleCI

Begin by reading the CircleCI getting started documentation. Do not yet add the suggested CircleCI config.

Enable and configure

The following instructions reference the develop and develop-built branches, but can be adapted for other branches (e.g. master and master-built). For launched applications, it is recommended to first enable and configure CircleCI on a repository branch that deploys to a non-production environment. After configuration of CircleCI is completed and works as expected, the same steps can be repeated for other deploying branches.

1. Create a VIP Support request and include a link to the GitHub repository that needs CircleCI enabled. VIP Support will confirm when this step is complete and provide a link to the CircleCI project for the repository.
2. Generate a deploy key. This key can be generated locally, as it will be used only by CircleCI to communicate with the GitHub repository; it does not come from or communicate with VIP’s servers.
3. On GitHub, add the key to the repository under “Settings > Deploy Keys”. The key needs write access.
4. On CircleCI:
   1. Navigate to the CircleCI link shared by VIP Support (e.g., https://circleci.com/gh/wpcomvip/your-github-repo).
      A user’s GitHub account credentials are used to access this URL.
   2. Add the key to the project (Settings | SSH Keys).
      It is important that the hostname is set to github.com.
5. Create a new pull request to add or adapt a config for CircleCI:
   • If a CircleCI config does not exist in the repository, copy this config to .circleci/config.yml in the repository. Any necessary build command(s) should be added to the section under @TODO: Configure build steps.
   • If a CircleCI config does exist:
     1. Add the build command(s). VIP’s example config includes an example of added build commands, in the section under @TODO: Configure build steps.
     2. Add the two sets of two lines referenced by the REQUIRED: comments.

6. Add the deploy key‘s fingerprint to the repository’s .circleci/config.yml in the develop branch.
7. If needed, add and update a .deployignore file.
8. Trigger a build by merging a pull request to develop. This can be a non-significant change like a code comment. If the setup was successful, CircleCI will push a built copy of the application code to the develop-built branch on GitHub.
9. Verify that the develop-built branch exists and contains built code from the merged pull request.
10. Contact VIP Support to update the environment to deploy from develop-built.

Testing a CircleCI config

New builds will only run when a commit is made. If a build script is failing on CircleCI, test the config locally. CircleCI has a Local CLI that can be used with Docker to execute jobs. The config.yml file can be validated with the CircleCI Local CLI, but it only checks for syntax errors and not build errors.

Installing a CircleCI config on macOS or Linux

• Public CircleCI CLI Github Repository: https://github.com/CircleCI-Public/circleci-cli
• Install using Homebrew, cURL, or Snapcraft.
• Make sure that Docker is installed and the user is logged in with docker login. It is recommended to log in with a Docker username. Issues have been reported when logging in with an email address.
• Connect with the user’s CircleCI account: circleci setup
• The config file can be validated with circleci config validate, or run a job locally with circleci local execute --job JOBNAME . This command only runs a single job and not a workflow.