Environments and deployments

In a job script, you can specify a static environment URL. However, there may be times when you want a dynamic URL. For example, if you deploy a Review App to an external hosting service that generates a random URL per deployment, like https://94dd65b.amazonaws.com/qa-lambda-1234567. In this case, you don’t know the URL before the deployment script finishes. If you want to use the environment URL in GitLab, you would have to update it manually.

To address this problem, you can configure a deployment job to report back a set of variables. These variables include the URL that was dynamically-generated by the external service. GitLab supports the environment:url value with variables defined in the .env file.

To use this feature, specify the artifacts:reports:dotenv keyword in .gitlab-ci.yml.

For an overview, see .

Example of setting dynamic environment URLs

The following example shows a Review App that creates a new environment for each merge request. The review job is triggered by every push, and creates or updates an environment named review/your-branch-name. The environment URL is set to $DYNAMIC_ENVIRONMENT_URL:

review:
  script:
    - DYNAMIC_ENVIRONMENT_URL=$(deploy-script)                                 # In script, get the environment URL.
    - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env    # Add the value to a dotenv file.
  artifacts:
    reports:
      dotenv: deploy.env                                                       # Report back dotenv file to rails.
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: $DYNAMIC_ENVIRONMENT_URL                                              # and set the variable produced in script to `environment:url`
    on_stop: stop_review

stop_review:
  script:
    - ./teardown-environment
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

As soon as the review job finishes, GitLab updates the review/your-branch-name environment’s URL. It parses the deploy.env report artifact, registers a list of variables as runtime-created, uses it for expanding environment:url: $DYNAMIC_ENVIRONMENT_URL and sets it to the environment URL. You can also specify a static part of the URL at environment:url, such as https://$DYNAMIC_ENVIRONMENT_URL. If the value of DYNAMIC_ENVIRONMENT_URL is example.com, the final result is https://example.com.

The assigned URL for the review/your-branch-name environment is visible in the UI.

Note the following:

• stop_review doesn’t generate a dotenv report artifact, so it doesn’t recognize the DYNAMIC_ENVIRONMENT_URL environment variable. Therefore you shouldn’t set environment:url in the stop_review job.
• If the environment URL isn’t valid (for example, the URL is malformed), the system doesn’t update the environment URL.
• If the script that runs in stop_review exists only in your repository and therefore can’t use GIT_STRATEGY: none, configure merge request pipelines for these jobs. This ensures that runners can fetch the repository even after a feature branch is deleted. For more information, see Ref Specs for Runners.

Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL"

Track newly included merge requests per deployment

GitLab can track newly included merge requests per deployment. When a deployment succeeded, the system calculates commit-diffs between the latest deployment and the previous deployment. This tracking information can be fetched via the Deployment API and displayed at a post-merge pipeline in merge request pages.

To activate this tracking, your environment must be configured in the following:

• Environment name is not foldered with / (that is, top-level/long-lived environments), OR
• Environment tier is either production or staging.

Here are the example setups of environment keyword in .gitlab-ci.yml:

# Trackable
environment: production
environment: production/aws
environment: development

# Non Trackable
environment: review/$CI_COMMIT_REF_SLUG
environment: testing/aws

Working with environments

Once environments are configured, GitLab provides many features for working with them, as documented below.

Environment rollback

When you roll back a deployment on a specific commit, a new deployment is created. This deployment has its own unique job ID. It points to the commit you’re rolling back to.

For the rollback to succeed, the deployment process must be defined in the job’s script.

Retry or roll back a deployment

If there is a problem with a deployment, you can retry it or roll it back.

To retry or rollback a deployment:

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Deployments > Environments.
3. Select the environment.
4. To the right of the deployment name:
   • To retry a deployment, select Re-deploy to environment.
   • To roll back to a deployment, next to a previously successful deployment, select Rollback environment.

Environment URL

The environment URL is displayed in a few places in GitLab:

• In a merge request as a link:
• In the Environments view as a button:
• In the Deployments view as a button:

You can see this information in a merge request if:

• The merge request is eventually merged to the default branch (usually main).
• That branch also deploys to an environment (for example, staging or production).

For example:

Go from source files to public pages

With GitLab Route Maps, you can go directly from source files to public pages in the environment set for Review Apps.

Stop an environment

When you stop an environment:

• On the Environments page, it moves from the list of Available environments to the list of Stopped environments.
• An on_stop action, if defined, is executed.

Dynamic environments stop automatically when their associated branch is deleted.

Stop an environment when a branch is deleted

You can configure environments to stop when a branch is deleted.

The following example shows a deploy_review job that calls a stop_review job to clean up and stop the environment.

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop_review
  rules:
    - if: $CI_MERGE_REQUEST_ID

stop_review:
  stage: deploy
  script:
    - echo "Remove review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: manual

Both jobs must have the same rules or only/except configuration. Otherwise, the stop_review job might not be included in all pipelines that include the deploy_review job, and you cannot trigger action: stop to stop the environment automatically.

The job with action: stop might not run if it’s in a later stage than the job that started the environment.

If you can’t use merge request pipelines, set the GIT_STRATEGY to none in the stop_review job. Then the runner doesn’t try to check out the code after the branch is deleted.

Read more in the .gitlab-ci.yml reference.

Stop an environment when another job is finished

You can set an environment to stop when another job is finished.

In your .gitlab-ci.yml file, specify in the on_stop keyword the name of the job that stops the environment.

The following example shows a review_app job that calls a stop_review_app job after the first job is finished. The stop_review_app is triggered based on what is defined under when. In this case, it is set to manual, so it needs a manual action from the GitLab UI to run.

Both jobs must have the same rules or only/except configuration. In this example, if the configuration is not identical:

• The stop_review_app job might not be included in all pipelines that include the review_app job.
• It is not possible to trigger the action: stop to stop the environment automatically.

Also in the example, GIT_STRATEGY is set to none. If the stop_review_app job is automatically triggered, the runner won’t try to check out the code after the branch is deleted.

The example also overwrites global variables. If your stop environment job depends on global variables, use anchor variables when you set the GIT_STRATEGY to change the job without overriding the global variables.

The stop_review_app job must have the following keywords defined:

• when, defined at either:
  • The job level.
  • In a rules clause. If you use rules and when: manual, you should also set allow_failure: true so the pipeline can complete even if the job doesn’t run.
• environment:name
• environment:action

review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop_review_app

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

Stop an environment after a certain time period

review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    on_stop: stop_review_app
    auto_stop_in: 1 week
  rules:
    - if: $CI_MERGE_REQUEST_ID

stop_review_app:
  script: stop-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: manual

deploy-to-cloud-a:
  script: echo "Deploy to cloud a"
  environment:
    name: test
    on_stop: teardown-cloud-a

deploy-to-cloud-b:
  script: echo "Deploy to cloud b"
  environment:
    name: test
    on_stop: teardown-cloud-b

teardown-cloud-a:
  script: echo "Delete the resources in cloud a"
  environment:
    name: test
    action: stop
  when: manual

teardown-cloud-b:
  script: echo "Delete the resources in cloud b"
  environment:
    name: test
    action: stop
  when: manual

build:
  stage: build
  script:
    - echo "Building the app"
  environment:
    name: staging
    action: prepare
    url: https://staging.example.com

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG

fetch = +refs/environments/*:refs/remotes/origin/environments/*

deploy:
  script: echo
  environment: production/$ENVIRONMENT

review:
  script: deploy review app
  environment: review/$CI_COMMIT_REF_NAME

Project.find_by_full_path(<your-project-full-path>).deployments.where(archived: true).each(&:create_ref)