Checks and how a stage gates on them

You often want a task to wait at a stage until something is true — the tests pass, a reviewer approves, the work is deployed. In Cadence you express that with a check: a named pass/fail record kept on the task, and a rule that stops the task moving on until that check has passed. This page explains what a check is and how gating works, so the Checks reference and the guide Gate a stage with checks make sense.

What a check is

A check is a named assertion about a task — tests_pass, reviewed, deployed. You define the checks a space uses once, in the space's check registry; each one has a short code and an optional description.

Every task carries a result for a check, and a result is in one of three states:

• pending — the check exists on the task but has not been decided yet.
• passed — the assertion holds.
• failed — it does not.

A task has at most one result per check. Setting a result to passed is the thing that satisfies a gate; nothing else does.

How gating a stage works

A check rule ties a check to a stage. There are two kinds, and they do different jobs:

• A create rule puts a pending result for its check on the task when the task enters the stage. This is how a check appears on a task in the first place without anyone adding it by hand.
• A require rule gates the stage on its check: the task cannot enter the stage until that check has passed. A result that is missing, still pending, or failed holds the task out.

So the common shape is a create rule on the stage where the work happens, which raises a pending check, and a require rule on the next stage, which will not let the task in until that check passes. The task waits between the two until the check is decided.

Where two rules would apply to the same check on the same stage, the more specific one wins; rules for different checks add up, so a stage can gate on several checks at once, and every one of them must have passed for the task to enter.

What still needs you

The gate is automatic, but passing the check is not. Nothing in Cadence sets a check to passed on its own. A worker on the stage sets it when it finishes its work, or you set it yourself (see Checks). Until something sets it, a require gate holds the task at its current stage for as long as it takes — a check nobody ever passes holds the task there indefinitely.

This is the thing to be clear about before you rely on a gate: it will stop a task that should not move on, but it will not decide the check for you. If you expect a stage to release a task on its own, make sure something — a worker on that stage, or you — actually sets the check the gate reads.

For how a passed check can then advance the task with no one in the loop, and for everything else that moves a task automatically or waits for a person, read What moves a task without a person. To set up a gated stage end to end, follow Gate a stage with checks. For the exact tools, fields and refusals, see Checks and the check rules section of Stage rules.