Releasing

This section covers releasing your project, the site you built from Vortex, to production. It's for the developer or lead who plans and runs those releases. Use it to 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 separate process, documented in Contributing > Maintenance > Release.

A release process has these 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, and 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.

A release runs a new version of the code against the database of a specific environment. Production holds the primary database. To test code against real data in a lower environment:

1. Copy the database from a higher environment to a lower environment, 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 also runs all its tests against a copy of the database from the configured source, refreshed daily. When the source is production, CI checks code changes against real data structures too.

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

A production deployment works the same way as a deployment to any other environment. CI builds and tests the release tag when you push it, or the production branch on branch-based hosting. CI then deploys the tag or branch under the same rules as any other branch or tag (see GitFlow).

Some tags don't deploy:

• CircleCI deploys only tags named like 1.2.3, 1.2.3-rc.1 or 2023-04-17.
• 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 your host supports post-deployment hooks or custom scripts.

On Lagoon, Vortex treats an environment as production in 2 cases: Lagoon marks it as production, or its branch is the branch in VORTEX_LAGOON_PRODUCTION_BRANCH, which .env ships as main. To release from a production branch:

1. Set VORTEX_LAGOON_PRODUCTION_BRANCH to production.
2. Rename the main entry under environments in .lagoon.yml to production. That entry 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 forces VORTEX_PROVISION_OVERRIDE_DB=0, so a value of 1 set in Lagoon has no effect on production.

➡️ 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 holds 3 sections:

• The expected release outcome
• Your project's version scheme, left out if you chose Other
• 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 and verifying.
• A release run template - a checklist of who does what and when during a release, which you clone 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. Deployments create a deployment marker in New Relic, so you can line up performance changes and errors with the release that caused them.

To turn the markers on:

1. Add newrelic to VORTEX_NOTIFY_CHANNELS in .env.
2. In your hosting provider's environment variables, set VORTEX_NOTIFY_NEWRELIC_ENABLED to true.
3. In the same place, set VORTEX_NOTIFY_NEWRELIC_USER_KEY to a New Relic user key.

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, because your own list replaces the default. 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, followed by how long the request took:

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

The New Relic notification script also exits with code 0 when it skips the marker, for example for an unlisted branch. A passing deployment 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