Bypass and bypass actors — the role-based exceptions that weaken the gate

The required-reviewer rule is the human gate on the protected environment. The bypass actor is the role-based exception that lets specific users or roles skip that rule. The bypass is a real mechanism with real production purposes: a break-glass account, a rotated service identity, an automated remediation workflow. It is also the easiest way to make a protected environment unprotected. This lesson covers the bypass mechanism, the smallest possible set of bypass actors, and the production discipline of never bypassing the gate in normal operation.

What a bypass actor is

A bypass actor is a user, team, or role that is permitted to deploy to a protected environment without satisfying the required-reviewer rule. The branch restriction and the wait timer still apply; only the reviewer pool is skipped. The bypass does not disable the environment; it short-circuits one specific rule.

flowchart TD
    A["Deploy job requested"] --> B{"Branch allowed?"}
    B -- "no" --> X["Rejected"]
    B -- "yes" --> C{"Actor is bypass actor?"}
    C -- "yes" --> D["Skip reviewer pool"]
    C -- "no" --> E["Held for reviewers"]
    D --> F{"Wait timer elapsed?"}
    E --> G["Reviewers approve"]
    F --> H["Apply"]
    G --> I{"Wait timer elapsed?"}
    I --> H

The bypass path skips the reviewer pool but still passes through the wait timer and the branch restriction. A bypass actor who deploys from the wrong branch is still rejected by the platform; the bypass only short-circuits the human gate.

The smallest possible set

The bypass list must be the smallest possible set of actors that satisfies the operational requirement. The operational requirement is break-glass: when normal reviewers are unavailable, an authorised actor can deploy without them. The smallest set is typically one or two named individuals, or a single break-glass team.

The GitHub CLI configures the bypass list through the reviewer pool itself: a user or team added to the required-reviewers list can also be marked as a bypass actor. The configuration is platform-side and lives in the environment settings. There is no separate bypass flag; bypass is a property of the actor’s role in the required-reviewers configuration.

gh environment view production

The view subcommand shows the reviewer pool. A bypass actor is identifiable by the absence of any reviewer requirement on their deploys; the audit log shows the deploy as not held for review with the actor named.

The audit trail a bypass leaves

A bypassed deploy leaves an audit trail that records three things: the actor who triggered it, the timestamp, and the reason if the platform asks for one. The trail does not record the justification, the urgency, or the post-hoc narrative - those are reconstructed from Slack threads, incident channels, and the operator’s memory.

flowchart LR
    A["Bypass actor deploys"] --> B["Audit: actor + timestamp"]
    B --> C["Slack thread: justification"]
    B --> D["Incident channel: urgency"]
    B --> E["Operator memory: post-hoc narrative"]
    C -. "Reconstructed" .-> F["Reconstructed audit"]
    D -. "Reconstructed" .-> F
    E -. "Reconstructed" .-> F

The platform-recorded audit is incomplete. The reconstruction is what the post-incident review will use to evaluate the bypass. A team that bypasses regularly has a permanent gap in the platform audit because the justification lives in chat and the chat is searchable by keyword, not by bypass event.

Why the bypass must never include the deployment identity

A common mistake is to add the CI service identity or the GitHub Actions bot as a bypass actor. The reasoning is that automated deploys should not wait for human review. The reasoning is wrong: an automated deploy that does not need human review does not need to target a protected environment; it can target an unprotected one. The protected environment exists to enforce the human gate; removing the gate from automated deploys is a configuration that has collapsed the boundary.

Production discipline

1. Keep the bypass list to the smallest possible set. One or two named actors is typical.
2. Never bypass for convenience. Bypass is for break-glass only.
3. Audit every bypass after the fact. The platform records the actor; the team records the rationale.
4. Never add automated deploy identities as bypass actors. An automated deploy that needs no review should target an unprotected environment.

Cross-course references

• This course, Part LVII-06 (Approval fatigue and bypass risks) covers the human-behaviour failure mode.
• This course, Part XXXIV-06 (The least-privilege credential) covers the identity-isolation discipline the bypass list must respect.
• This course, Part XCI-05 (Least privilege in GitOps) covers the GitOps-side analogue of bypass actors.

Quiz