Environments, Deployments, Review Apps, Protected Environments, and Deployment Approvals: Concepts, Architecture, and Mental Model

1. The practical problem: “the pipeline is green” does not tell you what is deployed

Chapter 16 gave pipeline outputs an identity: producer job, pipeline, commit SHA, checksum, and retention. Deployment introduces another state transition. A job can succeed while publishing nothing, publish to the wrong endpoint, or update an external system while GitLab records a misleading environment name. Conversely, GitLab can show a healthy environment record even when the external target is down because the environment record is not the infrastructure itself.

The operational question is therefore not just “did deploy succeed?” It is: which immutable source/artifact identity did which job attempt to deploy, to which target, under which environment name, and what evidence proves the external state matches the GitLab record?

2. Mental model: control-plane record around an external target

flowchart TD
  C[Commit SHA] -- pipeline config --> P[Pipeline]
  A[Build artifact + digest] -- needs edge --> J[Deployment job]
  P -- schedules --> J
  J -- deployment record --> D[(GitLab deployment)]
  D -- belongs to --> E[(GitLab environment)]
  J -- external action --> T[External target or simulation]
  E -- URL / metadata --> T
  V[Scoped variable / credential policy] -- job-time access --> J
  G[Protection / approval policy] -. optional paid gate .-> J

3. Define the resources before using the UI

4. A deployment record is hosted metadata around a job

A job becomes a deployment job when it declares an environment. A successful job normally creates a successful deployment record; failed/canceled deployment attempts are also visible in history. The deployment points back to the job and commit, which lets operators correlate pipeline evidence with environment history.

deploy_development:
  stage: deploy
  script:
    - test -f out/product.txt
    - sha256sum -c out/product.txt.sha256
    - echo "Simulated deployment only; no external system changed"
  environment:
    name: development
    url: https://development.example.invalid
    deployment_tier: development

The URL is metadata and a navigation aid. GitLab does not verify that development.example.invalid exists, nor that the job actually wrote to that target. In this course we deliberately use the reserved .invalid domain to prove the separation between GitLab’s record and external infrastructure.

5. Read-only inspection first

Before creating or changing an environment, inspect the project’s existing environment and deployment inventory. A UI path is Operate → Environments. The REST APIs provide machine-readable evidence without requiring a mutation:

PROJECT_ID="12345678"

glab api "projects/$PROJECT_ID/environments" --paginate \
  --jq '.[] | {id,name,state,external_url,tier,updated_at}'

glab api "projects/$PROJECT_ID/deployments?order_by=finished_at&sort=desc" --paginate \
  --jq '.[] | {id,status,ref,sha,environment:.environment.name,deployable_job_id:.deployable.id,finished_at}'

Use synthetic numeric IDs in course notes. Do not paste private API tokens into commands; glab should use its authenticated profile. If the API output contains private URLs or project information, capture only the fields needed for the lab.

6. Static and dynamic environments

A static environment has a stable name such as staging. Many deployments over time update the same logical target. A dynamic environment embeds change identity in the environment name, such as review/feature-login. GitLab groups dynamic environments by prefix, which makes Review Apps easier to manage.

review_app:
  stage: deploy
  script:
    - echo "Create a synthetic review deployment record"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.invalid
    deployment_tier: development

Dynamic naming is a metadata contract. If the external deploy script always writes to one shared test server, five GitLab review-environment names still do not create five isolated targets. The script/infrastructure must implement the isolation the names claim.

7. Review Apps connect change lifecycle to environment lifecycle

A Review App is usually created from an MR/branch pipeline so reviewers can inspect a running version of the proposed change. GitLab supplies the environment record and can surface the URL in merge-request workflows; your deployment code still creates the actual service. Review Apps are available on Free, but a real Review App may consume cloud, cluster, DNS, or runner resources. The mandatory labs use a synthetic URL and no external system.

A useful Review App policy answers: which pipeline source creates it, which branch/MR identity names it, whether untrusted fork code can deploy, which variables it receives, how it is stopped, and what cleanup evidence proves its external resources are gone.

8. Stop actions: state transition plus external cleanup

Stopping an environment should mean two things: GitLab marks the environment stopped, and your stop job tears down the external resource. Declare the stop job with environment:action: stop and connect it through on_stop.

