Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Environments and Deployments

Environments and Deployments

Learn how the environment keyword turns a CI job into a tracked deployment, with URLs, manual gates, resource_group locking, stop actions and deployment history.

A pipeline that only builds and tests ends with a green check mark. A pipeline that deploys has to answer more questions: where is this version running, who put it there, what was running before, and can I put it back? GitLab answers these with environments. An environment is a named place, such as staging or production, and every job that mentions it becomes a recorded deployment.

This lesson explains the environment keyword, how GitLab records deployments, how to keep two deployments from colliding, and how to stop an environment. GitLab itself cannot run on this site, so the YAML below is read-only. The runnable examples are small JavaScript stand-ins that copy the rules (they are not GitLab code), so you can try the logic yourself.

What the environment keyword does

Add environment to a job and GitLab creates the environment if it does not exist, then records a deployment each time the job runs.

YAML
deploy_staging:
  stage: deploy
  script:
    - ./scripts/deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

After this job succeeds, the project menu Operate > Environments lists staging with a link to the URL, the commit that was deployed, the user or pipeline that triggered it and the time. The menu names change between GitLab versions (older versions say Deployments > Environments), so look for "Environments" under the Operate or Deploy menu.

Two things are worth noticing. First, the job does not deploy anything by itself: your script does the work (rsync, kubectl, a cloud CLI). The keyword only tells GitLab what you did. Second, the environment name is just text. Teams usually pick a few stable names (development, staging, production) and rely on deployment tiers (production, staging, testing, development, other) to group them. You can set a tier explicitly with deployment_tier: production when the name is not obvious.

Manual gates and the production job

Deploying to production is normally a decision, not an automatic step. Use when: manual so the pipeline pauses until someone presses the play button:

YAML
deploy_production:
  stage: deploy
  script:
    - ./scripts/deploy.sh production
  environment:
    name: production
    url: https://www.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  needs:
    - job: deploy_staging

A manual job that is not allowed to fail blocks the pipeline status with the "blocked" state until someone runs it. If you want the pipeline to be reported as passed while the manual job waits, add allow_failure: true in the rule. Rules for choosing are covered in the GitLab CI/CD chapters; here the point is that the gate sits right before the environment that matters.

flowchart LR
  B["build"] --> T["test"]
  T --> S["deploy_staging (automatic)"]
  S --> G{"manual approval"}
  G --> P["deploy_production"]
  P --> H["deployment recorded in production"]

Every box that mentions an environment adds a row to that environment's deployment history.

Deployments, jobs and history

A deployment links four things: an environment, a commit, a pipeline job and a status (running, success, failed, canceled). The environment page shows the newest deployment first. This history is what makes rollbacks possible (see Deployment Strategies and Rollbacks) and what lets you answer "which commit is in production" without logging in to a server.

Useful predefined variables inside an environment job:

Variable Meaning
CI_ENVIRONMENT_NAME The name of the environment, for example staging
CI_ENVIRONMENT_SLUG A shortened, URL-safe version of the name (lowercase letters, numbers, hyphens)
CI_ENVIRONMENT_URL The url you declared
CI_ENVIRONMENT_TIER The deployment tier

You can pass CI_ENVIRONMENT_NAME to your deploy script instead of hard-coding the target, so one script serves every environment.

Environment-specific variables

CI/CD variables can be limited to an environment scope. A variable called API_URL with scope staging is only available to jobs that deploy to staging; the same name with scope production holds a different value. A wildcard scope such as review/* matches all review environments (more on those in Review Apps and Dynamic Environments). This is the clean way to keep production credentials out of staging jobs. Remember that the scope only applies when the job has an environment; a plain test job never sees the production-scoped value.

Avoiding collisions with resource_group

Two pipelines may try to deploy to the same environment at the same moment, for example when two merges land close together. Without protection, the second deploy can overwrite the first halfway through. Declare a resource group and GitLab runs only one job from the group at a time:

YAML
deploy_production:
  resource_group: production
  environment:
    name: production
  script:
    - ./scripts/deploy.sh production

Jobs that share the same resource_group string queue up. By default they run in the order they were created in newer GitLab versions (the process_mode of the group is configurable through the API: unordered, oldest_first or newest_first). Use the group name of the environment, so the lock matches what you are protecting.

Stopping environments

Environments that only exist for a while (a review environment for a merge request) need a way to disappear. GitLab uses a second job with action: stop and links it from the deploy job with on_stop:

YAML
deploy_review:
  stage: deploy
  script: ./scripts/deploy-review.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    on_stop: stop_review

stop_review:
  stage: deploy
  script: ./scripts/destroy-review.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual

When a merge request is merged or its branch is deleted, GitLab can run the stop job automatically. For a time-based cleanup, add auto_stop_in: 1 week to the deploy job. Stopping an environment runs your cleanup job; it does not delete the history.

Stand-in: deployment history and locking

The first example models a deployment list. deploy() records a new deployment, marks the previous one as superseded and prints the history. It is only a model of the information GitLab keeps.

JS A deployment history

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example models resource_group: three jobs want the same group, and only one may run at a time. The code shows why a queue stops two deploys from overlapping.

JS resource_group queue

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does adding the environment keyword to a job do?

    The keyword only tells GitLab where the job deploys. Your script still does the actual deployment; GitLab records the commit, user and status.
  2. 2. Which setting makes a production deploy wait for a person to press play?

    A manual job pauses the pipeline until someone starts it. resource_group only serializes jobs, and on_stop links a stop job.
  3. 3. Two pipelines deploy to production at the same time. How do you keep them from overlapping?

    Jobs that share a resource_group run one at a time, so the second deploy waits for the first to finish.
  4. 4. A variable is scoped to production. Which job can read it?

    Environment scope is matched against the job's environment name, so a job without that environment never sees the value.

Summary

  • The environment keyword turns a job into a tracked deployment with a URL, commit, user and status.
  • Use when: manual before environments that need a decision, and resource_group to serialize deploys.
  • Variables can be scoped to an environment name or a wildcard, keeping secrets away from the wrong jobs.
  • Short-lived environments are removed with on_stop and action: stop, or auto_stop_in.
  • The deployment history is the base for rollbacks and audits.

Next: Review Apps and Dynamic Environments