Reason codes

Every reason Zof can give for a decision, what it means and what to do. Each pull request's Zof / Control check lists its reasons under "Why". In Releases, the pull request's page shows every reason, and each gate on its Quality gates tab says what it needs and what to do. A gate names the capability, and the rule it comes from follows as Rule:; the rule's wording does not change what evidence is required.

When a decision has several reasons, the strictest wins: a denial, then missing evidence, then a missing approval. See How Zof decides.

In the console, a hold reads Blocked when only these reasons hold it: unmapped_files, unverifiable_requirement, policy_not_published. With any other reason beside them, it reads Needs evidence.

Evidence and checks

blocking_check_failed

On the check: "A required check failed."

Result: Denied (check: RELEASE DENIED)

A required test or check ran and failed on this commit. The check shows it as Failed. Fix it and push a new commit.

To unblock: Fix the failing check and push a new commit.

verification_contradicted

On the check: "A required check's result contradicts its rule."

Result: Denied (check: RELEASE DENIED)

Verification found a result that goes against a required check. Fix the problem and push a new commit.

To unblock: Fix the failing check and push a new commit.

missing_blocking_evidence

On the check: "A required check hasn't run yet."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

A required check hasn't reported a result for this commit, so the check shows Not run yet. Zof waits for Verification, and the check names what is missing. When unit tests passed but don't run every changed line, the check shows Changed lines untested instead, or Couldn't check when Zof couldn't measure which lines they run.

To unblock: View this run in the console.

Until a company publishes a release policy, Zof holds every change with this reason and the requirement policy.chosen. No test can meet it, so Zof says "No release policy chosen yet." instead, and the next step is to publish one. See Change your release policy.

insufficient_evidence

On the check: "A required check didn't report enough to pass."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

A result arrived but doesn't meet the rule, for example a load test above the latency limit.

To unblock: View this run in the console.

unverifiable_requirement

On the check: "Zof can't check a required rule as it is written."

Result: Blocked (check: RELEASE BLOCKED: evidence missing)

The rule asks for something Verification can't check as written. An admin changes the rule in Release policies so that it can be checked. The console has no way to waive a requirement yet.

To unblock: Add verification criteria or waive the requirement.

capability_unavailable

On the check: "A check couldn't run."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

The tool that runs the check failed or timed out, so the check shows Couldn't check. Once it is back, click Re-evaluate on the check.

To unblock: Re-evaluate once the input is available.

stale_evidence

On the check: "The check result is for an older commit or is too old."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

The result is for an older commit, or too old. A new run on this commit fixes it.

To unblock: View this run in the console.

evidence_criteria_mismatch

On the check: "The check ran against another policy version."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

The check ran against a different policy version. Verification has to run again against the live policy, and today that happens on a new push: the console says "Push a commit to re-check under the new policy."

To unblock: Re-run verification against the current policy.

no_verification_result

On the check: "No verification run exists for this change yet."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

Verification hasn't reported on this commit yet. The check shows "Evaluating: waiting for verification" with the time it will fail closed, usually 30 minutes after it starts waiting.

To unblock: View this run in the console.

unrecognized_verification_status

On the check: "Verification reported an unknown status."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

Verification sent a status Zof doesn't know, so Zof doesn't count it. Re-evaluate later.

To unblock: Re-evaluate once the input is available.

Approvals

approval_required

On the check: "A required approval is missing."

Result: Awaiting approval (check: AWAITING APPROVAL)

An authorized approver must approve the pull request on GitHub. The check names the teams. The author never counts.

To unblock: Approve this PR as an authorized reviewer for the named teams.

approval_invalid

On the check: "An approval no longer counts."

Result: Awaiting approval (check: AWAITING APPROVAL)

Someone approved, but the approval doesn't count. Common causes: the approver wrote the change or pushed to it, the approval was revoked or expired, it was given before Verification reported on this commit, or the evidence changed after it was given. An approval of an older commit is ignored instead, so it shows as approval_required. Ask a listed approver who didn't write the change to approve the current commit.

To unblock: Approve this PR as an authorized reviewer for the named teams.

approval_rejected

On the check: "An authorized reviewer requested changes on this head."

Result: Denied (check: RELEASE DENIED)

An authorized approver chose Request changes on this commit. It stays denied until that reviewer approves the commit, the review is dismissed on GitHub, or a new commit is pushed. Another approver's approval doesn't lift it.

To unblock: Approve this PR as an authorized reviewer for the named teams.

approver_authority_unavailable

On the check: "A reviewer's teams are unresolved; retrying."

Result: Awaiting approval (check: AWAITING APPROVAL)

Zof couldn't confirm a reviewer's GitHub teams, for example because GitHub didn't answer or the Members: read permission isn't granted. Zof tries again about once a minute.

To unblock: Re-evaluate once the input is available.

target_environment_unknown

On the check: "The environment is unknown, so every approver rule for the area applies."

Result: Awaiting approval (check: AWAITING APPROVAL)

Zof couldn't tell which environment the change goes to, so it doesn't fall back to the default approvers. The change needs the approvals of every environment rule its area has in Release approvers, each with its own approvers and count.

