Protected Environments, Deployment Approvals, Freeze Windows, Manual Gates, and Separation of Duties: Configuration, Design Choices, and Tradeoffs

1. Design from the control objective, not from the button

A manual Play button, a protected environment, and an approval rule can all “look like gates,” but they answer different questions. The right design begins with the control objective: who may request, who may authorize, who may execute, what must be frozen, and which evidence must survive?

Keep CI_PIPELINE_SOURCE, CI_COMMIT_SHA, compiled job rules, candidate digest, and external target identity in the decision because authorization without candidate identity is not reproducible.

2. Manual job versus environment approval

3. Self-approval versus separation of duties

By default, current GitLab deployment approvals do not let the pipeline triggerer approve the same deployment. A project option can allow this. That option is useful in low-risk workflows, but it changes the assurance: the requester and approver become one identity.

4. Hard freeze versus emergency exception

A freeze is most useful when it is deterministic and visible before job execution. CI_DEPLOY_FREEZE is pre-pipeline, so rules can prevent normal production jobs from being included or can transform them into an explicit emergency path. Avoid relying on a shell check at the end of a privileged deployment job after secrets and target credentials have already been exposed.

rules:
  - if: '$CI_DEPLOY_FREEZE'
    when: manual
    allow_failure: false
  - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    when: manual
    allow_failure: false
  - when: never

For stricter organizations, the emergency job can be defined in a separately controlled include or deployment project so ordinary developers cannot rewrite the bypass condition.

5. Broad deploy role versus narrow authorization

Granting every Maintainer production deployment authority is easy but couples source administration, CI configuration, variable access, and production actions. A narrower protected-environment deployer set—or a separate deployment project introduced in Chapter 15—reduces blast radius.

Do not compensate for a broad role with secret masking. Masking protects logs, not authorization. Least privilege is about whether the identity can receive or use the credential at all.

6. Secrets and gate timing: do not expose production credentials before authorization

A common design error is to load a production credential in a preparation job, then place the manual or approval gate later. The credential has already crossed the trust boundary. Prefer environment-scoped/protected variables and structure the pipeline so the first job requiring the production credential is the actual authorized deployment job.

7. Auditability: record both normal and exceptional paths

The environment UI and Deployments API provide deployment IDs, SHA/ref, actor, status, and—on Premium/Ultimate—approval summaries. Freeze-period APIs provide policy schedule evidence. Those are useful but incomplete without external health evidence and any emergency-exception reason.

Do not make “administrator did it” the end of an incident narrative. Administrator authority is a fact; the audit packet still needs candidate identity, action, reason, target effect, and verification.

8. Worked decision table

9. Current behavior assumptions to pin in operating documentation

• Protected environments: Premium/Ultimate; Maintainer or Owner can configure project protection; administrators retain access.
• Deployment approvals: Premium/Ultimate; default self-approval by pipeline triggerer is disabled; eligible approvers can approve/reject; approvals are separate from actual deployment execution.
• Manual jobs: available on Free; explicit allow_failure: false makes blocking intent clear. Inside rules, manual jobs default to blocking behavior.
• Manual confirmation: supported for manual jobs; current docs also support environment stop-job confirmation.
• Freeze periods: Free+; CI_DEPLOY_FREEZE is pre-pipeline when active; maintainers/owners manage freeze periods through API/UI.

10. Failure isolation: authorization should not hide execution failures

If approval is correct but the deployment script fails, do not reopen or weaken the approval rule first. If the candidate digest is wrong, fix artifact flow. If the job cannot obtain a runner, fix scheduling. If the target is unhealthy after a successful job, investigate the provider/application. Layered evidence prevents policy controls from becoming a generic troubleshooting hammer.

11. Design review checklist

• State the control objective and tier prerequisite before choosing a gate.
• Tie approval to exact source SHA and candidate digest.
• Keep protected credentials out of pre-authorization jobs.
• Make freeze behavior visible in compiled configuration, not only in operator memory.
• Treat emergency bypass as a separately auditable workflow.
• Verify post-deployment target state independently of GitLab job/approval state.

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.