Configure builds on CircleCI

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

Enable and configure

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.

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

1. In GitHub: Create a new branch that has -built appended to the name of the current deploying branch. For example, for an environment that currently has a deploying branch named develop, an additional branch named develop-built should be created.
2. In Zendesk: 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 (e.g., https://circleci.com/gh/wpcomvip/your-github-repo).
3. In the command line of the user’s local machine: Follow the instructions to create additional GitHub SSH keys. Both a public and a private key will be generated. The private key will be needed in Step 6. It is secure to generate these keys locally, as they will be used only by CircleCI to communicate with the GitHub repository; not with VIP’s servers.
4. In GitHub: Add the public key to the application repository under “Settings > Deploy Keys”. The key must have write access.
5. 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 will allow access this URL.
6. In CircleCI: Select the button labeled “Project Settings” in the upper right of the panel.
   • Select “SSH Keys” from the menu at the left to access a settings panel titled “Checkout SSH Keys”.
   • In the “Additional SSH Keys” section of the panel, select “Add SSH Key” to add the GitHub private key. The GitHub private key (from Step 3) makes it possible for CircleCI to push changes to the -built branches. It is important that the hostname in this setting is set to github.com.
   • Adding the GitHub private key will generate a “Fingerprint” value in the “Additional SSH Keys” panel. This value will be needed in Step 8.
   • In the “Deploy Key” section of the panel, select the button labeled “Add Deploy Key” to add a new deploy key. If a key has already been added, it will be displayed in the “Deploy Key” section. The deploy key makes it possible for CircleCI to checkout the repository.

7. In GitHub: 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.
8. In GitHub: Add the SSH key’s fingerprint (from Step 6) to the repository’s .circleci/config.yml in the develop branch.
9. Add and update a .deployignore file to ensure that files generated during the build process are included in the deployment.
10. 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.
11. Verify that the develop-built branch exists and contains built code from the merged pull request.
12. In the VIP Dashboard: Update the deployment branch for the environment to 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.

Limitations

CircleCI is a resource shared by multiple WordPress VIP customers. For the benefit of themselves and others, customers should keep the following in mind:

• Only use the small and medium resource classes. If a higher class is needed, create a VIP Support request.
• Only run tasks / jobs related to a WordPress VIP application.
• Only run tasks / jobs when they are needed (e.g. only trigger for PRs and branches tied to an environment).
• Keep overall usage as optimized as possible.

If unreasonable usage is discovered by VIP, the affected customers will be contacted to discuss that usage and work through possible improvements and workarounds.