Configure builds on CircleCI

It’s a good idea to read the CircleCI getting started documentation (but don’t add the suggested CircleCI config at this point).

The following instructions reference the master and master-built branch, but can be adapted for other branches, e.g. develop and develop-built.

Before you start

We’ll need to enable CircleCI for your repository. Open a ticket and we’ll take care of that for you. Once done, you can follow the remaining steps below.

1. Generate a deploy key. This key can be generated locally, as it will be used only by CircleCI to communicate with your GitHub repository; it does not come from or communicate with our servers.
2. On GitHub, add the key to your repository under “Settings > Deploy Keys”. Note that the key needs “write” access.
3. On CircleCI, you’ll need to:
   1. navigate to https://circleci.com/gh/wpcomvip/your-github-repo (use your GitHub account to access).
   2. add the key to your project (Settings | SSH Permissions). Note: It’s important that you set the hostname to github.com.
4. Create a new Pull Request to add or adapt a config for CircleCI:
   • If you have no CircleCI config in your repository, copy this config to .circleci/config.yml in your repo; you will need to add the build command(s) you’re using in the section under “@TODO: Configure build steps”
   • If you already have a CircleCI config, you’ll need to:
     1. Add the build command(s), referencing the section in our example config commented with “@TODO: Configure build steps”
     2. Add the two sets of two lines referenced by the “REQUIRED:” comments

1. If necessary, add and update a .deployignore file.
2. You can now trigger a build by merging a PR to master (this can be a non-significant change like a code comment). If the setup worked, CircleCI will have pushed a built copy of your application to the master-built branch on GitHub. You should verify the branch exists and contains the changes you made.
3. Now contact VIP again to have your environment updated to deploy from master-built
4. And that’s it! Happy building!

Testing your CircleCI Config

If your build script is failing on CircleCI, it might be a good idea to test your config locally since new builds will only run when a commit is made.  CircleCI has a Local CLI you can use with Docker to execute jobs.  Take a look at the Using the CircleCI Local CLI documentation.  You can validate your config.yml file using the Local CLI, but it only checks for syntax errors and not build errors.

Installing CircleCI Config on macOS or Linux

• Public CLI Github Repository: https://github.com/CircleCI-Public/circleci-cli
• Install using Homebrew, cURL, or Snapcraft
• Make sure you have Docker installed and you’re logged in with docker login (Tip: Many people report logging in with your email might cause issues so if you encounter that problem, try logging in with your Docker username)
• Connect with your CircleCI account: circleci setup
• Now you can validate a config file circleci config validate or run a job locally with circleci local execute --job JOBNAME (Note: this command only runs a single job and not a workflow)