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
). 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.master
-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 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 are used to access this URL. - Add the key to the project (Settings | SSH Keys).
It is important that the hostname is set togithub.com
.
- Navigate to the CircleCI link shared by VIP Support (e.g., https://circleci.com/gh/wpcomvip/your-github-repo).
- 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 deploy key‘s fingerprint to the repository’s .circleci/config.yml in the
branch.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.