Why do I need to declare environments in GitLab ?

  • To track deployed versions on each environment
  • To control deployment on environments (e.g. add an approval to deploy production)
  • Add environment-related variables

An environment can be linked to a pipeline step. For example, to define the target of a deployment.

Create an environment

1. In the side menu, go to : Operate > Environments

2. Click on “New environment”, set the parameters

  • Name: with the name of your environment
  • External URL: the URL of your environment (use in environments list for the Open button)
  • GitLab agent: An option to define the agent to be used for environment deployment. Can remain blank

3. Environment List

You can define several environments for a single project. They will then be available in the environment list in: Operate > Environments

View Deployments

When an environment has been specified in a deployment step, it is then possible to find out which version is deployed in the environment.

Click on the arrow at the beginning of the line to expand the details panel :

Define CI/CD variables for an environment

It is possible to define environment-specific variables to use in pipelines.

In your project, in the side menu, go to Settings > CI/CD, after that, expand the Variables section :

To add a variable, click on “Add variable” button and set the parameters :

  • Key: the name of your variable
  • Value: the value of the variable
  • Environment scope: defines the environment in which the variable will be available

Note : The same variable (with the same name) can de define for each environment.

In the .gitlab-ci.yml, environment scoped variables can be used similarly like a standard variable. ( For example: ${K8S_NS} )

Protected environments

Protected environments can be used to prevent unintentional deployment or to authorize only certain users to deploy.

In the side menu, go to Settings > CI/CD and expand the Protected environments section :

Protect an environment :

Click on “Protect an environment”, select the environment to protect and set the parameters to define who can deploy and who can approve :

Deploy on protected Environment

When a pipeline reaches the step to deploy on a protected environment, the pipeline will wait for deployment approval

At the same time, the environment deployment wait for approval in the environments list :

Click on “Approval options” button and approve or reject the deployment :

After approval, the pipeline does not restart automatically. Click on “Run” button to continue the deployment:


Environments are very useful in GitLab. However, it’s possible to write pipelines without it. But if you don’t use environments for deployment, you’ll miss out on some really useful features, such as approvals, variables and, by the way, it becomes harder to track deployments.