|
|
Environments
- Tier : Free, Premium, Ultimate
- Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated
A GitLab environment represents a specific deployment target for your application, like development, staging, or production. Use it to manage different configurations and deploy code during various stages of your software lifecycle.
With environments, you:
- Keep your deployment process consistent and repeatable
- Track what code is deployed where
- Roll back to previous versions when problems occur
- Protect sensitive environments from unauthorized changes
- Control deployment variables per environment to maintain security boundaries
- Monitor environment health and get alerts if something goes wrong
View environments and deployments
Prerequisites:
- In a private project, you must have at least the Reporter role. See Environment permissions .
There are a few ways to view a list of environments for a given project:
-
On the project’s overview page, if at least one environment is available (that is, not stopped).
-
On the left sidebar, select Operate > 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.
-
To view a list of all manual jobs in a deployment pipeline, select the Run ( ) dropdown list.
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,
stagingorproduction).
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.
Types of environments
An environment is either static or dynamic.
Static environments:
- Are usually reused by successive deployments.
-
Have static names. For example,
stagingorproduction. - Are created manually or as part of a CI/CD pipeline.
Dynamic environments:
- Are usually created in a CI/CD pipeline and are used by only a single deployment, then either stopped or deleted.
- Have dynamic names, usually based on the value of a CI/CD variable.
- Are a feature of review apps .
An environment has one of three states, depending on whether its stop job has run:
-
available: The environment exists. There might be a deployment. -
stopping: The on stop job has started. This state does not apply when there is no on stop job defined. -
stopped: Either the on stop job has run, or a user manually stopped the job.
Create a static environment
You can create a static environment in the UI or in your
.gitlab-ci.yml
file.
In the UI
Prerequisites:
- You must have at least the Developer role.
To create a static environment in the UI:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments .
- Select Create an environment .
- Complete the fields.
- Select Save .
In your
.gitlab-ci.yml
file
Prerequisites:
- You must have at least the Developer role.
To create a static environment, in your
.gitlab-ci.yml
file:
-
Define a job in the
deploystage. -
In the job, define the environment
nameandurl. If an environment of that name doesn’t exist when the pipeline runs, it is created.
For example, to create an environment named
staging
, with URL
https://staging.example.com
:
Create a dynamic environment
To create a dynamic environment, you use CI/CD variables that are unique to each pipeline.
Prerequisites:
- You must have at least the Developer role.
To create a dynamic environment, in your
.gitlab-ci.yml
file:
-
Define a job in the
deploystage. -
In the job, define the following environment attributes:
-
name: Use a related CI/CD variable like$CI_COMMIT_REF_SLUG. Optionally, add a static prefix to the environment’s name, which groups in the UI all environments with the same prefix. -
url: Optional. Prefix the hostname with a related CI/CD variable like$CI_ENVIRONMENT_SLUG.
-
In the following example, every time the
deploy_review_app
job runs the environment’s name and
URL are defined using unique values.
Set a dynamic environment URL
Some external hosting platforms generate a random URL for each deployment, for example:
https://94dd65b.amazonaws.com/qa-lambda-1234567
. That makes it difficult to reference the URL in
the
.gitlab-ci.yml
file.
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
.
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.
For an overview, see Set dynamic URLs after a job finished .
In the following example a review app creates a new environment for each merge request:
-
The
reviewjob is triggered by every push, and creates or updates an environment namedreview/your-branch-name. The environment URL is set to$DYNAMIC_ENVIRONMENT_URL. -
When the
reviewjob finishes, GitLab updates thereview/your-branch-nameenvironment’s URL. It parses thedeploy.envreport artifact, registers a list of variables as runtime-created, expands theenvironment:url: $DYNAMIC_ENVIRONMENT_URLand sets it to the environment URL.
Note the following:
-
stop_reviewdoesn’t generate a dotenv report artifact, so it doesn’t recognize theDYNAMIC_ENVIRONMENT_URLenvironment variable. Therefore you shouldn’t setenvironment:urlin thestop_reviewjob. - 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_reviewexists only in your repository and therefore can’t useGIT_STRATEGY: noneorGIT_STRATEGY: empty, 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 .
Deployment tier of environments
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. This can affect how metrics
like
deployment frequency
are calculated.
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
.
You cannot set an environment tier using the UI.
Instead, you can use the
deployment_tier
keyword
to specify a tier.
Rename an environment
You cannot rename an environment.
To achieve the same result as renaming an environment:
- Stop the existing environment .
- Delete the existing environment .
- Create a new environment with the desired name.
CI/CD variables
To customize your environments and deployments, you can use any of the predefined CI/CD variables , and define custom CI/CD variables.
Limit the environment scope of a CI/CD variable
By default, all CI/CD variables are available to all jobs in a pipeline. If a test tool in a job becomes compromised, the tool could attempt to retrieve all CI/CD variables available to the job. To help mitigate this kind of supply chain attack, you should limit the environment scope of sensitive variables to only the jobs that require them.
Limit the environment scope of a CI/CD variable by defining which environments it
can be available for. The default environment scope is the
*
wildcard, so any job
can access the variable.
You can use specific matching to select a particular environment. For example, set
the variable’s environment scope to
production
to only allow jobs with an
environment
of
production
to access the variable.
You can also use wildcard matching (
*
) to select a particular environment group,
like all
review apps
with
review/*
.
For example, with these four environments:
-
production -
staging -
review/feature-1 -
review/feature-2
These environment scopes match as follows:
| ↓ Scope / Environment → |
production
|
staging
|
review/feature-1
|
review/feature-2
|
|---|---|---|---|---|
*
|
Match | Match | Match | Match |
production
|
Match | |||
staging
|
Match | |||
review/*
|
Match | Match | ||
review/feature-1
|
Match |
You should not use environment-scoped variables with
rules
or
include
. The variables might not be defined when
GitLab validates the pipeline configuration at pipeline creation.
Search environments
To search environments by name:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments .
-
In the search bar, enter your search term.
- The length of your search term should be 3 or more characters .
-
Matching applies from the beginning of the environment name.
-
For example,
develmatches the environment namedevelopment, butelopdoes not.
-
For example,
-
For environments with a folder name format, matching applies after the base folder name.
-
For example when the name is
review/test-app, search termtestmatchesreview/test-app. -
Also searching with the folder name prefixed like
review/testmatchesreview/test-app.
-
For example when the name is
Group similar environments
You can group environments into collapsible sections in the UI.
For example, if all of your environments start with the name
review
,
then in the UI, the environments are grouped under that heading:
The following example shows how to start your environment names with
review
.
The
$CI_COMMIT_REF_SLUG
variable is populated with the branch name at runtime:
Stopping an environment
Stopping an environment means its deployments are not accessible on the target server. You must stop an environment before it can be deleted.
When using the
on_stop
action to stop an environment, the job runs if it’s not
archived
.
Stop an environment by using the UI
To stop an environment in the GitLab UI:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments .
- Next to the environment you want to stop, select Stop .
- On the confirmation dialog, select Stop environment .
Default stopping behavior
GitLab automatically stops environments when the associated branch is deleted or merged.
This behavior persists even if no explicit
on_stop
CI/CD job is defined.
However,
issue 428625
proposes to change this behavior
so that production and staging environments stop only if an explicit
on_stop
CI/CD job is defined.
You can configure an environment’s stopping behavior with the
auto_stop_setting
parameter in the Environments API.
Stop an environment when a branch is deleted
You can configure environments to stop when a branch is deleted.
In the following example, a
deploy_review
job calls a
stop_review
job to clean up and stop the
environment.
-
Both jobs must have the same
rulesoronly/exceptconfiguration. Otherwise, thestop_reviewjob might not be included in all pipelines that include thedeploy_reviewjob, and you cannot triggeraction: stopto stop the environment automatically. -
The job with
action: stopmight 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
GIT_STRATEGYtononeoremptyin thestop_reviewjob. Then, the runner doesn’t try to check out the code after the branch is deleted.
Stop an environment when a merge request is merged or closed
When you use the
merge request pipelines
configuration,
the
stop
trigger is automatically enabled.
In the following example, the
deploy_review
job calls a
stop_review
job to clean up and stop
the environment.
-
When the
Pipelines must succeed
setting is turned on,
you can configure the
allow_failure: truekeyword on thestop_reviewjob to prevent it from blocking your pipelines and merge requests.
Stop an environment after a certain time period
You can set an environment to stop automatically after a certain time period.
In your
.gitlab-ci.yml
file, specify the
environment:auto_stop_in
keyword. Specify the time period in natural language, such as
1 hour and 30 minutes
or
1 day
.
After the time period passes, GitLab automatically triggers a job to stop the environment.
In the following example:
-
Each commit on a merge request triggers a
review_appjob that deploys the latest change to the environment and resets its expiry period. -
If the environment is inactive for more than a week, GitLab automatically triggers the
stop_review_appjob to stop the environment.
The
environment:action
keyword can be used to reset the time
that an environment is scheduled to stop. For more information, see
Access an environment for preparation or verification purposes
.
View an environment’s scheduled stop date and time
When a environment has been scheduled to stop after a specified time period , you can view its expiration date and time.
To view an environment’s expiration date and time:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments .
- Select the name of the environment.
The expiration date and time is displayed in the upper-left corner, next to the environment’s name.
Override an environment’s scheduled stop date and time
When a environment has been scheduled to stop after a specified time period , you can override its expiration.
To override an environment’s expiration in the UI:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments .
- Select the environment name.
- in the upper-right corner, select the thumbtack ( ).
To override an environment’s expiration in the
.gitlab-ci.yml
:
-
Open the project’s
.gitlab-ci.yml. -
Update the
auto_stop_insetting of the corresponding deploy job toauto_stop_in: never.
The
auto_stop_in
setting is overridden and the environment remains active until it’s stopped
manually.
Clean up stale environments
Clean up stale environments when you want to stop old environments in a project.
Prerequisites:
- You must have at least the Maintainer role.
To clean up stale environments:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments .
- Select Clean up environments .
- Select the date to use for determining which environments to consider stale.
- Select Clean up .
Active environments that haven’t been updated after the specified date are stopped. Protected environments are ignored and not stopped.
Run a pipeline job when environment is stopped
You can define a stop job for the environment with an
on_stop
action
in the environment’s deploy job.
The stop jobs of finished deployments in the latest finished pipeline are run when an environment is stopped. A deployment or pipeline is finished if it has the successful, canceled, or failed status.
Prerequisites:
- Both the deploy and stop jobs must have the same rules or only/except configuration.
-
The stop job must have the following keywords defined:
-
when, defined at either:- The job level .
-
In a rules clause
. If you use
rulesandwhen: manual, you should also setallow_failure: trueso the pipeline can complete even if the job doesn’t run.
-
environment:name -
environment:action
-
In the following example:
-
A
review_appjob calls astop_review_appjob after the first job is finished. -
The
stop_review_appis triggered based on what is defined underwhen. In this case, it is set tomanual, so it needs a manual action from the GitLab UI to run. -
The
GIT_STRATEGYis set tonone. If thestop_review_appjob is automatically triggered , the runner doesn’t try to check out the code after the branch is deleted.
Multiple stop actions for an environment
To configure multiple
parallel
stop actions on an environment, specify the
on_stop
keyword across multiple
deployment jobs
for the same
environment
, as defined in the
.gitlab-ci.yml
file.
When an environment is stopped, the matching
on_stop
actions from only successful deployment jobs are run in parallel, in no particular order.
In the following example, for the
test
environment there are two deployment jobs:
-
deploy-to-cloud-a -
deploy-to-cloud-b
When the environment is stopped, the system runs
on_stop
actions
teardown-cloud-a
and
teardown-cloud-b
in parallel.
Stop an environment without running the
on_stop
action
There may be times when you want to stop an environment without running the defined
on_stop
action. For example, you want to delete many
environments without using
compute quota
.
To stop an environment without running the defined
on_stop
action, execute the
Stop an environment API
with the parameter
force=true
.
Delete an environment
Delete an environment when you want to remove it and all its deployments.
Prerequisites:
- You must have at least the Developer role.
- You must stop the environment before it can be deleted.
To delete an environment:
- On the left sidebar, select Search or go to and find your project.
- Select Operate > Environments .
- Select the Stopped tab.
- Next to the environment you want to delete, select Delete environment .
- On the confirmation dialog, select Delete environment .
Access an environment for preparation or verification purposes
You can define a job that accesses an environment for various purposes, such as verification or preparation. This effectively bypasses deployment creation, so that you can adjust your CD workflow more accurately.
To do so, add either
action: prepare
,
action: verify
, or
action: access
to the
environment
section of your job:
This gives you access to environment-scoped variables, and can be used to protect builds from unauthorized access. Also, it’s effective to avoid the prevent outdated deployment jobs feature.
If an environment is configured to stop after a certain time period, jobs with the
access
or
prepare
action will reset the scheduled stop time. The
environment:auto_stop_in
from the most recent successful deployment job to the environment is used when resetting the scheduled time.
For example, if the most recent deployment used
auto_stop_in: 1 week
and is later accessed by a job with
action: access
, the environment will be rescheduled to stop one week from the completion of the accessing job.
To access an environment without changing the scheduled stop time, use the
verify
action.
Environment incident management
Production environments can go down unexpectedly, including for reasons outside of your control. For example, issues with external dependencies, infrastructure, or human error can cause major issues with an environment. Things like:
- A dependent cloud service goes down.
- A 3rd party library is updated and it’s not compatible with your application.
- Someone performs a DDoS attack to a vulnerable endpoint in your server.
- An operator misconfigures infrastructure.
- A bug is introduced into the production application code.
You can use incident management to get alerts when there are critical issues that need immediate attention.
View the latest alerts for environments
- Tier : Ultimate
- Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated
If you set up an alert integration , alerts for environments are shown on the environments page. The alert with the highest severity is shown, so you can identify which environments need immediate attention.
When the issue that triggered the alert is resolved, it is removed and is no longer visible on the environments page.
If the alert requires a rollback , you can select the deployment tab from the environment page and select which deployment to roll back to.
Auto Rollback
- Tier : Ultimate
- Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated
In a typical Continuous Deployment workflow, the CI pipeline tests every commit before deploying to production. However, problematic code can still make it to production. For example, inefficient code that is logically correct can pass tests even though it causes severe performance degradation. Operators and SREs monitor the system to catch these problems as soon as possible. If they find a problematic deployment, they can roll back to a previous stable version.
GitLab Auto Rollback eases this workflow by automatically triggering a rollback when a
critical alert
is detected.
For GitLab to select the appropriate environment for the rollback, the alert should contain a
gitlab_environment_name
key with the name of the environment.
GitLab selects and redeploys the most recent successful deployment.
Limitations of GitLab Auto Rollback:
- The rollback is skipped if a deployment is running when the alert is detected.
- A rollback can happen only once in three minutes. If multiple alerts are detected at once, only one rollback is performed.
GitLab Auto Rollback is turned off by default. To turn it on:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > CI/CD .
- Expand Automatic deployment rollbacks .
- Select the checkbox for Enable automatic rollbacks .
- Select Save changes .
Environment permissions
Depending on your role, you can interact with environments in public and private projects.
View environments
- In public projects, anyone can view a list of environments, including non-members.
- In private projects, you must have at least the Reporter role to view a list of environments.
Create and update environments
- You must have at least the Developer role to create a new environment, or update an existing unprotected environment.
- If an existing environment is protected and you don’t have access to it, you cannot update the environment.
Stop and delete environments
- You must have at least the Developer role to stop or delete an unprotected environment.
- If an environment is protected and you don’t have access to it, you cannot stop or delete the environment.
Run deployment jobs in protected environments
If you can push or merge to the protected branch:
- You must have at least the Reporter role.
If you can’t push to the protected branch:
- You must be a part of a group with the Reporter role.
See Deployment-only access to protected environments .
Web terminals (deprecated)
If you deploy to your environments with the help of a deployment service (for example, the Kubernetes integration ), GitLab can open a terminal session to your environment. You can then debug issues without leaving your web browser.
The Web terminal is a container-based deployment, which often lacks basic tools (like an editor), and can be stopped or restarted at any time. If this happens, you lose all your changes. Treat the Web terminal as a debugging tool, not a comprehensive online IDE.
Web terminals:
- Are available to project Maintainers and Owners only.
- Must be enabled .
In the UI, to view the Web terminal, either:
-
From the Actions menu, select Terminal :
-
On the page for a specific environment, on the right, select Terminal ( ).
Select the button to establish the terminal session. It works like any other terminal. You’re in the container created by your deployment so you can:
- Run shell commands and get responses in real time.
- Check the logs.
- Try out configuration or code tweaks.
You can open multiple terminals to the same environment. They each get their own shell
session and even a multiplexer like
screen
or
tmux
.
Related topics
- Dashboard for Kubernetes
- Deployments
- Protected environments
- Environments Dashboard
- Deployment safety
Troubleshooting
The job with
action: stop
doesn’t run
In some cases, environments do not stop despite an
on_stop
job being configured. This happens when the job
with the
action: stop
is not in a runnable state due to its
stages:
or
needs:
configuration.
For example:
-
The environment might start in a stage that also has a job that failed.
Then the jobs in later stages job don’t start. If the job with the
action: stopfor the environment is also in a later stage, it can’t start and the environment isn’t deleted. -
The job with the
action: stopmight have a dependency on a job that has not yet completed.
To ensure the
action: stop
can always run when needed, you can:
-
Put both jobs in the same stage:
-
Add a
needsentry to theaction: stopjob so the job can start out of stage order:
Error: job would create an environment with an invalid parameter
If your project is configured to create a dynamic environment , you might encounter this error in a deployment job because the dynamically generated parameter can’t be used for creating an environment:
For example, your project has the following
.gitlab-ci.yml
:
Because the
$ENVIRONMENT
variable does not exist in the pipeline, GitLab tries to
create an environment with a name
production/
, which is invalid in
the environment name constraint
.
To fix this, use one of the following solutions:
-
Remove
environmentkeyword from the deployment job. GitLab has already been ignoring the invalid keyword, therefore your deployment pipelines stay intact even after the keyword removal. - Ensure the variable exists in the pipeline. Review the limitation on supported variables .
If you get this error on review apps
For example, if you have the following in your
.gitlab-ci.yml
:
When you create a new merge request with a branch name
bug-fix!
,
the
review
job tries to create an environment with
review/bug-fix!
.
However, the
!
is an invalid character for environments, so the