Version: v2

Lagoon deployment

Lagoon deployment asks the Lagoon hosting platform to deploy your branch or pull request, using the Lagoon CLI. Lagoon pulls the code from your repository and builds it itself, so nothing gets packaged in CI.

This page is for the lead or DevOps engineer who connects a project's CI to Lagoon. It covers what the deployment script asks Lagoon to do, the variables that configure it, and the setup steps. For how the site runs on Lagoon after a deployment, see Lagoon hosting.

How it works

When lagoon is included in $VORTEX_DEPLOY_TYPES, the deployment script finds the Lagoon CLI and points it at the configured Lagoon instance. Over SSH, the script requests a deployment for the current branch or pull request. Lagoon then runs these steps:

Pulls the latest code from your repository
Builds container images using your docker-compose.yml
Deploys containers to Kubernetes
Runs post-rollout tasks defined in .lagoon.yml

The script uses the lagoon binary on the path when there is one. Otherwise it reuses a binary it downloaded earlier, or downloads the pinned release into VORTEX_LAGOONCLI_PATH and checks it against the release's published checksums.

The script doesn't wait for the Lagoon build: it finishes after Lagoon accepts the request. Watch the build in the environment's deployments in the Lagoon UI.

Before it deploys, the script checks whether Lagoon already has an environment for the branch or pull request. A new branch or pull request gets a fresh deployment, and an existing environment gets a redeployment.

For a redeployment, the script sets VORTEX_PROVISION_OVERRIDE_DB on the environment while Lagoon queues the build: 1 when the deployment action is deploy_override_db, and 0 otherwise. The script then restores the variable to its earlier state, or removes it if the environment didn't have one. If the script can't read the environment's variables, it leaves the flag alone and prints a warning.

Lagoon decides which branches get an environment. Lagoon filters out a new branch that doesn't match the project's deployment pattern, and a pull request when the project doesn't deploy pull requests. The destroy action deletes the branch's environment instead of deploying it.

When Lagoon refuses a deployment because the project has reached its environment limit, the script reports it. The build still passes, unless you set VORTEX_DEPLOY_LAGOON_FAIL_ENV_LIMIT_EXCEEDED to 1 to fail it. Any other failure prints the Lagoon CLI output and fails the build.

Lagoon doesn't support tag deployments, so the script reports this, skips the deployment, and passes.

Configuration

Configure the deployment with the variables in the following table, then follow the setup steps.

Environment variables

The Deployment overview explains the Location values and how the script loads .env. The following table lists the variables that the Lagoon deployment script reads:

Variable	Required	Default	Location	Description
`VORTEX_DEPLOY_LAGOON_PROJECT`	Yes, unless `LAGOON_PROJECT` is set	Value of `LAGOON_PROJECT`	`.env`	Your Lagoon project name
`VORTEX_DEPLOY_LAGOON_INSTANCE`	No	`amazeeio`	`.env`	Lagoon instance name
`VORTEX_DEPLOY_LAGOON_INSTANCE_GRAPHQL`	No	`https://api.lagoon.amazeeio.cloud/graphql`	`.env`	Lagoon GraphQL endpoint
`VORTEX_DEPLOY_LAGOON_INSTANCE_HOSTNAME`	No	`ssh.lagoon.amazeeio.cloud`	`.env`	Lagoon SSH hostname
`VORTEX_DEPLOY_LAGOON_INSTANCE_PORT`	No	`32222`	`.env`	Lagoon SSH port
`VORTEX_DEPLOY_LAGOON_BRANCH`	No	Value of `VORTEX_DEPLOY_BRANCH`	CI	Branch to deploy
`VORTEX_DEPLOY_LAGOON_PR`	No	Value of `VORTEX_DEPLOY_PR`	CI	Pull request number to deploy
`VORTEX_DEPLOY_LAGOON_PR_HEAD`	No	Value of `VORTEX_DEPLOY_PR_HEAD`	CI	Head commit of the pull request
`VORTEX_DEPLOY_LAGOON_PR_BASE_BRANCH`	No	Value of `VORTEX_DEPLOY_PR_BASE_BRANCH`, then `develop`	CI	Branch the pull request targets; the shipped CI configs don't set it
`VORTEX_DEPLOY_LAGOON_ACTION`	No	Value of `VORTEX_DEPLOY_ACTION`, then `create`	CI	Deployment action: `destroy` deletes the environment, `deploy_override_db` overwrites the database on a redeployment, and any other value deploys
`VORTEX_DEPLOY_LAGOON_SSH_FINGERPRINT`	No	Value of `VORTEX_DEPLOY_SSH_FINGERPRINT`, then `VORTEX_SSH_FINGERPRINT`	CI	Fingerprint of the SSH key used to authenticate
`VORTEX_DEPLOY_LAGOON_SSH_FILE`	No	Value of `VORTEX_DEPLOY_SSH_FILE`, then `VORTEX_SSH_FILE`, then `~/.ssh/id_rsa`	CI	SSH key file used when no fingerprint is set
`VORTEX_DEPLOY_LAGOON_FAIL_ENV_LIMIT_EXCEEDED`	No	`0`	CI	Fail the build when the Lagoon environment limit is exceeded (`1`) or pass it (`0`)
`VORTEX_LAGOONCLI_VERSION`	No	`v0.32.0`	CI	Lagoon CLI release to download when the path has no `lagoon` binary
`VORTEX_LAGOONCLI_PATH`	No	`.artifacts/tmp`	CI	Directory the Lagoon CLI is downloaded into

