Releasing

This section is about releasing your project, the site you built from Vortex, to production. It's for the developer or lead who plans and runs those releases, and it helps you set up a release process and document it for your team.

It covers how code moves between environments, how branches and version numbers work, and where the automation takes over. Releasing the Vortex template itself is a different process, documented in Contributing > Maintenance > Release.

A release process has a few moving parts, and Vortex provides defaults and integration points for each of them:

• Release flow - the sequence of environments that code goes through from development to production
• Versioning workflow - the branching strategy, documented in GitFlow
• Version scheme - the numbering system you choose at install time, documented in Versioning. CalVer is the default, which .env stores as VORTEX_RELEASE_VERSION_SCHEME=calver
• Release documentation - your project's own docs/releasing.md
• Automated deployment - the CI pipeline and hosting integrations that do the technical work

Release flow

The release flow on this page uses 3 environments. Code moves "up" through the environments while the database moves "down":

  code:     Development ───► Stage ───► Production
  database: Development ◄─── Stage ◄─── Production

Each environment has its own job:

• Development - the latest development code, not released yet. It can be unstable, but its CI tests should pass.
• Stage - the pre-production environment. It mirrors production as closely as possible and hosts the final release testing.
• Production - the live, customer-facing site. It's stable and reliable, and it's the source of truth for data.

The production database is the primary source of truth: it's what your code gets applied to. A release applies a new version of the code to the database of a specific environment. To make sure code changes work with real data, the lower environments test against a copy of the production database:

1. Copy the database from a higher environment to a lower one (for example, production → stage → development).
2. Deploy the code to that environment.
3. Test that everything works against the copied database.

When your site provisions from a database dump, the CI pipeline runs all its tests against a copy of the production database too, refreshed daily. Code changes are then validated against real data structures as well.

Environment agreement

Agree on the specific environment setup (development, stage, production) within your team, and document it in your project. Some teams add environments, for example for user acceptance testing (UAT) or pre-production, or use different names.

Production deployment process

Deploying a release to production is technically the same as deploying to any other environment. CI builds and tests the release tag, or the production branch on branch-based hosting, when it reaches the repository. CI then deploys it under the same rules as any other branch or tag (see GitFlow). Those rules don't cover every tag: CircleCI deploys only tags named like 1.2.3, 1.2.3-rc.1, or 2023-04-17, and the Lagoon deployment type skips tags.

On Acquia and Lagoon hosting, Vortex integrates directly with the platform's own deployment system. On other hosting, wire the provision steps into your host's deployment configuration, as long as it supports post-deployment hooks or custom scripts.

On Lagoon, Vortex treats an environment as production when Lagoon marks it so, or when its branch is the one in ENVIRONMENT_PRODUCTION_BRANCH, which .env ships as main. To release from a production branch, set that variable to production. Then rename the main entry under environments in .lagoon.yml, which holds the production cron jobs and monitoring.

A deployment keeps the database of a site that already exists: provisioning replaces it only when VORTEX_PROVISION_OVERRIDE_DB is 1, and .env ships it as 0. On Lagoon, a production deployment also backs up the database first and skips sanitization. On a site that provisions from a database dump, the Lagoon production deployment also forces VORTEX_PROVISION_OVERRIDE_DB=0, so even a Lagoon variable set to 1 can't replace the production database.

➡️ See Development > Provision to learn what provisioning steps run during deployments.

Documentation

Each project keeps its own release documentation next to the code.

docs/releasing.md

Your project's docs/releasing.md file is the canonical release documentation for your team. As shipped, it records the expected release outcome and your project's version scheme (left out if you chose Other), and it leaves a marked section for project-specific configuration.

Extend it with the following sections:

• Detailed release procedures - an outline of what actions to take during releases: creating and finishing releases, deploying to production, rolling back, verifying.
• A release run template - a checklist of who does what and when during a release, cloned into a separate runsheet for each release.

Monitoring

After a release, monitoring shows how the released code behaves in production.

New Relic integration

Vortex integrates with New Relic for release tracking. To turn it on, add newrelic to VORTEX_NOTIFY_CHANNELS in .env. Then, in your hosting provider's environment variables, set VORTEX_NOTIFY_NEWRELIC_ENABLED to true and VORTEX_NOTIFY_NEWRELIC_USER_KEY to a New Relic user key. After that, deployments create a deployment marker in New Relic, so you can line up performance changes and errors with the release that caused them.

By default, markers go out only for deployments of the main, master, and develop branches, matched by exact name. If production deploys from a branch named production, set VORTEX_NOTIFY_NEWRELIC_BRANCHES to main,master,develop,production: your list replaces the default instead of extending it. A tag release deployed to Acquia arrives under a name such as deployment/1.2.3, which no entry matches, so it gets no marker.

To confirm that New Relic recorded a marker, look for this line in the deployment output:

[ OK ] Created deployment notification for application <app> with ID <id>.

The channel also exits with code 0 when it skips the marker, for example for an unlisted branch, so a deployment that passes doesn't prove that the marker exists.

➡️ See Deployment > Notifications > New Relic

See also

The following pages cover the rest of the release process:

Topic	Description
GitFlow	Branch structure and release operations
Versioning	CalVer, SemVer, and custom version schemes