GitHub Actions

GitHub Actions is GitHub's built-in continuous integration and delivery platform that automates the build, test, and deployment process directly from your repository.

For general GitHub Actions documentation, refer to the GitHub Actions Documentation.

info

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

Onboarding

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

Maintenance

Update deployment branches

The workflow triggers on pushes and pull requests to specific branches defined in the on.push.branches and on.pull_request.branches sections of .github/workflows/build-test-deploy.yml:

Push triggers (direct pushes and merges):

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)
project/**	Long-lived project branches for large initiatives

Pull request triggers (PRs targeting these branches):

Pattern	Description
All push branches above	Same as push triggers
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)

Short-lived branches like feature/** and bugfix/** only trigger CI through pull requests, not on direct pushes.

To add or remove branches, update the push and pull_request sections in the workflow file.

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 schedule.cron value ( cron format, UTC timezone):

schedule:
  - cron: '0 18 * * *'  # 6 PM UTC daily

Change runner size

For faster builds, you can use larger runners in the job configuration. Note that this may affect your GitHub billing:

runs-on: ubuntu-latest-4-cores  # Options: ubuntu-latest, ubuntu-latest-4-cores, etc.

Change test parallelism

To speed up test execution, you can increase the number of parallel runners in the build job matrix. See Using a matrix for your jobs for more information:

strategy:
  matrix:
    instance: [0, 1, 2, 3]  # 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.

Manual deployment

The workflow supports triggering deployments directly from the GitHub UI without running lint, build, or test jobs. Navigate to Actions → Database, Build, Test and Deploy → Run workflow and provide:

Input	Description
deploy_target	Branch name (e.g., develop) or PR reference (e.g., PR-123, case-insensitive)
override_db	Override the existing database in the deployment environment

When deploy_target is set, all other jobs are skipped and only the deploy job runs. For PR targets, the workflow resolves the PR's head branch and commit SHA automatically.

When override_db is checked, the database in the existing deployment environment will be overridden with a fresh copy taken from the production environment.

note

Artifact-based deployments do not work with manual deploys as the build job is skipped.

Terminal access for debugging

The workflow includes a tmate session for debugging. Trigger a manual workflow run with the Enable terminal session for CI jobs option checked to get SSH connection details in the build logs. See action-tmate for more information.

Adjust build timeout

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

- name: Long running task
  run: ./scripts/long-task.sh
  timeout-minutes: 60  # Default is 360 (6 hours)

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 variable in Settings → Secrets and variables → Actions → Variables. Default is 90 (percent).

Coverage reports are automatically posted as PR comments. Each new report replaces the previous one — older comments are minimized to keep the PR timeline clean. To disable this, set VORTEX_CI_CODE_COVERAGE_PR_COMMENT_SKIP to 1.

Test results

PHPUnit and Behat results are published to the Checks tab of each run, so a failed check links directly to the failing tests and their messages instead of requiring you to download artifacts or search through logs. Results are read from the JUnit reports the test tools already generate, so no extra setup is required.

Tests run across parallel build instances, so a separate check is created for each instance (for example, Test results (0) and Test results (1)). To disable publishing, set VORTEX_CI_TEST_RESULTS_SKIP to 1 in Settings → Secrets and variables → Actions → Variables.