Bypass and bypass actors — who can override the rule and what is left behind

Every branch protection rule has a bypass. The bypass exists for the same reason CODEOWNERS has a bypass (covered in Part XXXI): incidents require immediate action, and waiting for an unavailable reviewer or a queued CI check is not an option. The bypass is not a violation of the control; the bypass is part of the control. The dangerous failure mode is bypass without an audit trail.

This lesson walks the bypass actors on the major forges, the conditions under which they can override, the audit trail that bypass leaves, and the production discipline that makes bypass useful rather than harmful.

Bypass actors

The set of bypass actors is similar across forges, though the naming differs:

flowchart LR
    A[Rule blocks merge] --> B{Bypass actor invoked?}
    B -->|no| C[Merge remains blocked]
    B -->|yes| D[Bypass event recorded]
    D --> E[Merge proceeds with audit annotation]
    E --> F[Audit trail captures actor, time, reason]

• Repository administrators. On GitHub, the rule “Allow specified actors to bypass required pull requests” defaults to allowing administrators. On GitLab, project maintainers (role) can bypass by configuration. On Bitbucket, the rule can be set to allow “admins to bypass branch permissions”. The default semantics is: by default, admins can override; the rule must explicitly opt out.
• Users and teams on the bypass list. GitHub exposes this as a per-rule list of users and teams who can bypass. GitLab has the same via “approver groups” and “bypass settings” in the approvals API. Bitbucket exposes “Bypass for” with user or group selectors.
• Break-glass accounts. A small, named set used only for incident response. Their use is logged and alarmed. Typically the on-call lead and one or two backups. The accounts are separate from the bypass list because they have their own credentials and their own audit posture.

The configuration default is the most important thing to know about bypass: most forges ship with “admins can bypass” turned on by default, as a usability concession for small repositories and for repo recovery scenarios. Production repositories must turn this off explicitly. A protection rule that allows admins to bypass is a protection rule that an admin can wipe; the rule exists for normal change, not for insider action.

When bypass is permitted

Three conditions must hold for a bypass to be a legitimate bypass:

1. The actor is in the configuration. A user not on the bypass list cannot bypass by intent; if the forge nevertheless allows them to, the configuration is wrong.
2. The conditions for the bypass are met. Some forges require a reason; some require a linked incident ticket; some require a comment on the merge. The configuration determines which.
3. The forge records the bypass. Without an audit event, the bypass is indistinguishable from a normal merge.

Production discipline is to make all three conditions visible in the same UI surface: the bypass list, the conditions, and the audit log query are documented in the protection rule’s documentation, alongside the rule itself.

Audit trail and the bypass event

Bypass is not invisible. Every forge records bypass as a distinct audit event. The minimum record contains actor, action, time, target PR or push, and (optionally) reason or linked incident ticket. The exact event names vary by forge:

• GitHub: protected_branch.policy_override, protected_branch. bypass_actor_allowed, and the merge event itself with the actor tag.
• GitLab: approved_merge_request, merge_request_bypass, and changes to protected-branch settings.
• Bitbucket: a permissions-bypass attribute on the push event.

The audit log answers the question “did this rule ever fail to apply, and if so, who made it not apply, and when?”. A bypass that is not in the audit log is a bypass that did not happen - either a feature (the rule never failed) or a control failure (the rule failed and the failure was hidden).

A common production pattern is to alert on bypass events:

ALERT: branch_protection_bypass {actor, branch, pr, reason?, ...}
  ON every bypass event
  TO security-on-call and the on-call lead
  WITH a requirement to file an incident ticket within one business day

The alert’s purpose is to force the bypass into the team’s forensic record. Without an alert, the bypass is a footnote in the audit log; with an alert, the bypass is a paged event that the team must address.

The limit of branch protection as a control

Branch protection is a routing layer over a permission system. The permission system has admins. Admins can do anything the forge allows, including bypassing the rules they themselves configured. This is not a flaw; it is the design. The implications:

• Branch protection cannot prevent insider action. A determined admin with merge rights can bypass branch protection, push directly, or rewrite history. Branch protection is a process control, not a security boundary against insiders.
• Branch protection cannot prevent a malicious admin from removing the protection. An admin can delete or weaken the rule. The defence here is the audit log of changes to the protection rules, which is a separate event stream from the bypass event itself.
• Branch protection is one control in a stack. Signing prevents author spoofing. Audit logs capture what actually happened. CODEOWNERS routes the review. Tag discipline protects release artefacts. None alone is a complete control; the stack is the control.

flowchart LR
    A[Branch protection] --> F[Governance stack]
    B[CODEOWNERS] --> F
    C[Status checks] --> F
    D[Signed commits] --> F
    E[Audit log] --> F

Production discipline

Three rules for bypass on a production repository:

1. Bypass actors are configured narrowly. Two to four named individuals; teams in the bypass list are forbidden. The list is reviewed at the same cadence as the protection rule itself.
2. Bypass events generate alerts. Every bypass event is paged to security and requires an incident ticket within one business day. The alert is the audit log’s downstream detection layer.
3. Bypass is reviewed at every retrospective. Was it necessary, was it the right path, and what could have prevented it from being needed. The retro finding becomes a candidate rule change: a new required check, a new CODEOWNERS entry, a tighter bypass list.

Cross-course references

• Linux for Production Sysadmins - Part XIV (AuditLogging) covers audit logging at the OS layer; the bypass-event pattern is identical in form.
• Ansible for Production Sysadmins - Part XXXVIII (QualGates) covers the gate-bypass pattern in CI; the audit discipline is the same.
• Terraform for Production Sysadmins - Part XXXIII (StateGuard) covers the same bypass pattern on Terraform state changes, including the role of terraform apply in an incident.

Quiz