The TrustRelay Check: Reference for Developers

A reference for the required check TrustRelay publishes on a pull request: the check name, the conclusion it reports in each operating mode, the reason codes you may see, and how an override is recorded.

This page is a reference for the check TrustRelay publishes on a pull request. It lists the fields the check carries, the GitHub conclusion it reports in each operating mode, the reason codes that can appear, and what an override does to the record. It is written for the developer working in the pull request, not for the administrator configuring policy.

For the decision logic behind the outcome, see the decision-engine explanation. For checking a signed record after the fact, see the offline verification guide.

The check on your pull request

TrustRelay publishes a single check run named TrustRelay. It is attached to the head commit of the revision that was evaluated, and it is published with status completed.

Field	Value	Notes
Name	`TrustRelay`	The check name branch protection matches on.
Status	`completed`	The check does not stay in progress; it reports a terminal conclusion.
External id	`trustrelay:<passport_id>`	Binds the check to the signed record for this decision.
Title	The decision outcome	`APPROVE`, `BLOCK`, or `ESCALATE`; `EXCEPTION GRANTED` when an override applied.
Summary	The mode and any safeguards	Names the operating mode, and any safeguard code that changed the conclusion.

If TrustRelay evaluates a new revision, it looks for an existing check run with the same external id and updates it rather than publishing a second check. You should never see two TrustRelay checks for one decision.

What the conclusion means

The GitHub conclusion is not the decision. It is the decision expressed as a merge gate, and the mapping depends on the operating mode the repository is in. This matters in shadow mode, where a decision can be reported without affecting merge eligibility.

Outcome	`shadow`	`advisory`	`limited_enforcement`
`APPROVE`	`neutral`	`success`	`success`
`BLOCK`	`action_required`	`failure`	`failure`
`ESCALATE`	`action_required`	`action_required`	`action_required`
Any outcome with a valid override	`success`	`success`	`success`

In shadow mode the check never reports success or failure. It reports neutral for an approval and action_required for anything else, so the decision is visible without becoming a merge gate. When you are ready to enforce, the same decision in advisory or limited_enforcement mode becomes a real conclusion.

Only success lets the pull request merge when the check is required. Every other conclusion keeps the merge blocked.

Safeguard codes that change the conclusion

Between the decision and the check publication, TrustRelay compares the state the decision was made against with the state at publication. If anything material changed, the conclusion is made more restrictive and a safeguard code is added to the summary. These codes appear in the check summary, not as decision reason codes.

Safeguard code	What changed	Effect
`check_mode_drift`	The operating mode changed between decision and publication.	The more restrictive of the two conclusions is used.
`check_policy_drift`	The policy version changed between decision and publication.	Forces `action_required` if the conclusion would be `success`.
`check_stale_revision`	The head commit is no longer the revision that was evaluated.	Forces `action_required` if the conclusion would be `success`.
`check_fork_source`	The pull request comes from a fork.	Forces `action_required` if the conclusion would be `success`.
`check_override_validation_unavailable`	An override was claimed but could not be validated.	The override is not honoured.

The stale-revision code is the one you are most likely to meet. Push a new commit and the check for the previous commit no longer applies to the head, so it will not report success until the new revision is evaluated. This is deliberate: a passing check for a commit you have since replaced is not evidence about the commit you are about to merge.

Reason codes in the decision

Every decision carries reason codes. The first is a system code that names the outcome, and the rest come from the rules that were evaluated.

System code	Outcome	Meaning
`SYS_DECISION_APPROVED`	`APPROVE`	Authorized by policy evaluation.
`SYS_DECISION_BLOCKED`	`BLOCK`	Blocked by a policy rule.
`SYS_DECISION_ESCALATED`	`ESCALATE`	Escalated for human review.

The rule-derived codes use the form <RESULT>_<RULE_ID>, where the result is the rule's outcome in upper case. A missing sponsor, for example, produces MISSING_SPONSORSHIP_REQUIRED, and conflicting attribution produces CONFLICTING_ATT_NO_CONFLICTING_PROVIDERS. The rule identifiers and their results are described in the decision-engine explanation.

Alongside those, the system defines a stable vocabulary of named codes for the conditions a decision can encounter. Because these are stable strings, a script or a policy report can match on them without parsing prose.

Named code	Meaning
`EVD_REQUIRED_MISSING`	Required evidence is missing.
`EVD_REQUIRED_INVALID`	Required evidence is invalid.
`EVD_REQUIRED_UNSUPPORTED`	The evidence workflow is unsupported.
`EVD_REQUIRED_UNAVAILABLE`	A required evidence source is unavailable.
`ATT_AGENT_UNKNOWN`	Agent involvement cannot be established; all commits are unknown.
`ATT_CONFLICTING_PROVIDERS`	Conflicting coding-agent providers were detected.
`ATT_LOW_CONFIDENCE`	Attribution confidence is below the policy threshold.
`ATT_SPONSORSHIP_MISSING`	No human sponsorship was established.
`POL_RULE_APPLICABILITY_UNKNOWN`	Policy rule applicability cannot be determined.
`POL_OVERRIDE_GRANTED`	An override was granted; the exception is permitted.
`POL_EMERGENCY_BYPASS`	An emergency bypass was activated.
`SYS_INPUT_SCHEMA_UNSUPPORTED`	The input schema major version is unsupported.
`SYS_CANONICALIZATION_UNSUPPORTED`	The canonicalization semantics are unsupported.

Remediating a block

A block names what is missing. The check summary tells you which rule produced the outcome, and the reason code names the condition. In practice a block resolves in one of three ways.

Provide the missing evidence. Link the work item, or make the check that the policy requires produce a result. The decision is re-evaluated when the evidence changes.

Record a human sponsor. If the change was agent-authored and no sponsor is recorded, name one. Sponsorship is what the engine uses to establish accountability for the change.

Resolve the attribution. If the agent provider cannot be established, or two providers disagree about what produced the change, the attribution has to be settled before the change can be approved on evidence.

If none of those is the right answer for this change, an authorized reviewer can override, which is described next.

How an override is recorded

An override is an exception, and it is recorded as one. It is bound to a specific revision, it names who granted it and why, and it carries an expiry. The original decision is never rewritten.

Property	Behaviour
Bound to a SHA	The override applies to the revision it was granted for.
Expires	An override past its expiry is treated as inactive.
Superseded by a new SHA	Pushing a new commit makes a prior override ineffective.
Attributed	The grant records the actor, the reason, and an optional ticket reference.
Additive	The override is stored as a supplement to the passport, not a change to the decision.

When a valid override applies, the check reports success with the title EXCEPTION GRANTED, so the exception is visible in the pull request rather than hidden. The decision that produced the original BLOCK or ESCALATE remains in the record, alongside the override that superseded it.

If you push a new commit after an override was granted, the override no longer applies to the head revision. That is the same stale-revision rule as above, and it is why an override is not a way to make a check pass permanently.

What the check does not tell you

The check reports a decision and the reason for it. It does not report whether the policy is the right policy, whether the evidence was complete when it was collected, or whether the change is a good idea. A success conclusion means the change satisfied the policy that was in force, evaluated against the evidence that was available. Everything about whether that policy and that evidence were adequate belongs to the people who configured them.