CI sets the branch and pull request variables for you. The Variables reference lists the project-level variables that .env and the CI configs set.

Setup

To set up Lagoon deployment, complete these steps:

Add lagoon to the comma-separated VORTEX_DEPLOY_TYPES list in your .env file. On its own, it looks like this:
.env
```
VORTEX_DEPLOY_TYPES=lagoon
```
Set your Lagoon project name in your .env file:
.env
```
LAGOON_PROJECT=your-project-name
```
Give CI an SSH key that your Lagoon user accepts:
- On GitHub Actions, add the private key as the VORTEX_DEPLOY_SSH_PRIVATE_KEY repository secret.
- On CircleCI, add the private key under Project Settings → SSH Keys and set its fingerprint as deploy_ssh_fingerprint in .circleci/config.yml.
The CLI connects over SSH, so a missing key fails the deployment.

Confirm that the next deployment reached Lagoon. The deploy job log shows Requested the environment deployment. or Requested the environment redeployment., followed by [ OK ] Finished Lagoon deployment. That line means Lagoon accepted the request; the build's own result shows in the Lagoon UI.

Post-deployment automation

After Lagoon rolls out the new containers, the post-rollout tasks defined in .lagoon.yml back up or fetch the database, provision the site, and send notifications. See Lagoon hosting for every step.

Environments

The shipped .lagoon.yml sets up the environments with the following settings:

A drush cron job every 15 minutes and monitoring URLs for the main and develop branches.
A redirect from HTTP to HTTPS on every route (the routes key sets insecure to Redirect).
The deployed Git SHA as an environment variable (git_sha: 'true'), which the notifications use.
Commented-out blocks for a custom SSL certificate and for private container registries.

The post-rollout tasks in .lagoon.yml treat an environment as production when Lagoon marks it as such or when the branch matches ENVIRONMENT_PRODUCTION_BRANCH (default: main).

You configure which branches get an environment, their types, and pull request (ephemeral) environments per project in Lagoon itself. See Lagoon environment types.

On GitHub, the shipped .github/workflows/close-pull-request.yml workflow runs when a pull request closes. The workflow forwards the event to the Lagoon webhook endpoint, so Lagoon removes the pull request's environment. The endpoint defaults to https://hooks.lagoon.amazeeio.cloud/; to use another Lagoon instance, set LAGOON_WEBHOOK_ENDPOINT in the workflow's environment.

The Vortex CLI keeps this workflow for CircleCI projects too, so Lagoon still removes pull request environments when GitHub Actions is enabled for the repository. Nothing in the CircleCI config removes them.

How it works​

Configuration​

Environment variables​

Setup​

Post-deployment automation​

Environments​

See also​