Protected Environments, Deployment Approvals, Freeze Windows, Manual Gates, and Separation of Duties: Concepts, Architecture, and Mental Model

1. The practical problem: green is not the same as authorized

A pipeline can compile correctly, tests can pass, and an artifact can have a verified digest, yet a production change can still be unauthorized. Chapter 19 separated job success, GitLab deployment history, and external target health. This chapter adds another state boundary: who was allowed to authorize the change, under which policy, and with what audit evidence?

The safe model is deliberately conservative. Build and test jobs create evidence. Authorization policy decides whether a deployment candidate may cross a trust boundary. The deployment job performs the side effect. A health check then proves what happened outside GitLab. None of those states should be inferred from another.

2. Terms before configuration

3. State model: write down every boundary before changing it

A useful audit packet ties these rows together. If any link is missing, the claim “authorized production deployment succeeded” is incomplete.

4. Mental model: candidate → authorization → execution → health → audit

First a verified build produces a deployment candidate. GitLab compiles the deployment job and determines whether the target environment is protected and whether a freeze/manual rule applies. An approval policy may block execution until eligible approvers act. A deployer then starts or unblocks the deployment job. The job changes the target. Only an independent health check can establish post-deploy health. Finally, the pipeline, approval, deployment, and health identifiers form the audit record.

flowchart TD
  A[Verified artifact + SHA] --> B[Compiled deployment candidate]
  B --> C{Freeze/manual policy}
  C --> D{Protected environment authorization}
  D --> E[Approval record]
  E --> F[Authorized deploy action]
  F --> G[GitLab deployment record]
  G --> H[External target change]
  H --> I[Independent health verification]
  I --> J[Audit packet + exception history]

The arrows are causal dependencies, not decorations. For example, the approval record must point to the same candidate/deployment that is later health-checked; otherwise a reviewer can accidentally approve one revision while another is deployed.

5. Protected environments: who may execute the production side effect

Current GitLab documentation lists protected environments as Premium/Ultimate. A Maintainer or Owner can protect an environment and configure deploy access. Users not in the Allowed to deploy set cannot update or deploy to that protected environment. GitLab administrators retain broad authority, which means administrator actions belong in the audit model rather than being treated as invisible exceptions.

Protected environments are not the same as protected branches. A branch rule controls source changes; an environment rule controls deployment access. Mature delivery uses both when both source integrity and deployment authority matter.

6. Deployment approvals: authorization record, not rollout proof

Deployment approvals are also Premium/Ultimate. Required approvals block deployments to the protected environment until approval rules are satisfied. Current docs state that the pipeline triggerer cannot approve their own deployment by default; an explicit project option can allow self-approval. Administrators can approve or reject deployments, so admin intervention must be recorded as a governance event.

GitLab exposes approval details in the environment/deployment UI and through the Deployments API. The deployment can have a blocked status, and Premium/Ultimate responses can include approval summaries. After authorization, execution is still a separate event: approving does not prove the script ran or that the target became healthy.

7. Manual gates: useful, but model their blocking semantics precisely

Manual jobs exist on all tiers. Their pipeline behavior depends on allow_failure and where when: manual is declared. A top-level manual job defaults to optional behavior, while when: manual inside rules defaults to blocking behavior. To make intent unambiguous, use allow_failure: false for a blocking gate.

deploy_production:
  stage: deploy
  environment:
    name: production
  script:
    - ./ci/deploy-verified.sh "$CANDIDATE_DIGEST"
  when: manual
  allow_failure: false
  manual_confirmation: "Deploy the verified candidate to simulated production?"

manual_confirmation adds an explicit confirmation step, but it does not create independent authorization. If the same user can prepare, approve, and run the job, there is no true separation of duties.

8. Deploy freezes: policy input at pipeline creation

Deploy freeze periods are available on Free, Premium, and Ultimate. During an active freeze GitLab makes the pre-pipeline variable CI_DEPLOY_FREEZE=true available. That lets workflow, includes, and job rules decide whether a deployment job should be omitted, blocked, or converted to a controlled exception path.

deploy_production:
  stage: deploy
  script: ./ci/deploy-verified.sh "$CANDIDATE_DIGEST"
  environment:
    name: production
  rules:
    - if: '$CI_DEPLOY_FREEZE'
      when: manual
      allow_failure: false
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      when: manual
      allow_failure: false
    - when: never

A freeze is not external target health and not an air gap. It is a delivery policy signal. Any emergency exception should record who authorized it, why, which exact SHA/digest was affected, and how the target was verified afterward.

9. Inspect first: prove policy state without mutating it

Before playing, approving, retrying, or changing settings, capture evidence. In an authorized GitLab project, start with the pipeline graph and merged configuration; then inspect Operate → Environments for deployment status and approval details. Read freeze periods before editing them. If API access is authorized, prefer GET requests and avoid logging tokens.

# Read-only examples. Supply an authorized token through the client/environment; do not print it.
curl --fail --silent --show-error   --header "PRIVATE-TOKEN: $GITLAB_READ_TOKEN"   "$CI_API_V4_URL/projects/$CI_PROJECT_ID/freeze_periods"

curl --fail --silent --show-error   --header "PRIVATE-TOKEN: $GITLAB_READ_TOKEN"   "$CI_API_V4_URL/projects/$CI_PROJECT_ID/deployments?environment=production"

The response should be stored only if its contents are appropriate for your evidence retention policy. Never dump all CI/CD variables to “debug” authorization.

10. Separation of duties: design roles around failure impact

Small teams may combine roles operationally, but the course keeps the states separate so you can see exactly what assurance is lost when identities overlap.

11. Common mistakes and safer patterns

12. Summary and evidence checklist

• A verified artifact is a deployment candidate, not deployment permission.
• Protected environments and deployment approvals are Premium/Ultimate; manual jobs and freeze periods are available on Free.
• Approval, manual execution, deployment status, and external health are separate states.
• Default deployment self-approval is disabled; enabling it is an explicit reduction in separation of duties.
• A freeze should be observable in pipeline policy through CI_DEPLOY_FREEZE, and exceptions need their own evidence.
• Capture source SHA/digest, compiled configuration, policy/approval record, job/deployment IDs, actor, and post-deploy health.

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-12. The mandatory learning path uses only disposable/local simulation plus GitLab Free features. Protected environments and deployment approvals are treated as Premium/Ultimate and are simulated unless the learner already has an authorized eligible project.

• Protected environments — official reference.
• Deployment approvals — official reference.
• Deployment safety — official reference.
• Job control — official reference.
• CI/CD YAML reference — official reference.
• Predefined variables — official reference.
• Freeze Periods API — official reference.
• Deployments API — official reference.

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.