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 Continuous integration overview.

Onboarding

CircleCI onboarding is part of the project setup flow. See Set up continuous integration in the Installation guide and select CircleCI.

Maintenance

Update deployment branches

All jobs in the commit and audit workflows (database, lint, build, audit) 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)
N.x	Major version branches (e.g., 1.x, 2.x)

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

2 special cases apply on top of the branch filter:

• The deploy job halts early for pull requests coming from project/* branches, so a long-lived project branch deploys on direct pushes but not from its pull requests.
• Tag deployments run through a separate deploy-tags job that triggers only for tags matching semantic version (1.2.3, 1.2.3-rc.1) or date-based (2023-04-17) patterns.

Update nightly database schedule

The nightly database workflow caches a fresh database dump for faster builds the next day. It is scheduled against the develop branch - change the branch filter of the nightly-db workflow if your project does not use one.

To change when it 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

Resource classes scale CPU and memory only. Disk space is not tied to the resource class, so upgrading it will not help a job that runs out of space - see Runner disk space.

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

Every added container that runs Behat also needs a matching pN profile in behat.yml. See Test parallelism for the full procedure, how scenarios are balanced across containers, and how to move a tool onto a different container.

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.