Make Zof block merges

Make GitHub refuse to merge a pull request until Zof allows it. It takes about 5 minutes, and you need admin on the repository or the organization.

Zof decides whether a change may merge. GitHub is what stops the merge, and it does that only when a ruleset requires the Zof / Control check from the Zof GitHub App, the app connected during Connect GitHub. Until you add that ruleset, Zof is advisory: it tells you a change is blocked, but anyone with write access can still merge it.

Before you start

• The Zof GitHub App is installed on the repository. See Get started.
• Zof has posted Zof / Control on at least one pull request in the repository. GitHub only offers a check it has already seen.
• Your GitHub plan supports rulesets:

A private repository on a free plan shows Needs a paid plan in Zof, and its pull request checks say so too.

Set up the ruleset

We recommend an organization ruleset (Organization settings → Rules → Rulesets), so every repository is covered at once. The steps below are for one repository. The screens are the same.

1. Open the repository's Settings → Rules → Rulesets and click New ruleset → New branch ruleset.

2. Ruleset name: type a name, for example:

   Zof gate
   

3. Enforcement status: change Disabled to Active. A Disabled or Evaluate ruleset blocks nothing, and Zof reports it as not enforced.

4. Bypass list: leave it empty. Anyone on this list can merge around Zof. For emergencies, see Bypass Zof in an emergency.

   Warning. Zof doesn't read the bypass list. Enforced means GitHub requires the check, not that nobody can bypass it. Keep the list empty, and check it yourself when you review the ruleset.

5. Target branches: click Add target → Include default branch. Add every other branch that pull requests merge into, for example with Add target → Include by pattern:

   release/*
   

6. Branch rules:

   • Keep Restrict deletions and Block force pushes on.
   • Turn on Require a pull request before merging. Open Show additional settings and set Required approvals to 0. Zof already requires the right approvers, and never counts the author. A GitHub approval count on top would be a second gate.
   • Turn on Require status checks to pass. Leave Require branches to be up to date and Do not require status checks on creation off.

7. Under Status checks that are required, click Add checks and type:

   Zof / Control
   

   Select the entry whose source is the Zof GitHub App. On GitHub, the Zof GitHub App appears under the name it was registered with, which is Zof AI on Zof's hosted service. The Zof console doesn't show that name.

8. In that row, check that the source is the Zof GitHub App (Zof AI on Zof's hosted service), not Any source. With any source, anyone could post a green check with that name, so Zof reports the branch as not enforced.

9. Leave every other rule off and click Create.

Don't see Zof / Control in the list? GitHub only suggests checks it has seen on this repository. Open any pull request in it, wait for the Zof / Control check, then come back to step 7. Don't pick the "Add zof — Any source" entry GitHub offers while you type. It requires a check literally named zof from any app. Nothing posts that, so every pull request would stay blocked.

Classic branch protection works too. Require Zof / Control from the Zof GitHub App, and tick Do not allow bypassing the above settings, otherwise admins can merge around it.

Check that it worked

1. In the Zof console, open Integrations, then open the GitHub card and the Configuration tab. The branch shows Enforced within a few minutes for a repository ruleset, and within about 10 minutes for an organization ruleset.
2. Open a test pull request into that branch. While Zof / Control isn't green, GitHub's merge button is disabled.
3. New pull requests no longer carry the "Not enforced" warning.
4. In the ruleset, Bypass list shows no actors. Zof can't check this for you.

If the branch shows Not enforced, Needs a paid plan or Can't confirm, check the ruleset against the steps above. Each label, with its causes, is in Enforcement statuses.

Choose which branches to protect

A ruleset applies only to the branches it targets.

Zof checks every pull request, whatever its base branch. For a pull request into a branch the ruleset doesn't cover, the check still shows Zof's decision, but it warns "Not enforced: developers can merge this PR despite this result". The Configuration tab lists that branch as Not enforced. So the console always tells you which branches are really protected.

Try it first in Evaluate mode

A ruleset in Evaluate mode reports what it would block without blocking anything. Zof shows Not enforced until you switch the ruleset to Active.

While a branch isn't enforced

The check shows Zof's result and warns on every pull request, but anyone with write access can still merge. When someone merges a pull request that Zof hasn't allowed, Zof records it, and your company's admins get a "Merged without Zof's approval" notification.

Not supported yet

Merge queue. If a branch Zof gates uses a merge queue, the queue waits for a Zof / Control result on the queue's own commit. Zof doesn't post one there, so merges would wait forever. Until Zof supports it, a branch that Zof gates can't use a merge queue.

Why Zof doesn't set this up for you

Creating a ruleset needs write access to your repositories' administration settings. Zof doesn't ask for that. It reads your rules to tell you whether the ruleset is in place, and never changes them.

Zof writes only:

• its own checks: Zof / Control, and Zof / Review, which is always neutral and never blocks a merge;
• comments on a pull request, when a Zof code review is posted to it.

It never approves a pull request.