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., production
and
). 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.production
-built
- 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.
- Generate a GitHub 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.
- On GitHub, add the key to the repository under “Settings > Deploy Keys”. The key needs
write
access. - On CircleCI:
- 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. - Select the “Project Settings” button 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 the “Additional SSH Keys” section of the panel, select “Add SSH Key” to add the GitHub private key.
The GitHub private key makes it possible for CircleCI to push changes to the-built
branches. It is important that the hostname in this setting is set togithub.com
. - In the 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.
- Navigate to the CircleCI link shared by VIP Support (e.g.,
- 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:
- Add the build command(s). VIP’s example config includes an example of added build commands, in the section under
@TODO: Configure build steps
. - Add the two sets of two lines referenced by the
REQUIRED:
comments.
- Add the build command(s). VIP’s example config includes an example of added build commands, in the section under
- 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
- Add the SSH key’s fingerprint to the repository’s .circleci/config.yml in the
branch. This key and fingerprint are listed in the Additional SSH Keys section.develop
- If needed, add and update a
.deployignore
file. - Trigger a build by merging a pull request to
. 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 thedevelop
branch on GitHub.develop
-built - Verify that the
branch exists and contains built code from the merged pull request.develop
-built - 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 withcircleci 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
andmedium
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.
Note
Do not use CircleCI’s Context feature. This is a mechanism for securing and sharing environment variables across projects. Contexts are globally available and can be accessed by any project within the wpcomvip
organization on CircleCI, which can allow secrets to be made available to unauthorized users. Instead, use project-level environment variables or an external secrets storage system like Hashicorp’s Vault.
Last updated: August 03, 2023