The protected environment pattern — the platform-side guard for production deploys

A protected environment is a first-class platform object: a named bucket such as production, staging, or canary, with protection rules attached. The bucket is the target of a deployment; the rules are the gate a deploy job must pass through before it can write to that target. On GitHub the construct is called an environment on the repository or organisation; on GitLab it is called a protected environment with allowed tiers. In both cases the rules live in platform configuration, not in the workflow file.

The construct is platform-side, not workflow-side

The most important property of the protected environment is that it is not a string in a YAML file. The string environment: production in a workflow job is a reference to a platform object. The platform object owns the rules. The workflow author does not decide who approves, how long the wait is, or which branches are allowed to deploy; the platform administrator decides, and the workflow file is incapable of overriding those decisions.

flowchart LR
    A["Workflow job declares environment: production"] --> B["Platform looks up object"]
    B --> C["Environment: production"]
    C --> D["Required reviewers"]
    C --> E["Wait timer"]
    C --> F["Branch restriction"]
    C --> G["Environment secrets"]
    D --> H["Gate evaluation"]
    E --> H
    F --> H
    G --> H
    H --> I{"All rules satisfied?"}
    I -- "yes" --> J["Job runs with environment identity"]
    I -- "no" --> K["Job held or rejected"]

The workflow declares where it intends to deploy. The platform decides whether the deploy is permitted. The two roles are intentionally separate: the workflow author can propose a deploy, but cannot approve one.

The canonical production environment

A canonical production environment on GitHub is configured once per repository, then shared by every workflow that targets it. The configuration commands are real and verifiable:

gh environment edit production \
  --required-reviewers user:alice,bob,team:platform-sre

gh environment edit production \
  --wait-timer 5

gh environment edit production \
  --deployment-branch-policy \
  --branch-patterns main,release/*

The first command names the required reviewers. The second sets a five-minute wait timer. The third restricts the environment to deploys from main or release/* branches. Three rules, three commands, one environment. Once configured, every workflow that declares environment: production inherits the rules.

gh environment view production

The view subcommand reports the live configuration - the reviewer list, the wait timer, the branch patterns, and any secrets attached to the environment.

The rules compose into a gate

Each rule addresses a different failure mode. Required reviewers gate the deploy on a named second pair of eyes. The wait timer creates a cooling-off window in which a hasty approval can be revoked. Branch restriction prevents a feature-branch deploy from reaching production. The three rules are independent: a configuration that has two of three has been completed but not finished. The next lesson covers required reviewers and the wait timer in detail; the one after covers branch restriction.

Production discipline

1. Configure the environment once at the platform level. Do not reimplement the gate in workflow code.
2. Treat the workflow’s environment string as a reference. A typo in the string is a deploy with no gate.
3. Verify all three rules are present. Two of three is a configuration completed but not finished.
4. Audit the environment quarterly. The reviewer pool drifts; the timer drifts; the branch list drifts. The audit must catch the drift before the deploy does.

Cross-course references

• This course, Part LVII-03 (Protected environments and required reviewers) introduces the three rules at an intermediate level.
• This course, Part XLVIII-06 (Environment protection rules) covers the rules in the context of conditional execution.
• Terraform for Production Sysadmins - Part XXVIII covers the canonical promotion pattern through protected environments.

Quiz