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

GateYAML typeWhat happensNeeds
No gatenoneThe next step starts as soon as this one finishes.—
JudgmentjudgmentAn agent judges the result before the workflow moves on.Criteria
User approvaluser_approvalA person approves before anything after this step runs.—
CI greenci_greenCI must be green before anything after this step runs.Command
Review checkreview_checkReview must pass before anything after this step runs.—
QA checkqa_checkQA must pass before anything after this step runs.Command
Fact checkfactA 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 ci or pnpm 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:

WeakStrong
“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.

FieldYAMLWhat it does
Return toon_fail.return_toAn earlier step to go back to. It must run before this one
Policyon_fail.policyHow to go back (below)
Max attemptson_fail.max_attemptsHow many times to try before the step fails

Policies:

PolicyYAMLBehaviour
Retry with feedbackretry_with_feedbackSend the failure back as context and try again
Start freshredispatchRe-run the return step from a clean slate
EscalateescalateStop 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: 2

Rules 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.

    Type to search the docs, help center and blog.