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/bin/vortex-deploy.
The script runs in the continuous integration pipeline's deploy job after the
build and lint jobs pass. (On GitHub Actions, a
manual deployment
can also run the deploy job on its own.)
The script deploys the code to a remote location by calling the
relevant scripts based on the type of deployment defined in the $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- The Lagoon CLI is used to trigger a deployment on the Lagoon platform.
Once the code lands on the hosting platform, the platform provisions the site
and sends notifications - that part runs on the hosting
side, not in the deploy job.
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 ────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─ Database Job (Nightly) ───────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Scheduled ──► Download production ──► Sanitize database ──► Store database cache │ │
│ │ trigger database Remove sensitive data │ │
│ │ │ │
│ └─────────────────────────────────────┬──────────────────────────────────────────────┘ │
│ │ Provides cached database │
│ ▼ │
│ ┌─ Lint Job ────────────┐ ┌─ Database Job ────────────────┐ ┌─ Audit Job ──────────┐ │
│ │ │ │ ◆ Nightly cache exists? │ │ Composer audit │ │
│ │ Build CLI container │ │ Yes ──► job succeeds │ │ (advisories) │ │
│ │ ▼ │ │ No ──► download, sanitize, │ │ ▼ │ │
│ │ Composer validate │ │ store cache │ │ Gitleaks │ │
│ │ ▼ │ └───────────────┬───────────────┘ │ (committed secrets) │ │
│ │ Composer normalize │ ▼ │ │ │
│ │ ▼ │ ┌─ Build Job ───────────────────┐ │ │ │
│ │ Hadolint │ │ Code assembly │ │ │ │
│ │ ▼ │ │ Docker, Composer deps, │ │ │ │
│ │ DCLint │ │ NPM deps, assets │ │ │ │
│ │ ▼ │ │ ▼ │ │ │ │
│ │ PHPCS │ │ Website setup │ │ │ │
│ │ ▼ │ │ Import cached DB, drush │ │ │ │
│ │ PHPStan │ │ deploy, custom scripts │ │ │ │
│ │ ▼ │ │ ▼ │ │ │ │
│ │ Rector │ │ Testing │ │ │ │
│ │ ▼ │ │ PHPUnit tests ──► Behat tests │ │ │ │
│ │ Twig CS Fixer │ └───────────────┬───────────────┘ │ │ │
│ │ ▼ │ │ │ │ │
│ │ Gherkin Lint │ │ │ │ │
│ │ ▼ │ │ │ │ │
│ │ ESLint / Stylelint │ │ │ │ │
│ │ │ │ │ │ │
│ └──────────┬────────────┘ │ │ │ │
│ │ │ │ │ │
│ ▼ ▼ │ │ │
│ ┌─ Deployment Job ─────────────────────────────────────────┐ │ │ │
│ │ │ │ │ │
│ │ Webhook Artifact Lagoon │ │ Does not gate │ │
│ │ Call URL Package artifact Run Lagoon CLI deploy │ │ deployment │ │
│ │ │ │ │ │
│ └──────────────────────────────────────────────────────────┘ └──────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────────────┘
│
▼
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:
productionmainmasterdeveloprelease/**hotfix/**project/**
This runs 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 runs for the pull request's branch. Depending on the hosting platform, this may create a temporary environment named after the pull request.
Short-lived feature/* and bugfix/* branches deploy through their pull
requests rather than through direct pushes - deploying both the push and the
PR would double every CI run and deployment. Branches created by automated
dependency updates (deps/*) never deploy.
project/* branches are long-lived branches typically used for larger
features or projects spanning multiple pull requests - for example, a
migration branch whose code and configuration are not ready to merge into
develop but need a remote environment for testing. Such branches are
manually synced with develop and deploy on direct pushes.
The exact patterns differ slightly per provider - see GitHub Actions > Update trigger branches and CircleCI > Update deployment branches.
Deployment action
By default, an existing database is retained during a deployment.
The $VORTEX_DEPLOY_ACTION variable changes what a deployment does:
deploy(default) - deploy the code and preserve the environment's database.deploy_override_db- deploy the code and overwrite the database with a fresh copy from the production environment.destroy- remove the deployed environment, on platforms that support it (Lagoon).
Skipping deployments
You can skip all deployments by setting the VORTEX_DEPLOY_SKIP environment
variable to 1.
This is useful when you want the continuous integration pipeline 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.
See also
| Topic | Description |
|---|---|
| Webhook | Deploy by calling a webhook URL |
| Artifact | Deploy code artifacts to remote repositories |
| Lagoon | Deploy to the Lagoon hosting platform |
| Notifications | Send deployment notifications |