Deployment

Deployment to a remote location is performed by the deploy router script shipped via the drevops/vortex-tooling Composer package and installed at vendor/drevops/vortex-tooling/src/vortex-deploy.

The script runs in continuous integration pipeline deploy job only after all tests pass.

The script deploys the code to a remote location by calling the relevant scripts based on the type of deployment defined in $VORTEX_DEPLOY_TYPES variable as a comma-separated list of one or multiple supported deployment types:

webhook - A webhook URL is called via CURL.
artifact - A code artifact is created and sent to a remote repository.
lagoon - A Lagoon webhook URL is called via CURL to trigger a deployment.

Expand to see deployment in the complete code lifecycle

                                    Local Development
 ═════════════════════════════════════════════════════════════════════════════════════════
           Developer writes code ──► Build and test locally ──► Commit changes
                                            │
                                            ▼
                                      Git Repository
 ═════════════════════════════════════════════════════════════════════════════════════════
                   Push to remote branch ──► Open/Update Pull Request
                                            │
                                            ▼
┌─ CI Pipeline ──────────────────────────────────────────────────────────────────────────────┐
│                                                                                            │
│  The Lint, Test and Build jobs run in parallel. Deployment runs after all three pass.      │
│                                                                                            │
│  Lint Job                                                                                  │
│    Build CLI container ──► Composer validate / audit / normalize ──► Hadolint ──►          │
│    DCLint ──► PHPCS ──► PHPStan ──► Rector ──► Twig CS Fixer ──►                           │
│    Gherkin Lint ──► ESLint / Stylelint                                                     │
│                                                                                            │
│  Test Job                                                                                  │
│    Restore the database cache. On the first build of the day (cache miss), each runner     │
│    downloads the production database and exports a clean pre-provision dump; only the      │
│    primary runner stores it in the cache for the rest of the day's builds.                 │
│      ▼                                                                                     │
│    Build Docker ──► Composer deps ──► NPM deps ──► Assets                                  │
│      ▼                                                                                     │
│    Import cached database ──► drush deploy ──► custom deploy steps                         │
│      ▼                                                                                     │
│    PHPUnit tests ──► Behat tests                                                           │
│                                                                                            │
│  Build Job                                                                                 │
│    Assemble and validate the deployable artifact                                           │
│                                                                                            │
│  Deployment Job (after Lint, Test and Build pass)                                          │
│    Webhook URL ──► artifact package ──► Lagoon webhook ──► Docker container image          │
│                                                                                            │
└────────────────────────────────────────────────────────────────────────────────────────────┘
                                            │
                                            ▼
                                     Hosting Platform
 ═════════════════════════════════════════════════════════════════════════════════════════
 ◆ Environment ──No──► Sync DB from production ───┐
   exists?                                        │
      │ Yes                                       ▼
      └──────────────────────────────────► drush deploy ──► Custom scripts ──► Notifications


                                  Available Environments
 ═════════════════════════════════════════════════════════════════════════════════════════
        ┊ PR Environment ┊    Dev             Staging          Production
        ┊ (auto-removed) ┊    develop branch  main branch      production branch or tag

Deployment targets

Deployment targets can be branches and pull requests. These targets are defined in the CI configuration files and the hosting platform.

By default, deployments are triggered when commits are pushed into the following branches:

production
main
master
develop
release/**
hotfix/**
project/**

This will run the deployment script to forward the code to the remote hosting platform and tell it to use the current branch's code for the deployment.

When a pull request is raised against one of the branches above, a deployment will run for the pull request's branch. Depending on the hosting platform, this may create a temporary environment for the pull request with the name of the pull request.

Note that feature/* or bugfix/* (or any other branches) branches are not included in the default list of deployment targets. This is to prevent deployments from branches that are typically short-lived and have a pull request raised, which will trigger a deployment. Adding these branches to the list of deployment targets will lead to duplicated CI runs and deployments.

project/* branches are long-lived branches that are typically used for larger features or projects that may span multiple pull requests. Such branches would be manually synced with the develop branch and deployed to a remote environment for testing. An example of this would be a migration branch that has migration code and configuration that is not yet ready to be merged into develop but needs to be deployed to a remote environment for testing.

Deployment action

By default, an existing database will be retained during a deployment.

To change this behavior and overwrite the database with a fresh copy from production environment, set the $VORTEX_DEPLOY_ACTION variable to deploy_override_db.

Skipping deployments

You can skip all deployments by setting the VORTEX_DEPLOY_SKIP environment variable to 1.

This is especially useful in continuous integration pipelines where you may want to build and test without triggering a deployment.

Skipping deployments for specific pull requests or branches

To skip specific Pull Requests or branches, set $VORTEX_DEPLOY_ALLOW_SKIP to 1 and provide lists in the following variables:

Skipping specific pull requests

Set $VORTEX_DEPLOY_SKIP_PRS to a single PR number or comma-separated list:

# Skip a single PR
VORTEX_DEPLOY_ALLOW_SKIP=1
VORTEX_DEPLOY_SKIP_PRS=42

# Skip multiple PRs
VORTEX_DEPLOY_ALLOW_SKIP=1
VORTEX_DEPLOY_SKIP_PRS=42,123,456

Skipping specific branches

Set $VORTEX_DEPLOY_SKIP_BRANCHES to a single branch name or comma-separated list:

# Skip a single branch
VORTEX_DEPLOY_ALLOW_SKIP=1
VORTEX_DEPLOY_SKIP_BRANCHES=feature/test

# Skip multiple branches
VORTEX_DEPLOY_ALLOW_SKIP=1
VORTEX_DEPLOY_SKIP_BRANCHES=feature/test,hotfix/urgent,project/experimental

Combined usage

You can use both variables together:

VORTEX_DEPLOY_ALLOW_SKIP=1
VORTEX_DEPLOY_SKIP_PRS=42,123
VORTEX_DEPLOY_SKIP_BRANCHES=feature/test,hotfix/urgent

Gating deployments on a PR label

Skipping is subtractive - everything deploys unless you exclude it. The label gate is the opposite: it makes a pull request deployment opt-in, so a PR reaches an environment only when it is explicitly labeled for it. This is useful for controlling the number and cost of per-PR environments, or for keeping work-in-progress pull requests out of environments.

Set $VORTEX_DEPLOY_ALLOW_LABEL to the name of the label that authorizes deployment:

VORTEX_DEPLOY_ALLOW_LABEL=deploy

With this set, a pull request is deployed only if it carries the deploy label; pull requests without it are skipped. When the variable is empty or unset (the default), the gate is inactive and deployments behave as before.

The gate applies only to pull request builds. Branch and tag deployments have no associated pull request label and are never gated.

The pull request's labels are read from $VORTEX_DEPLOY_PR_LABELS, a comma-separated list that the CI provider populates from the pull request event. On GitHub Actions this is wired up automatically. On CircleCI the labels are not available natively, so populate $VORTEX_DEPLOY_PR_LABELS yourself (for example, from the GitHub API) to use the gate.

The label gate and the skip lists can be combined. A skip-list match is evaluated first and always wins, so a pull request listed in $VORTEX_DEPLOY_SKIP_PRS is skipped even when it carries the gate label.

Topic	Description
Webhook	Deploy by calling a webhook URL
Artifact	Deploy code artifacts to remote repositories
Lagoon	Deploy to Lagoon hosting platform
Notifications	Send deployment notifications

Deployment targets​

Deployment action​

Skipping deployments​

Skipping deployments for specific pull requests or branches​

Skipping specific pull requests​

Skipping specific branches​

Combined usage​

Gating deployments on a PR label​

See also​