Environments, Deployments, Review Apps, Protected Environments, and Deployment Approvals: Configuration, Design Choices, and Tradeoffs

1. Start with the external system, then model it in GitLab

The safest deployment architecture does not start by inventing environment names in YAML. First identify the real deployment targets and their invariants: whether they are shared or per-change, how they are addressed, who owns them, what credential writes to them, what constitutes successful health, and how they are removed or restored. Then make GitLab environment/deployment records reflect those facts.

A mismatch between external topology and GitLab naming is operational debt. For example, calling ten review environments review/* while all jobs overwrite one shared server creates false concurrency and false isolation.

2. Static environment versus Review App

Review Apps improve feedback only if external isolation is real. If per-MR infrastructure is expensive or unsafe, use a static test target with controlled scheduling rather than pretending to have dynamic isolation.

3. Automated deployment versus manual execution versus deployment approval

These answer different questions:

A mature production gate may combine MR governance, protected branch, pipeline checks, protected environment, deployment approvals, short-lived target identity, and an explicit operator run. Avoid adding a manual button solely to make a pipeline “feel controlled.”

4. Merge approval and deployment approval are intentionally separate

A merge approval answers “is this code change acceptable to integrate?” A deployment approval answers “is this particular deployment to this protected environment acceptable now?” The same code may be approved for merge but intentionally not deployed during an incident, freeze, or readiness problem. Conversely, redeploying a previously reviewed artifact may need deployment authorization without another source-code review.

5. Environment-scoped variable versus broad project variable

If a variable is needed only by production, scope it to production rather than *. If a synthetic review variable is needed by every Review App, scope it to review/*. This reduces accidental exposure to unrelated jobs.

Scope is not a substitute for trust. If a production deployment job executes attacker-controlled code, that code can still access variables granted to the job.

6. Roll back by known artifact versus rebuild from source

There are two very different actions often called rollback:

• Redeploy known artifact: select the exact binary/image/package digest that was previously successful and deploy it again. This preserves identity.
• Rebuild old source: check out the old commit and run today’s build with today’s registries, base images, timestamps, dependency mirrors, and toolchain. This may produce different bytes.

GitLab’s deployment rollback reruns the deployment job for a previous deployment/commit; it does not automatically rerun upstream build jobs. Design the deploy job so it can retrieve/verify the previously identified artifact if deterministic rollback matters.

7. Deployment input contract

A production deploy job should have an explicit contract such as:

deployment input:
  commit_sha: 7f3...c21
  artifact_type: container-image
  immutable_identity: registry.example/app@sha256:abc...
  build_pipeline_id: 9012
  deploy_pipeline_id: 9055
  environment: production
  target_id: cluster/prod-eu1
  verification: health-check + version endpoint

This is more useful than “deployed main.” It lets incident responders reproduce the exact intended state.

8. Explicit stop policy versus implicit cleanup

Current GitLab can automatically stop environments when their associated branch is merged/deleted, even without an explicit on_stop job, but the documentation notes a proposed change for production/staging behavior. Treat implicit stop as convenience, not your external cleanup contract. Define explicit stop actions for resources that actually need teardown, and verify the external resource afterward.

9. auto_stop_in: safety net versus state surprise

A short TTL limits leaked review resources, but every new deployment resets the timer and periodic background processing means exact timing is approximate. A very short TTL can surprise reviewers; a very long TTL hides cleanup defects. Choose a duration from expected review lifetime and cost, then monitor stale external resources independently.

10. Deployment history as an audit/recovery index

GitLab preserves deployment metadata and keeps deployed commits reachable even as old deployment refs may be archived/cleaned. Use environment history to identify the last known-good deployment, but preserve artifact/package/image retention separately. A commit being reachable does not mean its original build artifact still exists.

11. Tier and offering matrix

12. Worked architecture decision

A team has 20 daily MRs, one shared staging environment, and one production target. They want low cost and strong production governance.

13. Evaluate tradeoffs across six dimensions

• Maintainability: can teams predict environment names/lifecycles without custom cleanup scripts everywhere?
• Security: can untrusted code reach deployment credentials, protected runners, or target networks?
• Reliability: can deployments be serialized where the target cannot accept concurrency, and can stale deployments be prevented?
• Compatibility: do Self-Managed version and runner/executor behavior support the chosen syntax/features?
• Performance: do Review Apps improve feedback enough to justify runner/deployment latency?
• Cost: how many dynamic resources, pipelines, artifacts, and hosted-runner minutes can exist concurrently?

14. Production policy template

Environment policy
- environment names map 1:1 to documented target classes
- every deploy logs commit + immutable artifact identity + target identifier
- review/* has explicit stop action and bounded TTL
- production deploys are serialized and verified externally
- production credential is environment-scoped / short-lived
- rollback redeploys known artifact identity; rebuild is a separate recovery mode
- protected-environment/approval rules are documented if licensed
- exception path names approver, reason, expiry, evidence, and follow-up

Knowledge check

Summary

Environment design is topology and trust design. Static versus dynamic names should match real external isolation; automation, manual runs, and deployment approvals solve different governance problems; scoped variables reduce exposure; and known-artifact rollback preserves identity. A production environment record becomes useful when every deployment can be independently tied to an immutable input and verified target.

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