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 configuration files in the .circleci/ directory, 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:

Variable	Description
VORTEX_ACQUIA_KEY	Acquia Cloud API key
VORTEX_ACQUIA_SECRET	Acquia Cloud API secret

6. Configure schedule triggers

If you use the self-hosted Renovate workflow for automatic dependency updates, the update-dependencies.yml pipeline requires a schedule trigger configured in the CircleCI UI. Without this trigger, the workflow will not run.

Go to Project Settings → Triggers and create the following scheduled trigger:

Setting	Value
Trigger name	update-dependencies
Config source	update-dependencies.yml
Branch	develop
Schedule	Every day at 11:05 and 23:05 UTC

note

The trigger name update-dependencies must match exactly - it is referenced in the workflow when condition in the configuration file.

tip

The nightly database schedule is defined directly in .circleci/config.yml using the nightly_db_schedule YAML anchor. No UI configuration is needed for this schedule.

Maintenance

Update deployment branches

All CI jobs (database, lint, build) run on every branch. The deploy job only runs for specific branch patterns, controlled by a regex filter in the workflows section of .circleci/config.yml:

Pattern	Description
production	Production environment branch
main, master	Default development branches
develop	Integration branch for ongoing work
release/**	Release preparation branches (e.g., release/1.2.3, release/2023-04-17)
hotfix/**	Urgent production fixes (e.g., hotfix/1.2.4, hotfix/2023-04-17)
feature/**	New feature branches (e.g., feature/login, feature/123-new-ui)
bugfix/**	Non-urgent bug fix branches (e.g., bugfix/fix-auth, bugfix/456-crash)
project/**	Long-lived project branches for large initiatives
ci*	Temporary CI testing branches (e.g., ci, ci-debug)

To modify which branches trigger deployments, update the only filter regex in the deploy job.

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 in .circleci/config.yml (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

When adding more containers, distribute Behat scenarios across them using profile tags (@p0, @p1, @p2, etc.) in your feature files. Since the first container also runs linting, PHPUnit, and coverage, assign more Behat scenarios to the additional containers to keep build times balanced.

See Test parallelism for details on how tests are distributed across 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

Code coverage threshold

The workflow enforces a minimum code coverage threshold. If coverage falls below the threshold, the build fails.

Configure the threshold by setting the VORTEX_CI_CODE_COVERAGE_THRESHOLD environment variable in Project Settings → Environment Variables. Default is 90 (percent).

Coverage reports can be posted as PR comments. This requires a GITHUB_TOKEN environment variable with permission to post comments. Each new report replaces the previous one — older comments are minimized to keep the PR timeline clean. To disable PR comments, set VORTEX_CI_CODE_COVERAGE_PR_COMMENT_SKIP to 1.