Skip to main content

CircleCI

CircleCI is a cloud-based continuous integration and delivery platform that automates the build, test, and deployment process.

For general CircleCI documentation, refer to the CircleCI Documentation.

info

For information about the CI workflow structure, jobs, and caching strategy, see the CI overview.

Onboarding​

Before you begin, ensure you have:

  • A CircleCI account connected to your repository
  • Repository admin access to configure project settings
  • API credentials for your hosting provider (if deploying)

1. Enable the project​

Log in to CircleCI and add your repository as a new project. CircleCI will connect to your GitHub account, detect the .circleci/config.yml configuration file, and start running builds automatically when you push code.

2. Add SSH key for database download​

To download a database from your hosting provider during CI builds, you need an SSH key that has access to your hosting environments.

  1. Generate an SSH key pair:

    ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject-circleci@example.com" -f ~/.ssh/deployer_myproject_circleci -N ""
    Key naming convention

    Use the +<project>-<service> suffix in the email comment (e.g., deployer+myproject-circleci@example.com) to identify what the key is used for. This helps when managing multiple deployment keys across different projects and services.

  2. Add the contents of the public key (e.g., ~/.ssh/<key>.pub) to your hosting provider's authorized keys for read access.

  3. Add the private key in CircleCI under Project Settings → SSH Keys. CircleCI will generate a fingerprint - copy it for the next step.

3. Add SSH key for deployment​

To deploy code to your hosting provider, you need an SSH key with write access to your hosting environments.

note

The database source and deployment destination may be different providers (e.g., downloading a database from Acquia but deploying to Lagoon). If they are the same provider, you can use a single key for both operations.

  1. Generate an SSH key pair (skip if using the same key as above):

    ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject-circleci@example.com" -f ~/.ssh/deploy_myproject_circleci -N ""

  2. Add the public key to your hosting provider

  3. Add the private key in CircleCI under Project Settings → SSH Keys. Copy the fingerprint for the next step.

4. Update SSH fingerprints in config​

CircleCI uses SSH key fingerprints to load the correct keys into the runner container. Update the YAML anchors in your .circleci/config.yml file:

  • db_ssh_fingerprint - your database download SSH key fingerprint
  • deploy_ssh_fingerprint - your deployment SSH key fingerprint

5. Configure environment variables​

Add the following variables in Project Settings → Environment Variables:

Acquia:

VariableDescription
VORTEX_ACQUIA_KEYAcquia Cloud API key
VORTEX_ACQUIA_SECRETAcquia Cloud API secret

Maintenance​

Update deployment branches​

The deploy job only runs for specific branch patterns. To modify which branches trigger deployments, update the only filter regex in the deploy job under the workflows section of .circleci/config.yml:

filters:
  branches:
    only: /^(production|main|master|develop)$|^project\/[a-zA-z0-9\-\.]+|^(feature|bugfix)\/[a-zA-Z0-9\-\.\,_]+$|^ci.*|^(release|hotfix)\/[0-9]+(\.[0-9]+){2}(-rc\.[0-9]+)?$|^(release|hotfix)\/[0-9]{4}-[0-9]{2}-[0-9]{2}(\.[0-9]+)?$/

Update nightly database schedule​

The nightly database job caches a fresh database dump for faster builds the next day. To change when this runs, update the nightly_db_schedule YAML anchor (cron format, UTC timezone):

- &nightly_db_schedule "0 18 * * *"  # 6 PM UTC daily

Change runner resource class​

For faster builds, you can upgrade the runner resource class in the runner_config section. Note that this may affect your CircleCI billing:

resource_class: large  # Options: small, medium, large, xlarge

Change test parallelism​

To speed up test execution, you can increase the number of parallel runners in the build job. See Running tests in parallel for more information:

build:
  parallelism: 4  # Run tests across 4 containers

SSH access for debugging​

CircleCI provides built-in SSH access to debug failing builds. Click the Rerun job with SSH button on a failed job to get SSH connection details. See Debugging with SSH for more information.

Adjust build timeout​

If builds are timing out, increase the no_output_timeout value for long-running steps:

- run:
    name: Long running task
    command: ./scripts/long-task.sh
    no_output_timeout: 60m  # Default is 10m