* feat(gate): bd gate create --repo names the repository a gh:run/gh:pr gate is checked in
A gh:pr gate for a PR in another repository could only be pointed there
through the blocked issue's metadata.repo; with none, `bd gate check`
resolved the bare number against the current repository and escalated
"pull request not found" on every check, with nothing in the text saying
which repository it had looked in. Five gates armed that way on 2026-10-03
never released after their PRs merged.
- `--repo OWNER/REPO` (or HOST/OWNER/REPO) on `bd gate create`: an
explicit value wins over the inherited one; it goes through the same
validator as metadata.repo (now `validateGitHubRepo`, split out of
`githubRepoFromIssue`); it is refused on human/timer/bead gates, where
nothing would read it. Both create routes call one helper,
`gateMetadataForCreate`, so the flag cannot drift between them.
- The gh:pr not-found escalation reason names the repository the number
was resolved against ("pull request not found: #42 in owner/repo" or
"... in the current repository").
- Help text, docs/workflows/gates.md and the plugin's ASYNC_GATES.md say
when the flag is needed. docs/cli-reference is pinned to the release
and regenerates on its own.
Tests: TestGateMetadataForCreateExplicitRepo, TestCheckGHPRNotFoundNamesTheRepository
(unit); TestEmbeddedGateCreate/create_gate_with_repo + /repo_flag_on_human_gate_is_refused
(embedded); TestProxiedServerGateCreateInheritsRepoMetadata/explicit_repo_flag_wins_over_inherited
(proxied).
Refs ghosttrack/wyvern wy-2jh4v5.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(gate): keep the create --repo workspace bypass off bd gate create
The root pre-run bypass for `bd create --repo` (GH#3686) matched the leaf
name "create", so `bd gate create --repo` outside a workspace took it: an
OWNER/REPO slug opened a stray ./OWNER/REPO/.beads workspace under the cwd
and failed with "issue not found", and an https:// URL skipped store wiring
and panicked on the nil store. Key the bypass on the command path, as
proxy_capability.go already does; gate create now fails with "no beads
database found" outside a workspace like every other command, and top-level
create --repo (local path and remote URL) still takes the bypass.
Also name the repository in the gh:run not-found escalation, as the gh:pr
one already does. Only stderr with a lowercase "not found" reaches that
arm: real gh reports a missing run as "HTTP 404: Not Found (<api url>)",
which takes the existing error path, and that URL already names the
repository. The match stays case-sensitive because a token without access
to the repository gets the same 404.
Tests: TestEmbeddedCreateRepoFromNonBeadsCwd/gate_create_repo_flag_is_not_a_workspace
(slug and URL forms, built binary run from an empty cwd) and the
cross_repo/current_repo subtests of TestCheckGHRunNotFoundNamesTheRepository
fail with the fixes reverted. Its real_gh_404_names_the_repository subtest
feeds gh's real 404 stderr and fails if the match is widened.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
7.7 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, GitHub, and bead 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 to close — a plain ID names a bead in this rig, the cross-rig form is <rig>:<bead-id> |
bd gate check for plain local IDs; cross-rig values cannot be checked — resolve those manually |
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 takes that value from --repo, or, without the flag,
inherits a valid metadata.repo value from the issue it blocks;
human/timer/bead gates do neither (--repo is refused on them), 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, and when a PR number does not resolve, the escalation names the
repository it was looked up in. A gate for a PR in another repository whose
blocked issue carries no metadata.repo needs --repo: without it the number
is looked up in the current repository and escalates as not found on every
check.
bd gate create --type=gh:pr --blocks bd-abc --await-id=42 --repo=owner/other-repo
Known limitations: multi-rig and proxied-server topologies
Bead gates and prefix routing (routes.jsonl) do not work in every
topology. Two limitations to expect, both tracked in
#5861:
- Cross-rig bead gates never resolve on their own. A
<rig>:<bead-id>await value reportscannot be checked (multi-rig routing removed)and stays pending regardless of the awaited bead's status. Close it withbd gate resolve. - Prefix routing cannot open a proxied-server target rig. A routed
lookup into a rig that is itself in proxied-server mode fails with
proxy server store needs to be uow provider, so an all-proxied shared-server topology cannot resolve routed targets at all.
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:
[[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
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:
[[steps]]
id = "wait-for-downstream"
title = "Wait for downstream release"
[steps.gate]
type = "gh:run"
id = "release.yml"
repo = "org/downstream-repo" # check gh:run against this repo, not the current one
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 every other var-bearing step field (title, description, design,
acceptance_criteria, notes, assignee, labels, await_id, and the
string values inside metadata).
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:
[[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 = "fan-out"
title = "Spawn a worker per shard"
[[steps]]
id = "summarize"
title = "Summarize all spawned work"
needs = ["fan-out"] # the spawner whose children to wait for
waits_for = "all-children" # or "any-children", or "children-of(fan-out)"
all-children and any-children wait for the children of needs[0], so a step
using them must declare needs; children-of(step-id) names the spawner itself
and does not. A bare gate with neither is rejected when the formula is cooked,
because it would wait for no one.
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.