Adversarial review falsified this page: 10 of its 12 checkable claims contradicted the binary. It taught a phantom TOML gate schema (approvers, require_all, duration, event, status, action, merged — all silently dropped by the parser), phantom subcommands (bd gate approve/skip), a nonexistent pending/open/closed state model, list-valued waits_for, and 7d durations that time.ParseDuration rejects. Rewritten from source: the four-field [steps.gate] schema (type/id/await_id/timeout per internal/formula/types.go), the real subcommand set (list/create/show/resolve/check/add-waiter), gate types with their closers (human resolves manually; timer and gh:* close via bd gate check; bead gates currently unresolvable — multi-rig routing removed), needs vs waits_for fan-in semantics, and a worked example taken from beads' own release formula. Closure: every TOML construct on the page round-trips intact through bd formula show --json (gh:run/human/timer gates, needs, waits_for).
4.2 KiB
| title | description |
|---|---|
| Gates | Async wait conditions that park a workflow step until the world catches up — a human decision, a timer, or a GitHub run or PR. |
Some workflow steps can't proceed on code alone: a release needs CI to go green, a deploy needs a human sign-off, a cleanup should wait 24 hours. A gate is an issue that represents that wait. It blocks a step the same way any blocker does — the step leaves the ready frontier until the gate closes — so agents never need to poll or spin.
How a gate works
A gate is a bead like any other: created open, it blocks its waiters through a normal dependency edge, and the step becomes ready the moment the gate closes. Gates close in one of two ways:
- Manually —
bd gate resolve <gate-id>(human gates always close this way). - Via
bd gate check— evaluates open timer and GitHub gates against the real world and closes the ones whose condition is met.
bd gate list # open gates
bd gate list --all # include closed
bd gate show <gate-id> # details and waiters
bd gate check # evaluate open gates, close satisfied ones
bd gate check --dry-run # report without closing
bd gate resolve <gate-id> # close a gate manually
Gate types
| Type | Waits for | Closed by |
|---|---|---|
human |
a person's decision | bd gate resolve only |
timer |
a duration after gate creation | bd gate check once the timeout elapses |
gh:run |
a GitHub Actions workflow to complete successfully | bd gate check (uses gh run view) |
gh:pr |
a pull request to merge | bd gate check (uses gh pr view) |
bead |
a bead in another rig to close | currently unresolvable — multi-rig routing was removed, so bd gate check reports these gates as uncheckable |
Timeouts use Go duration syntax: 30m, 1h, 24h (there is no d unit —
write 24h, not 1d).
Gates in formulas
A formula step declares a gate with a [steps.gate] block. When the formula
is instantiated, bd creates the gate issue and wires it as a blocker of that
step. The schema has four fields: type, id, await_id, and timeout.
This is the release gate from beads' own release formula — the step that waits for the GitHub release workflow:
[[steps]]
id = "wait-for-ci"
title = "Wait for release workflow"
[steps.gate]
type = "gh:run"
id = "release.yml" # which workflow to watch
timeout = "30m" # escalate if it takes longer
A human sign-off gate:
[[steps]]
id = "approve-deploy"
title = "Human approves the deploy"
[steps.gate]
type = "human"
And a cooling-off timer:
[[steps]]
id = "wait-24h"
title = "Let the release bake"
[steps.gate]
type = "timer"
timeout = "24h"
Verify what the parser actually understood before pouring — unknown keys in TOML are dropped silently:
bd formula show <formula> --json # inspect the parsed gate blocks
Creating gates outside formulas
bd gate create attaches a gate to existing work:
# Block bd-abc until a PR merges
bd gate create --type=gh:pr --blocks bd-abc --await-id=42
# Block bd-abc until a human resolves the gate
bd gate create --type=human --blocks bd-abc --reason "Design sign-off"
# Add another waiter to an existing gate
bd gate add-waiter <gate-id> <issue-id>
Fan-in: waiting on other steps
Waiting on other steps is not a gate — it's a dependency. Use needs to
fan in on named steps, and waits_for when a step must wait for
dynamically-created children:
[[steps]]
id = "merge-results"
title = "Merge results"
needs = ["test-a", "test-b"] # fan-in on named steps
[[steps]]
id = "summarize"
title = "Summarize all spawned work"
waits_for = "all-children" # or "any-children", or "children-of(step-id)"
Working with gated molecules
bd ready --gated # molecules where a gate just closed (ready to resume)
bd blocked # what's waiting, and on which gates
Automation patterns: run bd gate check on a schedule (cron, CI, or an
orchestrator loop) so timer and GitHub gates close without a human in the
loop; keep human gates for the decisions that should never auto-close.