- View environments and deployments
- Types of environments
- Deployment tier of environments
- Configure manual deployments
- Configure Kubernetes deployments (DEPRECATED)
- CI/CD variables for environments and deployments
- Set dynamic environment URLs after a job finishes
- Track newly included merge requests per deployment
-
Working with environments
- Environment rollback
- Environment URL
-
Stop an environment
- Stop an environment when a branch is deleted
- Stop an environment when another job is finished
- Stop an environment after a certain time period
- Multiple stop actions for an environment
- View a deployment’s scheduled stop time
- Override a deployment’s scheduled stop time
- Delete a stopped environment
- Delete an active environment without running a stop job
- Access an environment for preparation or verification purposes
- Group similar environments
- Environment incident management
- Monitor environments
- Web terminals (DEPRECATED)
- Check out deployments locally
- Archive Old Deployments
- Scope environments with specs
- Rename an environment
- Related topics
- Troubleshooting
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:
- On the top bar, select Menu > Projects and find your project.
-
On the left sidebar, select Deployments > Environments. The environments are displayed.
-
To view a list of deployments for an environment, select the environment name, for example,
staging
.
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
orproduction
. - 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:
- On the top bar, select Menu > Projects and find your project.
- On the left sidebar, select Deployments > Environments.
- Select New environment.
- Enter a name and external URL.
- Select Save.
In your .gitlab-ci.yml
file:
-
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
-
Trigger a deployment. (For example, by creating and pushing a commit.)
When the job runs, the environment and deployment are created.
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
isreview/$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.
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)
- Introduced in GitLab 12.6.
- 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.
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:
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: