Gates and failure handling
Gates stop a workflow until a check passes: CI green, QA, review, judgment, fact checks and user approval, plus where a run returns when a gate fails.
On this page
A gate is a condition on a step. When the step finishes, the gate must pass before anything after it runs. If it fails, the run can go back to an earlier step and try again, start that step fresh, or stop and ask a person. Gates are how a workflow says “don’t open the PR until CI is green” or “a person approves the plan before any code is written”.
Any step can have a gate. Check steps always have one, and Human steps default to User approval.
Gate types
| Gate | YAML type | What happens | Needs |
|---|---|---|---|
| No gate | none | The next step starts as soon as this one finishes. | — |
| Judgment | judgment | An agent judges the result before the workflow moves on. | Criteria |
| User approval | user_approval | A person approves before anything after this step runs. | — |
| CI green | ci_green | CI must be green before anything after this step runs. | Command |
| Review check | review_check | Review must pass before anything after this step runs. | — |
| QA check | qa_check | QA must pass before anything after this step runs. | Command |
| Fact check | fact | A recorded fact must hold before the workflow moves on. | Criteria |
In a run, a step behind a gate shows what it’s waiting for: “Wait for CI to pass”, “Wait for your approval”, “Wait for the review to pass”, “Wait for QA to pass”, “Wait for the judgment check to pass” or “Wait for the check to pass”.
Criteria and commands
- Judgment and Fact check need criteria: a plain description of what the check should look for. Without it you see ““Judgment check before review”: say what the judgment should look for.”
- CI green and QA check need a command, such as
pnpm ciorpnpm e2e. Without it: ““CI checks”: which command should the check run?” The command runs in the run’s sandbox, under the same command rules as any other command.
Good judgment criteria are testable. Compare:
| Weak | Strong |
|---|---|
| “The code is good.” | “The diff does what the plan says, and tests cover every changed branch.” |
| “No security issues.” | “No unmitigated auth, secret or injection risk in the diff.” |
On fail
When a gate fails, the On fail block decides what happens next.
| Field | YAML | What it does |
|---|---|---|
| Return to | on_fail.return_to | An earlier step to go back to. It must run before this one |
| Policy | on_fail.policy | How to go back (below) |
| Max attempts | on_fail.max_attempts | How many times to try before the step fails |
Policies:
| Policy | YAML | Behaviour |
|---|---|---|
| Retry with feedback | retry_with_feedback | Send the failure back as context and try again |
| Start fresh | redispatch | Re-run the return step from a clean slate |
| Escalate | escalate | Stop and ask a person |
Each return counts as an attempt. The run shows attempt N on the step. When the attempts run out, the step fails and so does the run, and you get a run.failed webhook event and a notification if you’ve turned on “A run fails after retries”.
The graph draws an On fail return as a dashed edge back to its target.
- id: review
kind: check
name: Judgment check before review
owner: { kind: orchestrator }
instructions: Check the diff matches the plan and the tests cover it before a person looks.
gate:
type: judgment
criteria: The diff does what the plan says, and tests cover every changed branch.
on_fail:
return_to: implement
policy: retry_with_feedback
max_attempts: 2Rules for return targets
The return step must still run before the gated step. If you reorder or turn off steps so that’s no longer true, the editor shows ““CI checks” returns to “Implement” on failure, which no longer runs before it.” and you can’t apply until you pick another target.
You also can’t delete a step that another step returns to: “Choose another failure return for “CI checks” before deleting this step.”
Approvals as gates
A User approval gate creates an ask in the Inbox when the run reaches it. The person who approves depends on the step’s owner (Issue owner, CODEOWNERS, Project lead or Anyone on the project). Request changes counts as a failed gate and follows On fail: with Retry with feedback, the note goes back to the return step as context.
Gates versus Decide
A gate answers “may the run continue?”. A Decide step answers “which way should it go?”. If a failure should lead somewhere other than back (for example, open a draft PR and notify a person instead of retrying), use a Decide step after the check with outcomes like All checks succeeded and an Otherwise branch.
In test runs
In a test run, gates behave as they do in real runs. User approval gates and Human steps wait for you in the test transcript with Approve and Send back; Send back follows On fail with the attempt count increased. In a dry run, CI checks are simulated and pass most of the time, so you can see a return path exercised.