Skip to main content

Continuous Integration

Vortex offers continuous integration configurations for GitHub Actions and CircleCI providers that allow you to automate the process of building, testing, and deploying your site.

The workflow configuration is identical for both continuous integration providers. You would need to choose one of them and follow the setup instructions.

The continuous integration pipeline consists of multiple jobs executed in a containerized environment to ensure consistency across runs.

Workflow structure​

1. Database​

  • Runs in a drevops/ci-runner runner container
  • Downloads the latest DB version based on a caching strategy
  • Caches database dumps to speed up the follow-up runs

2. Build​

  • Runs after the database job
  • Uses Docker Compose to set up the environment
  • Validates Composer lock and audits dependencies
  • Assembles the codebase by installing dependencies
  • Provisions a website
  • Lints code (only on the first instance)
  • Runs unit tests
  • Runs BDD tests
  • Generates code coverage reports
  • Collects and stores test results and artifacts

3. Deployment​

  • Runs after successful completion of a previous build job
  • Uses the built codebase without development dependencies from the build step
  • Adds required secrets and environment variables
  • Triggers a deployment using a router script

Caching strategy​

Database is downloaded overnight and cached so that the next continuous integration run on the same day uses the cached database dump.

By default, the database is cached per-branch for 24 hours. If cache is not available, the fallback default branch is used.

note

Database caching is a very powerful feature that allows to speed up the continuous integration runs on large projects with a lot of data.

In case of a project with a large database >1GB, the database import itself may take a long time, so it may be worth looking into either packaging the database dump into a container image (overnight) or using a sanitized database dump with only the required data for the tests.

Vortex supports both creating and using a database container image with embedded data. You may use MariaDB data container for Drupal with database captured as Docker layers to create an initial database image.

There are other tools also available for this purpose, such as Drush GDPR Dumper that allows to remove data from the database dump during Drush database export command without the need for an intermediate database import step.

Reset the cache​

If you need to force a fresh cache (e.g., to pull the new database dump outside of the regular schedule), increment the version tag in the cache keys:

# Before
v25.11.0-db11
# After
v25.11.1-db11

Trigger conditions​

The continuous integration pipeline is triggered by:

  • Push events to the following branches:
    • production, main, master, develop
    • feature/*, bugfix/*
    • release/*, hotfix/* (semantic version or date-based, e.g., release/1.2.3, hotfix/2023-04-17)
    • project/*
    • ci*
  • Pull requests to these branches
  • Tags matching semantic version (1.2.3, 1.2.3-rc.1) or date-based (2023-04-17) patterns
  • Scheduled runs for automatic database caching

Maintenance​

Enable debug mode​

To get verbose output when troubleshooting build failures, enable debug mode by setting the VORTEX_DEBUG variable to 1 in your CI provider's settings.

Update CI runner image​

The CI jobs run inside the drevops/ci-runner container - a Docker image specifically designed for CI job execution. It provides a consistent, reproducible environment with 25+ pre-installed tools:

  • PHP & Node.js - PHP 8.4, Node.js, Composer, npm, Yarn
  • Docker tools - Docker, Docker Compose, Docker Buildx
  • Code quality - ShellCheck, shfmt, Bats testing framework
  • Utilities - Git, curl, rsync, jq, and more

Using this image ensures all CI runs have identical tooling, eliminating environment inconsistencies between local development and CI. It also massively speeds up builds by avoiding repetitive installation of common tools.

To update to a newer version, change the image tag in your CI configuration file. The image follows CalVer versioning (e.g., 25.10.0) with monthly releases.

Ignore tool failures​

Sometimes you may want to allow builds to pass despite linter and test failures.

Set the corresponding VORTEX_CI_*_IGNORE_FAILURE variable to 1 to ignore failures (but still run the tool and see the results in the logs):

VariableTool
VORTEX_CI_COMPOSER_VALIDATE_IGNORE_FAILUREComposer validate
VORTEX_CI_COMPOSER_AUDIT_IGNORE_FAILUREComposer audit
VORTEX_CI_COMPOSER_NORMALIZE_IGNORE_FAILUREComposer normalize
VORTEX_CI_HADOLINT_IGNORE_FAILUREHadolint (Dockerfile)
VORTEX_CI_DCLINT_IGNORE_FAILUREDocker Compose lint
VORTEX_CI_PHPCS_IGNORE_FAILUREPHPCS
VORTEX_CI_PHPSTAN_IGNORE_FAILUREPHPStan
VORTEX_CI_RECTOR_IGNORE_FAILURERector
VORTEX_CI_PHPMD_IGNORE_FAILUREPHPMD
VORTEX_CI_TWIG_CS_FIXER_IGNORE_FAILURETwig CS Fixer
VORTEX_CI_GHERKIN_LINT_IGNORE_FAILUREGherkin Lint
VORTEX_CI_NODEJS_LINT_IGNORE_FAILURENode.js/Yarn lint
VORTEX_CI_PHPUNIT_IGNORE_FAILUREPHPUnit
VORTEX_CI_BEHAT_IGNORE_FAILUREBehat

Configure deployment skip conditions​

Sometimes it may be necessary to skip deployments for specific branches or pull requests. For example, you may want to temporarily avoid deploying more changes into already deployed environments which still run CI checks on new commits.

To skip deployments for specific branches, set the VORTEX_DEPLOY_SKIP_BRANCHES variable to a comma-separated list of exact branch names:

VORTEX_DEPLOY_ALLOW_SKIP=1 # Enable deployment skipping
VORTEX_DEPLOY_SKIP_BRANCHES="feature/test,hotfix/urgent,project/experimental"

To skip deployments for specific pull requests, set the VORTEX_DEPLOY_SKIP_PRS variable to a comma-separated list of PR numbers:

VORTEX_DEPLOY_ALLOW_SKIP=1 # Enable deployment skipping
VORTEX_DEPLOY_SKIP_PRS="123,456,789"

To skip all deployments entirely, set VORTEX_DEPLOY_SKIP=1.