Skip to main content
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.

​
Gate types

Timeouts use Go duration syntax: 30m, 1h, 24h (there is no d unit — write 24h, not 1d). GitHub gates use the current Git repository by default. To evaluate a PR or workflow run in another repository, set the gate’s string metadata.repo value to OWNER/REPO or HOST/OWNER/REPO. An ad-hoc gh:run/gh:pr gate created with bd gate create inherits a valid metadata.repo value from the issue it blocks; human/timer/bead gates do not, since metadata.repo is unrelated, ordinary metadata for those types. bd gate check rejects malformed repository values instead of falling back to the current repository.

​
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 five fields: type, id, await_id, timeout, and repo. This is the release gate from beads’ own release formula — the step that waits for the GitHub release workflow:
For a gh:run or gh:pr gate that watches another repository, set repo the same way a metadata.repo value works for an ad-hoc gate — OWNER/REPO or HOST/OWNER/REPO. Malformed values are rejected when the gate is checked:
repo accepts a {{var}} placeholder (e.g. repo = "{{gate_repo}}"); for a formula persisted with bd cook --persist, the placeholder is substituted when the proto is later poured with bd mol pour --var gate_repo=..., the same as title, description, and await_id. bd gate discover (auto-discovery of a gh:run gate’s run ID) requires a workflow name hint (await_id/id, not left blank) for a gate targeting another repository — without one, the local commit/branch heuristics that narrow a same-repo match don’t apply across repos, so nothing but the workflow name can identify the right run. A cross-repo gate discovery also ignores the local checkout’s branch unless --branch is passed explicitly; an auto-detected local branch has no relationship to the target repo’s branches. A human sign-off gate:
And a cooling-off timer:
Verify what the parser actually understood before pouring — unknown keys in TOML are dropped silently:

​
Creating gates outside formulas

bd gate create attaches a gate to existing work:

​
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:

​
Working with gated molecules

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.