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

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

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.