* fix(formula): substitute vars in step assignee, labels, and metadata
Cook and pour substituted title/description/notes/gate but copied
assignee, labels, and metadata through raw, so a poured bead carried
literal `{{var}}` text in all three.
- labels: every label-based query, filter, and automation silently stops
matching, and nothing errors (GH#5110).
- metadata: general keys came through literal; only a top-level "repo"
key on a gh:* gate was substituted (GH#5110).
- assignee: worse than cosmetic - close refuses when the actor doesn't
match the assignee, so every step of a poured molecule is unclosable
and the molecule can never advance (GH#5754).
internal/formula/expand.go already substituted assignee and labels on
the inline-expansion path, so the two paths disagreed on the same
fields; Step.Assignee is documented as "supports substitution" and
ExtractVariables already scanned it, meaning pour hard-failed demanding
a variable it then refused to resolve.
Both call sites are fixed together: runtime-mode cook feeds the proto
that pour clones, so a field left literal in either path ships a
placeholder onto the bead. Fixing cloneSubgraphInto covers pour, wisp,
bond, and the proxied-server paths, which all funnel through it.
substituteMetadataRepo is generalized to substituteMetadataVars, which
resolves every string leaf of the metadata JSON at any depth. This drops
the earlier gh:*-gate-only restriction (SF2/SF4): reading a `repo` key
AS a GitHub selector is only correct on a gh:* gate, but resolving a
{{var}} in it interprets the key not at all. The walk still decodes into
json.RawMessage, so untouched values stay byte-identical, and object
keys are never rewritten (a rewritten key could collide with a sibling).
The variable scan is widened to match: extractAllVariables (pour) and
ExtractVariables (cook) now cover assignee, labels, metadata strings,
notes, and await ID, so pour demands exactly the variables it resolves.
Undeclared handlebars are still filtered out by VarDefs.
Regression coverage asserts on a poured bead, and checks the assignee
via validation.AssigneeMatches rather than a string compare - a
substitution-only assertion would pass while the unclosable symptom
persisted.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* chore(formula): regenerate schema_gen.go after the types.go doc edits
TestSchemaGenIsCurrent holds schema_gen.go to a byte-for-byte rerun of
the generator over types.go, and the field docs are part of the
generated output — so the Labels/Metadata comment updates made it stale.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(mol bond): resolve vars like pour instead of demanding every handlebar
buildAttachCloneOpts demanded every variable extractAllVariables found in
the proto subgraph and applied no declared defaults, unlike pour
(cmd/bd/pour.go) and wisp (cmd/bd/wisp.go). Widening the scanned field set
to assignee, labels and metadata therefore widened bond's hard refusal
along with it: a proto whose label or metadata carried an undeclared
documentation handlebar, or a declared var carrying only a default, made
`bd mol bond` fail with "missing required variables" where it previously
succeeded.
Run applyVariableDefaults + extractRequiredVariables there, matching the
sibling call sites. extractRequiredVariables returns the unfiltered list
when VarDefs is nil, so a legacy template still requires every var it
mentions; the change is strictly a reduction in false failures. Applying
the defaults also puts them in opts.Vars, which is the map
cloneSubgraphInto actually substitutes from.
Also from review:
- docs/workflows/gates.md no longer enumerates a stale three-field list for
where `{{var}}` substitution applies.
- maxMetadataSubstitutionDepth's doc names walkJSONStrings (not the
long-gone substituteJSONVars) and says plainly that hitting the bound
deliberately ships a literal placeholder rather than erroring.
Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* build(bazel): add the validation dep to the bd_test go_test (make bazel-sync)
mol_embedded_test.go and template_test.go now import internal/validation
directly (validation.AssigneeMatches, to check the substituted step
assignee), so gazelle emits //internal/validation on bd_test. bd_lib
already carries the dep, so bd_test compiles through embed, but gazelle
lists every direct test import on the go_test itself. cmd/bd/BUILD.bazel
landed on main after this PR branched, so the PR could not carry the
line; without it, bazel.yml's "BUILD files in sync" step fails in the
required Bazel / test lane. Generated by `make bazel-sync`.
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 Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
208 lines
7.6 KiB
Markdown
208 lines
7.6 KiB
Markdown
---
|
|
title: Gates
|
|
description: 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.
|
|
|
|
```bash
|
|
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` 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.
|
|
|
|
### Known limitations: multi-rig and proxied-server topologies
|
|
|
|
Bead gates and prefix routing (`routes.jsonl`) do not work in every
|
|
topology. Three limitations to expect, all tracked in
|
|
[#5861](https://github.com/gastownhall/beads/issues/5861):
|
|
|
|
- **Cross-rig bead gates never resolve on their own.** A `<rig>:<bead-id>`
|
|
await value reports `cannot be checked (multi-rig routing removed)` and
|
|
stays pending regardless of the awaited bead's status. Close it with
|
|
`bd gate resolve`.
|
|
- **`bd close` cannot verify a bead gate in the experimental proxied-server
|
|
mode.** Proxied-server commands never open a local store, so closing the
|
|
gate refuses with `no local store available` even when the awaited bead is
|
|
closed. Run `bd gate check`, which evaluates bead gates in proxied-server
|
|
mode and closes the satisfied ones, or `bd close --force`.
|
|
- **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:
|
|
|
|
```toml
|
|
[[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:
|
|
|
|
```toml
|
|
[[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:
|
|
|
|
```toml
|
|
[[steps]]
|
|
id = "approve-deploy"
|
|
title = "Human approves the deploy"
|
|
|
|
[steps.gate]
|
|
type = "human"
|
|
```
|
|
|
|
And a cooling-off timer:
|
|
|
|
```toml
|
|
[[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:
|
|
|
|
```bash
|
|
bd formula show <formula> --json # inspect the parsed gate blocks
|
|
```
|
|
|
|
## Creating gates outside formulas
|
|
|
|
`bd gate create` attaches a gate to existing work:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```toml
|
|
[[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
|
|
|
|
```bash
|
|
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.
|