The compliance check
The second check on a pull request — what madebook/compliance evaluates on the exact commit, why only commit-exact and independent evidence counts, approval rules, expiring exceptions, and how Madebook verifies the host would actually block a merge.
madebook/supervised says a pull request went through Madebook. It cannot say that the exact commit about to merge meets the organization's rules, or that the host would stop it if not. madebook/compliance answers both, and it is the check to make required when you want Madebook to block merges.
| Check on the pull request | Question | Turns red when |
|---|---|---|
madebook/supervised |
Did this work go through Madebook? | Nobody reported it through the MCP, or a critical control fired. |
madebook/compliance |
Does this commit meet the rules this organization set? | Anything the rules require is missing, stale, unverified or unresolved, and no valid exception covers it. |
Keep them apart. The first stays deliberately narrow. The second is the one this page is about.
What it evaluates
For one pull request, at its current head commit:
| Item | Met when |
|---|---|
supervision |
(repositories that require supervision) a session claimed the pull request and no critical control fired |
protocol |
the session is not waiting on a person — no BLOCKED, DECISION_REQUIRED or HARD_STOP |
decisions |
no decision gate on the session or mission is open |
contract |
the mission's contract is approved, and the session was briefed on that version |
evidence:<kind> |
a requirement from the contract, a policy the change tripped, or its risk band has current, independent evidence on this commit |
policy_block:<key> |
a policy with a block_merge action did not fire on this change |
policy_monitor:<key> |
always met — a policy in its monitor stage fired; the detail says what it would require once enforced |
approvals |
enough independent approvals on this commit (more for high-risk changes) |
owners:<rule> |
each owned path has an approval from one of its owners (Madebook rules or CODEOWNERS) |
Each item is met, unmet, unknown or excepted. The verdict passes only when every item is met or excepted.
Unknown fails. When Madebook cannot establish something — a team's members, the paths a commit changed, the host's configuration — the item is unknown and is treated as unmet. A verdict that cannot be established is not a pass.
Compliance mode
Set per repository on the workspace's Compliance page:
| Mode | What happens |
|---|---|
| Off | Nothing is evaluated or posted. This is the default, and the governance journey asks you to either turn it on or leave it off on purpose. |
| Monitor | Evaluated and posted; a failure is posted as neutral, so it is visible and blocks nothing. The right first setting. |
| Enforce | A failure is posted as failure. It blocks merges only once the host requires the check — see Enforcement state. |
Judged repositories re-sync their pull requests every ten minutes, so mirroring no longer depends on webhooks arriving.
Evidence is commit-exact
Before, evidence was matched by label across the mission, on any commit. Now every CI result and review is stored with the repository, pull request, commit, host id, issuer and attempt it came from, and its standing — current, superseded or revoked — is recomputed from stored facts after every change. So:
- a push supersedes every result on the old commit;
- a re-run supersedes the earlier run of the same check, even while it is still pending;
- an approval is withdrawn by a later request for changes, a dismissal, or (by default) a new commit;
- a webhook arriving late or twice changes nothing — replays, polls and out-of-order deliveries converge on the same answer.
Only current evidence on the head commit counts. Evidence that names no commit cannot vouch for any code and counts for nothing.
Agent-reported evidence never counts. An agent's account of its own tests is stored as reported (see Evidence and gates); compliance reads only observed and attested.
Check mappings. On the repository's Compliance settings, a mapping says "this check, from this issuer, is our unit test suite". A repository can require mapped checks only, so a check classified from its name alone satisfies nothing.
Approvals
Before, any approval counted — including the author's own, and stale ones. Now only independent approvals on the head commit count.
Organization → Approval rules holds the approval policy. The organization's default applies, a workspace can override it, and a repository can override that — most specific wins. A policy sets:
| Setting | What it decides |
|---|---|
| Required approvals | How many independent approvals an ordinary change needs |
| High-risk approvals | How many a high-risk change needs |
| No self-approval | The pull request author and every commit author are excluded |
| Stale approvals | Whether a new commit withdraws earlier approvals (on by default) |
| Path owners | Paths that need an approval from a named owner or team |
| CODEOWNERS | Whether the repository's own CODEOWNERS file is applied |
| Security reviewers | Designated reviewers for security-relevant changes |
| Skip on ship / review | Whether shipping a mission or reviewing a capsule may skip what is missing |
Owners and teams are resolved through the GitHub App (it needs Members: read for @org/team). A team Madebook cannot read makes the item unknown, and unknown fails.
Exceptions
Before, shipping recorded an optional note. Now an exception is a first-class record, at Organization → Exceptions:
- it names the items it waives, for one pull request (optionally pinned to one commit) or one mission;
- it has a reason and an expiry — when it expires the pull request is re-evaluated;
- it is approved by someone other than the requester.
An emergency exception can be self-approved by an owner or admin, lasts at most 24 hours, and must be reviewed afterwards by a different admin. Every step — request, approval, revocation, expiry, emergency review — is audited.
Pending exceptions and overdue emergency reviews appear in the attention queue and the review queue.
Enforcement state
Turning enforce on is not the same as being enforced. Madebook reads the host's branch protection and rulesets for the default branch and reports one of:
| State | Meaning |
|---|---|
| enforced | madebook/compliance is required, from the Madebook GitHub App, in an active rule. |
| misconfigured | Compliance is enforced here but the host does not require the check, does not pin it to the App, or only evaluates the rule. The reading carries the exact fixes. |
| monitoring | The repository is in monitor mode. |
| unavailable | Madebook cannot read the configuration — a permission, a plan, or a host it cannot verify yet. GitLab and Azure DevOps read as unavailable today. |
Bypass — administrators exempt, ruleset bypass actors — is reported alongside the state. Verification reruns every six hours, on protection-change webhooks, and on demand; a change of state is audited and raised in Attention.
A personal-token connection can never be enforced. Anyone with write access can post a commit status, so a check that is not pinned to the App proves nothing. Enforcement requires the check to be required from the Madebook App. See The pull request check.
Where it shows
| Page | What it holds |
|---|---|
| Workspace → Pull requests | The list, and a page per pull request: the verdict item by item, evidence with its standing, verdict history, what authorized the change, the rules in force, enforcement, exceptions, and — for a session run by CodeBook — what its session reported. |
| Workspace → Compliance | Mode per repository, host enforcement with findings and fixes, check mappings, approval rules, exceptions, plus the Coverage and Outcomes cards for this workspace. |
| Organization → Approval rules | The approval policy and its overrides. |
| Organization → Exceptions | Every exception, its state and its approver. |
| The Ship and Review dialogs | Explain a refusal item by item. |
| Attention | Pending exceptions, overdue emergency reviews, enforcement drift. |
The GitHub App permissions this needs
The App requests Administration: read (branch protection and rulesets) and Members: read (teams in owner rules), and subscribes to the status, branch_protection_rule and repository_ruleset events. An App created before this must have its permissions updated on GitHub, and existing installations must accept them; Admin → Integrations → Verify with GitHub lists what is missing by name.
MADEBOOK_PRIVATE_HOSTS is an operator-only allow-list so a GitHub Enterprise Server on a private network is reachable. It can never admit the cloud metadata range.