To unblock: Approve this PR as an authorized reviewer for the named teams.

Agents

accountable_human_unknown

On the check: "The agent author has no accountable human."

Result: Awaiting approval (check: AWAITING APPROVAL)

A bot or app opened or pushed this change, and no person is accountable for it. An approver listed in Release approvers for the change's owner takes it over by approving the pull request. The author never counts.

To unblock: Have a human take over the change.

agent_not_granted

On the check: "The agent author is not granted in the policy catalogue."

Result: Awaiting approval (check: AWAITING APPROVAL)

This agent has no grant in your release policy (the Agents tab in Release policies). An approver listed in Release approvers for the change's owner takes it over by approving the pull request, or an admin grants the agent.

To unblock: Have a human take over the change.

agent_permission_exceeded

On the check: "The agent author exceeds its grant."

Result: Awaiting approval (check: AWAITING APPROVAL)

The agent has a grant, but this change goes beyond it. Releases names what it exceeds (action, environment or tier); the check on GitHub doesn't. An approver listed in Release approvers for the change's owner takes it over by approving the pull request, or an admin widens the grant.

To unblock: Have a human take over the change.

Mapping and context

unmapped_files

On the check: "Some changed files don't belong to any service in your system map."

Result: Blocked (check: RELEASE BLOCKED: evidence missing)

Some changed files don't belong to any service Zof knows, so Zof can't tell what they touch. Open the repository’s System map and map those files to a service. When no required check failed, the check leads with this reason: it names up to three unmapped top-level folders and links to System map. A zof.yaml at the repository root also works.

To unblock: Add these files to a service in System map.

tags_unknown

On the check: "Some entities' tags are unknown, so a tag rule applied."

Result: none. This reason never blocks on its own.

Zof doesn't know a service's tags, so it applied the tag rules as if they matched. Those rules' requirements are what block.

change_not_found

On the check: "The change was not found in the system graph."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

The System Graph doesn't know this change yet. Zof decides again when the System Graph reports on it.

To unblock: Re-evaluate once the input is available.

context_unavailable

On the check: "The change context is unavailable."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

Zof couldn't get what this change touches. It re-evaluates when the context arrives.

To unblock: Re-evaluate once the input is available.

context_unparseable

On the check: "The change context could not be parsed."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

What Zof received about this change couldn't be read, so it isn't used.

To unblock: Re-evaluate once the input is available.

Zof could not read an input

verification_unavailable

On the check: "The verification result is unavailable."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

Zof couldn't reach Verification, or it didn't answer in time. Zof retries on its own.

To unblock: Re-evaluate once the input is available.

verification_unparseable

On the check: "The verification result could not be parsed."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

The verification result couldn't be read, so it isn't used.

To unblock: Re-evaluate once the input is available.

approvals_unavailable

On the check: "Approvals could not be loaded."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

Zof couldn't load the pull request's approvals. Re-evaluate in a minute.

To unblock: Re-evaluate once the input is available.

policy_not_published

On the check: "No release policy has been published."

Result: Blocked (check: No release policy yet)

To unblock: Publish a release policy.

A company admin must publish the first release policy. The GitHub check asks for action and links to Release policies. It cannot allow a pull request until a policy is published and served.

policy_unavailable

On the check: "Policy evaluation is unavailable."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

Zof couldn't evaluate your release policy. Re-evaluate in a minute.

To unblock: Re-evaluate once the input is available.

policy_result_invalid

On the check: "Policy evaluation returned an invalid result."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

The policy engine returned an answer Zof couldn't trust, so Zof didn't use it.

To unblock: Re-evaluate once the input is available.

policy_version_mismatch

On the check: "The policy engine runs an unexpected bundle version."

Result: Needs evidence (check: RELEASE BLOCKED: evidence missing)

The policy engine isn't running the policy version Zof expects. Zof retries about once a minute.

To unblock: Re-evaluate once the input is available.

Informational

advisory_rule_unmet

On the check: "An optional check didn't pass. It doesn't stop the release."

Result: none. This reason never blocks on its own.

An optional check didn't pass. The check shows it with the Optional tag, and it never stops the release.

head_superseded

On the check: "A newer commit replaced this one; the newest commit is evaluated."

Result: Denied (check: RELEASE DENIED)

A newer commit was pushed. Zof decides on the newest commit; nothing to do on this one. Zof doesn't put this reason in a decision today. It uses the code when it refuses work about a commit the pull request has moved past, such as a re-run of an old commit's check.

all_requirements_satisfied

On the check: "All required checks passed."

Result: Release authorized (check: RELEASE AUTHORIZED)

Every required check passed. On an enforced branch, the pull request may merge.

An older decision with this reason may not record a result for each check. Releases and a fix pull request's panel then name that policy decision ("Authorized by policy decision …, without per-check results") and leave this reason out, because the decision can't show which checks passed. Home and shared reports leave it out too. Home, shared reports, the Releases list and the pull request's page also leave it out when the decision can't be read or Zof hasn't allowed the change, and Home and the Releases list read Blocked, with "Check failed" as the reason, when an allowed change's check failed. The Policy decisions page in Admin shows every reason as it was recorded.