Skip to content

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 production-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 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.
  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 will allow access this URL.
    2. Select the “Project Settings” button in the upper right of the panel.
    3. Select “SSH Keys” from the menu at the left to access a settings panel titled “Checkout SSH Keys”.
    4. 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 to github.com.
    5. 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.
  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.
  1. Add the SSH key’s fingerprint to the repository’s .circleci/config.yml in the develop branch. This key and fingerprint are listed in the Additional SSH Keys section.
  2. If needed, add and update a .deployignore file.
  3. 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.
  4. Verify that the develop-built branch exists and contains built code from the merged pull request.
  5. 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.

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.

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: February 27, 2023