Environments, Deployment Protection Rules, Approvals, Concurrency, and Rollbacks: Configuration, Design Choices, and Tradeoffs
A working deployment pipeline can still embody the wrong policy. This lesson turns the mechanics from Lesson 2 into design decisions: where configuration belongs, which approvals deserve humans, when concurrency should cancel or queue, and why promotion of one artifact usually provides stronger evidence than rebuilding per environment.
Learning objectives
- Choose environment-, repository-, or organization-scoped configuration based on trust and ownership boundaries.
- Compare human approval, built-in protection rules, and custom automated protection rules without treating any one as universal.
- Select cancellation versus queueing semantics according to the reversibility and duration of the deployment operation.
- Justify same-artifact promotion versus rebuild-per-environment using provenance and reproducibility requirements.
- Apply current plan/visibility/deployment constraints without making paid features mandatory.
Availability: All mandatory decision exercises have a public GitHub Free implementation. Private/internal environment availability and certain enterprise governance patterns are labeled separately. Custom deployment protection rules are public preview; organization secrets and enterprise policies are not required.
1. Scope configuration where the authority actually changes
| Data/control | Best scope when… | Governance consequence |
|---|---|---|
| Environment secret | Credential is usable only against one deployment target. | Access is delayed until environment protection passes; still treat runner/network as trusted infrastructure. |
| Environment variable | Non-secret target setting differs by environment. |
Available as vars only to jobs referencing that
environment.
|
| Repository secret/variable | All workflows in one repository legitimately share it. | Broader blast radius than environment scope; repository workflow writers matter. |
| Organization secret/variable | Many repositories share centrally managed configuration. | Requires org policy/visibility design; increases dependency and admin blast radius. |
| OIDC/federation | External provider supports short-lived identity federation. | Avoids a stored long-lived cloud key; deeper OIDC treatment is Chapter 20. |
Do not store a production credential at repository scope merely because it is easier to reference. The environment is useful precisely because the credential can be unavailable before the gate.
2. Manual approval and automated protection solve different uncertainty
A human reviewer is useful when the decision requires business context, incident awareness, or separation of duties that is not fully machine-readable. A wait timer is useful for a deliberate observation window, not as proof of correctness. Branch/tag restrictions are useful when only vetted refs should be eligible. A custom deployment protection rule is useful when an external system can evaluate objective readiness—change tickets, observability thresholds, test systems—but it introduces a GitHub App, webhook/API availability, and policy dependency.
Production policy often combines controls: immutable artifact identity + required reviewers + an automated health/change-management gate + target IAM. Do not make a reviewer re-evaluate facts that machines can prove, and do not ask automation to decide subjective business risk it cannot observe.
3. Cancellation versus queueing is a state-transition choice
| Operation | Typical choice | Reason |
|---|---|---|
| Preview deploy for latest PR revision | cancel-in-progress: true |
Old preview has little value; newest commit supersedes it. |
| Staging smoke deployment | Often cancel stale in-progress if activation is atomic/restartable. | Faster feedback, but only if cancellation cannot leave partial target state. |
| Database migration / production rollout | Queue/serialize; avoid cancellation after mutation starts. | Mid-flight cancellation may leave partial irreversible state. |
| Long-running validation with valuable diagnostics | Queue or distinct group per revision. | Canceling may hide evidence needed for diagnosis. |
Concurrency names are repository-wide. Prefix them with the
system/environment/workflow boundary you intend, for example
payments-production-deploy, rather than generic
deploy. Current GitHub.com also supports
queue: max; verify your GitHub Enterprise Server
version before copying that property into GHES.
4. Promote the same artifact when the question is “did staging test what production received?”
Rebuilding per environment can be legitimate if the artifact intentionally embeds target-specific configuration. But it destroys a powerful invariant: byte equality between staged and production payloads. A stronger pattern is usually build once, sign/hash/attest once, store the artifact, then inject target configuration at deploy/runtime boundaries. Production receives the same artifact digest that staging validated.
If rebuilding is unavoidable, treat each rebuild as a new artifact with a new digest and new evidence. Never describe it as “promoting the same release” when the bytes changed.
5. Define rollback before the first production deployment
A rollback policy should answer: which prior artifacts remain retained; who may initiate rollback; whether approval remains required during incidents; what target data/schema compatibility constraints exist; how concurrency behaves; how health is verified; and how the resulting deployment is recorded. Emergency access should shorten bureaucracy without deleting evidence.
For example, a break-glass path might use a smaller named reviewer set plus an incident number, but still require artifact digest verification and a fresh deployment record. “Admin bypass and fix it manually” is not a rollback design.
6. Current availability matters to architecture
| Capability | Current public-repository path | Private/internal note |
|---|---|---|
| Environments + environment variables/secrets | Available on current plans; GitHub Free lab works in public repo. | Private/internal environment access requires Pro/Team/Enterprise depending on account/repository. |
| Required reviewers / wait timer | Available in public repositories on Free/Pro/Team. | Private/internal availability is plan-dependent; verify current plan. |
| Deployment branch/tag restrictions | Available for public repos. | Also available for private repos on Pro/Team; enterprise policy may add constraints. |
| Custom deployment protection rule | Available in public repos; currently public preview. | Private/internal use currently requires Enterprise. |
| Concurrency | Actions workflow feature, independent of environment object. | Availability follows Actions/deployment version; newer queue semantics may differ on GHES. |
7. Worked scenario: payments API with staging and production
Context: 20 deploys/day, public demonstration repository but a real external runtime, database migrations on some releases, two release managers, automated observability gate available.
Choice: build one immutable package, verify digest
in staging, use cancel-in-progress only for staging
application deployment, serialize production with a queue, require a
release-manager reviewer with self-review prevented, add the
observability rule only after its failure mode is understood, use
OIDC for cloud identity, and retain at least the last known-good
artifacts through the rollback window.
Why: this maximizes evidence consistency and reduces credential exposure. It costs more storage than rebuilding from source on demand, but lowers incident ambiguity. The human review is retained where business/incident context matters; objective health evidence is automated.
8. Decision table
| Question | Prefer A | Prefer B |
|---|---|---|
| Reusable credential scope? | Environment when credential belongs to one target. | Repository/org only when broader use is intentional and governed. |
| Gate type? | Manual reviewer for contextual/separation decision. | Automated custom rule for objective external evidence. |
| Concurrency? | Cancel when work is safely superseded and interruption is harmless. | Queue when mutation must finish and ordering/serialization matters. |
| Promotion? | Same artifact when production should receive staging-tested bytes. | Rebuild only when target-specific build is an explicit design, then treat as new artifact. |
| Rollback? | Redeploy known-good retained artifact through normal/incident gate. | Compensating change when runtime/data semantics make old artifact unsafe. |
Knowledge checks
Why is an environment secret usually a better home for a production-only credential than a repository secret?
Its scope matches the target, and GitHub withholds it until the environment protection rules pass. That narrows exposure compared with a repository-wide secret.
When is cancel-in-progress a poor production choice?
When cancellation can interrupt a non-atomic or irreversible mutation such as a database migration or leave the target in a partial state.
Does an automated deployment protection rule remove the need for target-system IAM?
No. It is a GitHub admission gate. The external runtime still needs its own authentication/authorization and should independently reject unauthorized mutation.
If staging and production builds have different SHA-256 digests, may you claim production received the artifact staging tested?
No. They are different artifacts. Either promote the same bytes or treat the second build as a new artifact requiring new evidence.
What is the production value of preventing self-review?
It enforces separation of duties: the actor who initiates a deployment cannot be the sole approver of that same deployment.
Summary
Good deployment governance scopes credentials to targets, automates objective evidence, preserves meaningful human separation, serializes state-changing operations appropriately, promotes identified bytes, and defines rollback before incidents. Availability is part of the design: a policy that assumes an unavailable protection rule is not a policy.
Next: Lesson 4 deliberately breaks environment names, concurrency groups, approval identity, artifact promotion, and plan assumptions, then diagnoses each failure without erasing evidence.
Further reading
- GitHub Docs — Deployments and environments
- GitHub Docs — Managing environments for deployment
- GitHub Docs — Reviewing deployments
- GitHub Docs — Deploying with GitHub Actions
- GitHub Docs — Control workflow/job concurrency
- GitHub REST — Deployment environments (2026-03-10)
- GitHub REST — Deployments
- GitHub REST — Deployment statuses
Keep the academy open
Support free, practical DevOps education.
Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.
0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0
Send only Ethereum/ERC-20 compatible assets to this
address.