Environments and deployments

Environments describe where code is deployed.

Each time GitLab CI/CD deploys a version of code to an environment, a deployment is created.

GitLab:

  • Provides a full history of deployments to each environment.
  • Tracks your deployments, so you always know what is deployed on your servers.

If you have a deployment service like Kubernetes associated with your project, you can use it to assist with your deployments. You can even access a web terminal for your environment from within GitLab.

View environments and deployments

Prerequisites:

  • You must have at least the Reporter role.

To view a list of environments and deployments:

  1. On the top bar, select Menu > Projects and find your project.

  2. On the left sidebar, select Deployments > Environments. The environments are displayed.

    Environments list

  3. To view a list of deployments for an environment, select the environment name, for example, staging.

    Deployments list

Deployments show up in this list only after a deployment job has created them.

Types of environments

There are two types of environments:

  • Static environments have static names, like staging or production.
  • Dynamic environments have dynamic names. Dynamic environments are a fundamental part of Review apps.

Create a static environment

You can create an environment and deployment in the UI or in your .gitlab-ci.yml file.

In the UI:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Environments.
  3. Select New environment.
  4. Enter a name and external URL.
  5. Select Save.

In your .gitlab-ci.yml file:

  1. Specify a name for the environment and optionally, a URL, which determines the deployment URL. For example:

    deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging server"
  environment:
    name: staging
    url: https://staging.example.com

  2. Trigger a deployment. (For example, by creating and pushing a commit.)

When the job runs, the environment and deployment are created.

note
Some characters cannot be used in environment names. For more information about the environment keywords, see the .gitlab-ci.yml keyword reference.

Create a dynamic environment

To create a dynamic name and URL for an environment, you can use predefined CI/CD variables. For example:

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: never
    - if: $CI_COMMIT_BRANCH

In this example:

  • The name is review/$CI_COMMIT_REF_SLUG. Because the environment name can contain slashes (/), you can use this pattern to distinguish between dynamic and static environments.
  • For the url, you could use $CI_COMMIT_REF_SLUG, but because this value may contain a / or other characters that would not be valid in a domain name or URL, use $CI_ENVIRONMENT_SLUG instead. The $CI_ENVIRONMENT_SLUG variable is guaranteed to be unique.

You do not have to use the same prefix or only slashes (/) in the dynamic environment name. However, when you use this format, you can group similar environments.

note
Some variables cannot be used as environment names or URLs. For more information about the environment keywords, see the .gitlab-ci.yml keyword reference.

Deployment tier of environments

Introduced in GitLab 13.10.

Sometimes, instead of using an industry standard environment name, like production, you might want to use a code name, like customer-portal. While there is no technical reason not to use a name like customer-portal, the name no longer indicates that the environment is used for production.

To indicate that a specific environment is for a specific use, you can use tiers:

Environment tier Environment name examples
production Production, Live
staging Staging, Model, Demo
testing Test, QC
development Dev, Review apps, Trunk
other  

By default, GitLab assumes a tier based on the environment name. Instead, you can use the deployment_tier keyword to specify a tier.

Configure manual deployments

You can create a job that requires someone to manually start the deployment. For example:

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual

The when: manual action:

  • Exposes a play button for the job in the GitLab UI, with the text Can be manually deployed to <environment>.
  • Means the deploy_prod job is only triggered when the play button is clicked.

You can find the play button in the pipelines, environments, deployments, and jobs views.

Configure Kubernetes deployments (DEPRECATED)

Version history
caution
This feature was deprecated in GitLab 14.5.

If you are deploying to a Kubernetes cluster associated with your project, you can configure these deployments from your .gitlab-ci.yml file.

note
Kubernetes configuration isn’t supported for Kubernetes clusters that are managed by GitLab. To follow progress on support for GitLab-managed clusters, see the relevant issue.

The following configuration options are supported:

In the following example, the job deploys your application to the production Kubernetes namespace.

deploy:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
    kubernetes:
      namespace: production
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster, you can view cluster and namespace information. On the deployment job page, it’s displayed above the job trace:

Deployment cluster information

Configure incremental rollouts

Learn how to release production changes to only a portion of your Kubernetes pods with incremental rollouts.

CI/CD variables for environments and deployments

When you create an environment, you specify the name and URL.

If you want to use the name or URL in another job, you can use:

  • $CI_ENVIRONMENT_NAME. The name defined in the .gitlab-ci.yml file.
  • $CI_ENVIRONMENT_SLUG. A “cleaned-up” version of the name, suitable for use in URL and DNS, for example. This variable is guaranteed to be unique.
  • $CI_ENVIRONMENT_URL. The environment’s URL, which was specified in the .gitlab-ci.yml file or automatically assigned.

If you change the name of an existing environment, the:

  • $CI_ENVIRONMENT_NAME variable is updated with the new environment name.
  • $CI_ENVIRONMENT_SLUG variable remains unchanged to prevent unintended side effects.

Set dynamic environment URLs after a job finishes

Introduced in GitLab 12.9.

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 dotenv (.env) file format, and expands 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 Set dynamic URLs after a job finished.

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: