Skip to content
Sign in

How-to

Bypass Zof in an emergency

Updated

On this page

Merge one pull request that Zof can't allow, then close the gap again. It takes about 5 minutes, and you need admin on the repository, or on the organization for an organization ruleset.

Use this only when a change must ship and Zof can't say yes: during an outage, or for a change to zof.yaml that Zof judges by the old settings (see Change zof.yaml safely). Keep the bypass open for minutes, not days.

Before you start

  • Write down why you're bypassing, and keep it with your incident notes. Your admins will see the merge. Zof doesn't ask for the reason yet.
  • Find the ruleset that requires Zof / Control, for example Zof gate. See Make Zof block merges.

Open the bypass

  1. Go to Settings → Rules → Rulesets (Organization settings for an organization ruleset) and open the ruleset that requires Zof / Control.
  2. Under Bypass list, click Add bypass.
  3. Pick the narrowest actor that works:
    • Best: a small team, for example release-admins (Teams tab).
    • One-off: your own user (Users tab).
    • Avoid: Repository admin, which lets every admin bypass. Maintain and Write are worse still.
  4. Next to the actor, set the mode to For pull requests only, so the bypass still needs a pull request and leaves a record. Use Always allow only if the pull request flow itself is what's broken.
  5. Scroll to the bottom and click Save changes. GitHub doesn't apply it until you save.

Merge

  1. Open the pull request. The merge box now offers Merge without waiting for requirements to be met (bypass rules). Tick it and merge.

Close the bypass straight away

  1. Go back to the ruleset, remove the actor you added (open the ⋯ menu next to it, then Delete bypass), and click Save changes.

Check that it worked

  1. The ruleset's Bypass list shows no actors.
  2. On another pull request that Zof hasn't allowed, the merge box no longer offers Merge without waiting for requirements to be met (bypass rules).
  3. Your company's admins got a "Merged without Zof's approval" notification for the pull request, in the console's bell.

Enforced on the Configuration tab of the GitHub page doesn't tell you whether the bypass is closed: Zof doesn't read the bypass list, so it shows Enforced either way.

What Zof does after a bypass

Status
The merged commit keeps its failing Zof / Control check. GitHub's audit log records who bypassed.Works today
Zof records the merge as made without authorization.Works today
Admins get a "Merged without Zof's approval" notification in the console, and by email unless they turned it off.Works today
The change page’s Enforcement stage shows a recorded unauthorized merge in red.Works today
Releases and Reports summarize bypassed merges.Planned
Zof asks the person who merged for a reason, and stores it with the record.Planned
Planned. Releases and Reports don't summarize bypassed merges yet, and Zof doesn't yet ask the person who merged for a reason. Today you have the notification, Zof's own record of the merge, and GitHub's audit log.

Zof never turns a bypass into an approval. Its record of the merge keeps the result Zof had at the time, and that record is never changed.

Set up break glass before you need it

Most teams keep the bypass list empty and add an actor only during an emergency, as above. If you need a standing break-glass path instead:

  • add one small team, for example release-admins, never Repository admin;
  • set its mode to For pull requests only, never Always allow.

Example

On 2026-10-12 a test pull request added a tier-1 service to zof.yaml. Zof judged it by the old settings, where the new service had no tier, so it needed the strictest evidence and was blocked as "RELEASE BLOCKED: evidence missing". With an empty bypass list, nobody could merge it.

The repository owner added Repository admin to the Zof gate bypass list, saved, merged the pull request with the bypass option, then removed the bypass and saved again. The bypass was open for a few minutes. A single team or user would have been narrower.

Next steps