deploy_review:
  stage: deploy
  script: echo "synthetic deploy"
  resource_group: review-$CI_COMMIT_REF_SLUG
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.invalid
    on_stop: stop_review
    auto_stop_in: 1 day

stop_review:
  stage: deploy
  script: echo "synthetic teardown"
  resource_group: review-$CI_COMMIT_REF_SLUG
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual

Using the same resource_group for deploy and stop also supports the current UI Stop behavior documented by GitLab. In production, the stop script must be idempotent: “already gone” should be a safe, observable result rather than a destructive error cascade.

9. auto_stop_in is lifecycle policy, not a precise scheduler

environment:auto_stop_in schedules an environment to be stopped after a human-readable duration. GitLab’s background worker checks expirations periodically, so the stop is not guaranteed at the exact second the interval elapses. Every new deployment resets the environment’s lifetime. Current GitLab also supports resetting or preserving the schedule with environment actions such as access, prepare, and verify.

Do not use auto_stop_in as the only control for expensive infrastructure. Combine it with idempotent external cleanup and inventory/TTL controls in the actual platform.

10. Environment-scoped variables narrow credential exposure

A project CI/CD variable can be scoped to an environment name or wildcard such as review/* or production. This is valuable because a job only receives the variable when its environment matches the scope. It reduces exposure but does not make untrusted deployment code safe: code that receives the variable can still use it.

11. Rollback means a new deployment pointing to an older known state

GitLab can retry/redeploy a deployment or roll back to a previously successful deployment. A rollback creates a new deployment record and a new job ID pointing to the commit being restored. Only the deployment job is rerun; upstream build jobs are not magically rerun. This is why the safest rollback architecture deploys an immutable, retained artifact by digest/identity instead of rebuilding mutable dependencies.

If your deploy job rebuilds from source, “rollback to commit X” may produce bytes different from the original deployment of X. Preserve artifact identity separately when production reproducibility matters.

12. Protected environments and deployment approvals are separate paid governance layers

Protected environments are Premium/Ultimate and restrict who may deploy to an environment. Deployment approvals are also Premium/Ultimate and add required approvers to protected-environment deployments. They do not replace branch protection, runner isolation, secret scope, or external cloud IAM.

Current behavior also matters operationally: a deployment approval does not automatically start the corresponding deployment job. After all required approvals are satisfied, the job still must be run according to GitLab’s deployment-approval workflow. By default, the pipeline triggerer cannot self-approve unless that option is explicitly enabled.

13. Trust boundary: environment metadata does not constrain a runner

A job named deploy_production can run on an over-privileged runner and reach unrelated systems. Conversely, a protected environment can prevent GitLab from authorizing a deployment job but cannot revoke a credential that someone copied elsewhere. Treat these as composing controls: reviewed config + protected refs + scoped variables/short-lived identity + isolated runners + target IAM + environment protection/approval + deployment evidence.

14. DevOps connection: deployment state must be falsifiable

A useful environment record lets another engineer independently falsify or confirm the claim “commit/artifact A is deployed to target B.” Record commit SHA, artifact digest, deployment job and pipeline IDs, environment name, external target identifier, actor/policy evidence, and a post-deploy verification signal. Without that chain, environment dashboards become labels rather than operational evidence.

Knowledge check

Summary

GitLab environments are auditable records around deployment targets; deployments connect jobs and commits to those records. Review Apps add change-scoped dynamic environments, stop actions and auto_stop_in manage lifecycle, scoped variables narrow runtime exposure, and rollback should preserve known artifact identity. Protected environments and deployment approvals add paid governance, but they compose with—not replace—runner, ref, secret, and external-IAM controls.

Official references

• GitLab Docs — Environments
• GitLab Docs — Deployments
• GitLab Docs — Review apps
• GitLab Docs — Deployment safety
• GitLab Docs — Protected environments
• GitLab Docs — Deployment approvals
• GitLab Docs — Environments API
• GitLab Docs — Deployments API
• GitLab Docs — Protected environments API
• GitLab Docs — CI/CD variables
• GitLab Docs — CI/CD YAML syntax reference
• GitLab Docs — Predefined CI/CD variables
• GitLab Docs — Where variables can be used
• GitLab Docs — Resource groups