* ci(bazel): remote Bazel lanes for allowlisted fork authors (advisory) Add bazel-farm.yml, a pull_request_target caller of bazel.yml. It gives the RBE farm to fork PRs to main whose author and triggering user (sender: the pusher on synchronize) are both on .github/bazel-farm-allowlist.txt, which is read from the base commit. The list has julianknutsen, quad341, sjarmak and csells, the same as gascity's blacksmith allowlist. - authorize job: sparse checkout of github.sha that holds only the allowlist and .github/scripts/bazel-farm-authorize.sh; no token on disk, no secrets, event facts through env only. The script also checks fork vs base repo, the default branch, the action, and a 40-hex head SHA. - farm job: calls bazel.yml with contents: read, exactly the four RBE secrets, checkout-sha pinned to the event's head SHA, and fork-farm: authorized. - bazel.yml: new checkout-sha and fork-farm inputs (no-ops for pr.yml and nightly.yml). Every lane checks out inputs.checkout-sha with persist-credentials: false. The rbe job runs a fork remotely only for an authorized pull_request_target call, and then remote or skip, never local. PR concurrency also cancels on pull_request_target. The bazel-sync-patch upload is skipped on pull_request_target. Advisory only: pr.yml is unchanged, so every fork PR still runs the local Bazel lanes inside the enforced CI Gate / Required. Policy tests pin the trigger and types, both jobs' conditions, the allowlist source and contents, the pinned checkout, read-only permissions, where secrets appear, no expressions in run scripts, per-PR concurrency, the timeout, and that no workflow_run consumer can pick up a farm run. TestBazelLaneIsGatedAlongsideLegacy now allows pull_request_target on a bazel.yml caller for bazel-farm.yml only. 26 mutations were each caught by these tests (sender check dropped, allowlist read from the PR head, write permission added, event data interpolated into run, SHA pin dropped, and others). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * docs(ci): trusted-author fork PR farm design and threat model Document bazel-farm.yml in the required-check topology: - the design, and why it is advisory rather than part of the enforced gate; - the gate options considered; - the threat model: allowlist spoofing, sender vs. author, TOCTOU with the pinned SHA, workflow-file edits, script, label and comment injection, token scope, artifact poisoning, and farm and Actions cache poisoning; - what can only be verified on GitHub. The one capability a listed author gets beyond a same-repo PR is called out as an accepted risk, with mitigations: pull_request_target runs use the default branch's Actions cache scope. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(ci): opt the farm's lane checkouts into fork-head checkout (F1) actions/checkout@3d3c42e5 is v7.0.1, not v6, and v7 refuses to check out a fork PR's head SHA on pull_request_target unless allow-unsafe-pr-checkout is true. Every lane of an authorized farm run therefore failed at checkout. - Each bazel.yml lane checkout now sets allow-unsafe-pr-checkout to inputs.fork-farm == 'authorized' && github.event_name == 'pull_request_target'. That is false for every other caller and event. - TestBazelWorkflowForkFarmInputs pins that exact expression. It also fails if the key appears anywhere else in the workflows (so never a literal true, and never on the authorize checkout). - Relabel the checkout pin as # v7.0.1 in bazel.yml and bazel-farm.yml. - Add the opt-in to the engdoc's design section and to the verify-on-GitHub list. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(ci): verify everything restored from caches in Bazel lanes (F3) A farm run executes PR code in the default branch's cache scope. GitHub's own cache is read-only for pull_request_target: GitHub issues a read-only token, and cache-mode defaults to read. Whether Blacksmith's colocated cache enforces the same is unverified. So trusted runs no longer execute anything they restore without verifying it first: - setup-bazel: Bazelisk's home moves out of the runner cache to a fresh $RUNNER_TEMP/bazelisk-home, so the Bazel binary is never restored from a cache. BAZELISK_VERIFY_SHA256 is set to the release sha256 pinned for the .bazelversion version on each arch (9.2.0 amd64 and arm64). The wrapper step then re-checks every Bazel binary in that home. - write-bazelrc.sh: add common --repo_contents_cache=. The repo contents cache holds extracted repos that Bazel never re-verifies. The content-addressable repository cache stays, since Bazel re-hashes it on every hit. - Runner cache key bumped to bazel-repo-v3 (the content changed). - bazel-test runs `go mod verify` right after the Go module cache restore. - Policy tests: - cache-mode may only be read or none in bazel-farm.yml, bazel.yml and setup-bazel; - bazel.yml permissions are exactly contents: read; - the Bazel sha pin matches .bazelversion, and Bazelisk's home is outside the cache; - the binary is verified after download; - go mod verify follows every module cache restore; - the rc disables the repo contents cache. - Engdoc and bazel-farm.yml header: corrected about GitHub's read-only cache, noted Blacksmith as unknown, and listed the full blast radius (release.yml hardening tracked separately). The canary design is in the rollout notes. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(ci): farm runs only the author's own fork, on opened/synchronize (F4) "The sender is listed" did not prove that a listed user chose the head commit: - A listed author could open a PR whose head is a third party's fork, and that fork's owner could push between the author's review and "Create". - A collaborator on a listed author's fork could push while the PR was closed or a draft (that push is skipped), and the author's later "Reopen" or "Ready for review" click would run it with secrets. Changes: - The authorize script requires the head repository owner's numeric id to equal the PR author's (HEAD_OWNER_ID, PR_AUTHOR_ID, passed via env). - Drop the reopened and ready_for_review triggers, and the script now refuses those actions too. Drafts already run on opened and synchronize. - Tests pin the trigger types and the new env, and add script cases: - cross-fork head, missing or non-numeric owner id; - reopened and ready_for_review refused; - unanchored action (xopenedx); - base-repo prefix (gastownhall/beads-evil). This covers two mutations the reviewer found surviving. - Engdoc: the new checks, and the residual that stays the listed author's responsibility (commits pushed by fork collaborators). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(ci): match the farm allowlist on numeric user ids (F5) Logins are mutable: after a rename, anyone can register the old login, and before this change they would then be listed as both author and sender. - The allowlist now holds one numeric user id per line, with the login as a comment. The ids were looked up with gh api users/<login> --jq .id. - The authorize script matches PR_AUTHOR_ID and SENDER_ID (github.event.pull_request.user.id, github.event.sender.id). Logins are now used only in the log. An allowlist entry that is not a numeric id fails the job. - Tests pin the id-to-login table and the SENDER_ID env. Script cases: - a renamed login re-registered with a new id (author and sender); - id prefix, suffix and leading zero; - an id that appears only in a comment; - listed ids with unlisted logins; - a PR from another listed user's fork; - broken allowlists (a login entry, a signed id). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * docs(ci): farm re-run semantics and the add/remove-user procedure (F6) A re-run replays the original event. It checks out the same pinned head SHA, which is fine. It also reads the allowlist at the original base commit, so a user removed from the list still gets the RBE secrets when one of their old runs is re-run. Only users with write access can re-run. - Engdoc: how to add a user. - Engdoc: how to remove a user. Merge the removal, then cancel and delete their farm runs (a gh api query by head-repository owner id). For cause, rotate RBE_TLS_CERT/KEY and have the farm revoke the old certificate; rotating also closes the re-run window. - bazel-farm.yml header: points to the procedure. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(ci): name the farm call "Bazel Farm", not "Bazel" (F7) The farm's check runs were named "Bazel / <lane>", the same as pr.yml's. Farm results are PR-controlled: PR code runs setup-bazel and can make a lane exit 0. If a ruleset ever required a "Bazel / ..." check, a farm run could satisfy it. The farm's checks are now "Bazel Farm / <lane>", and a test pins the name and requires it to differ from pr.yml's bazel job. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(ci): run the farm authorize script in the C locale (F8) Bash bracket ranges and ${v,,} depend on the locale. In en_US.UTF-8, [0-9], [0-9a-f] and [A-Za-z] match some non-ASCII characters, and the Kelvin sign lowercases to "k". This is not exploitable (GitHub ids, logins and SHAs are ASCII, and the allowlist is maintainer-controlled), but the script now exports LC_ALL=C. The script tests now run under en_US.UTF-8 and add cases with non-ASCII digits in ids and a non-ASCII character in the SHA. Without the export, the SHA case fails, so the tests catch its removal. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(ci): farm authorize script runs on bash 3.2 (macOS) ${v,,} is bash >= 4; macOS runners' /bin/bash is 3.2, so the script's tests failed there. Lowercase with tr under LC_ALL=C (ASCII only, as before). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local> Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| bench-ready-indexes | ||
| ci | ||
| gitattributespolicy | ||
| hooks | ||
| migration-test | ||
| prlintmake | ||
| repro-be-1he-slow-path | ||
| repro-dolt-hang | ||
| repro-dolt-prod-timeouts | ||
| bazel-autofix-push.sh | ||
| bazel_autofix_push_test.go | ||
| bazel_farm_workflow_test.go | ||
| bazel_policy_test.go | ||
| build-examples.sh | ||
| BUILD.bazel | ||
| bump-version.sh | ||
| check-build-tags.sh | ||
| check-cli-docs-drift.sh | ||
| check-doc-flags.sh | ||
| check-doc-freshness.sh | ||
| check-go-install-guidance.sh | ||
| check-migration-hygiene.sh | ||
| check-testing-short.sh | ||
| check-versions.sh | ||
| check_build_tags_test.go | ||
| check_doc_freshness_test.go | ||
| check_testing_short_test.go | ||
| ci_capability_selector_test.go | ||
| ci_workflow_apt_get_timeout_test.go | ||
| ci_workflow_test.go | ||
| clean-test-tmp.sh | ||
| complexity_script_test.go | ||
| conformance.sh | ||
| conformance_script_test.go | ||
| cross-version-smoke-test.sh | ||
| docs-autofix-push.sh | ||
| docs.md | ||
| gen-winres.sh | ||
| generate-cli-docs.sh | ||
| generate-newsletter.py | ||
| generate-newsletter_README.md | ||
| gh-body-lint | ||
| host_tools_test.go | ||
| install-hooks.sh | ||
| install.sh | ||
| install_dolt_test.go | ||
| migrate-jsonl-to-dolt.sh | ||
| migrate-legacy-to-current.sh | ||
| mutation-equivalence.sh | ||
| pr-preflight.sh | ||
| pr_preflight_test.go | ||
| pull_dolt_image_test.go | ||
| README.md | ||
| release.sh | ||
| release_script_test.go | ||
| resolve-docs-bd.sh | ||
| sign-windows.sh | ||
| test-cgo.sh | ||
| test-git-remote.sh | ||
| test-icu-path.sh | ||
| test.sh | ||
| test_script_test.go | ||
| update-nix-vendorhash.sh | ||
| update-versions.sh | ||
| update-winget.sh | ||
| upgrade-smoke-test.sh | ||
| upgrade_smoke_loop_test.go | ||
| verify-cgo.sh | ||
Beads Scripts
Utility scripts for maintaining the beads project.
ci/
Repository-owned CI command wrappers. These scripts are the source of truth for the target CI tiers; Make targets are aliases for local discoverability.
make ci-pr-core
make ci-pr-policy
make ci-pr-lint
make ci-package-mcp
make ci-package-npm
Each wrapper auto-detects the repository root, sources .buildflags when it
invokes Go in the default build mode, and records per-command timing through
scripts/ci/lib/timing.sh.
Broad Go test wrappers also source scripts/ci/lib/test-env.sh, which creates a
temporary HOME/XDG/Dolt root, isolates Git global/system config, clears runtime
Beads/Dolt environment variables, and sets BEADS_TEST_SKIP=dolt before tests
run. This keeps local make test and make ci-pr-core results comparable to
the fast PR-core contract even on shared agent hosts. Set
BEADS_TEST_ENV_RUN_DOLT=1 only when intentionally running the Dolt-dependent
tests through these broad wrappers, or BEADS_TEST_ENV_DISABLE=1 when debugging
against your real local configuration.
The broad Go wrappers also cap package and test parallelism to 4 by default
(GO_TEST_PKG_PARALLEL and GO_TEST_PARALLEL). This avoids turning high-core
shared hosts into a different test topology than GitHub Actions.
make ci-pr-policy includes scripts/check-testing-short.sh, which enforces
that testing.Short() is only used for runtime, stress, or large-fixture skips.
Use build tags, environment checks, or named wrappers for integration/e2e/API
boundaries.
Package gate wrappers validate publishable/package-adjacent surfaces:
make ci-package-mcpbuilds or consumes abdbinary, puts it onPATHasbd, then runs locked MCP packageuv sync, Ruff, mypy, pytest, and build checks.make ci-package-npmbuilds or consumes the native binary expected bynpm-package/bin/bd, runs the npm package test suite, and checksnpm pack --dry-run.
Set BEADS_TEST_BD_BINARY=/path/to/bd for MCP and npm package gates to reuse a
prebuilt candidate binary instead of rebuilding it inside the wrapper.
pr-preflight.sh
Read-only PR safety check for agents and maintainers.
# Before implementing or opening a related PR
./scripts/pr-preflight.sh --search "topic keywords" --repo gastownhall/beads
# Before changing, closing, or merging an existing PR
./scripts/pr-preflight.sh 123 --repo gastownhall/beads
It reports contributor/fork status, draft/review/merge/check state, risky diff
signals such as .beads/ changes or missing tests, and the required
contributor-protection next steps. It does not replace code review or local
validation.
Base-branch health is supplemented by a warn-only PR-gate sample: the last 60
completed pull_request-event runs, grouped per workflow. A single workflow
whose decisive runs (>= 5, across >= 3 distinct head branches) are all
failure-class is reported as a broken PR gate — the case where a job that
exists only in the PR workflow is red for every PR while the base branch shows
green. This detector never blocks (deliberately: automation classifies
unrecognized [block] lines as genuine merge blockers and would park merge
lanes on a false positive); it is skipped entirely while the base branch is
red.
gh-body-lint
Lint Markdown files before posting them with gh ... --body-file.
./scripts/gh-body-lint body.md
./scripts/gh-body-lint --fix body.md
The lint catches literal \n sequences, which render poorly on GitHub, and
GH#123 references, which do not auto-link like #123 or owner/repo#123.
release.sh (⭐ The Easy Button)
One-command release from version bump to local installation.
Usage
# Full release (does everything)
./scripts/release.sh 0.9.3
# Preview what would happen
./scripts/release.sh 0.9.3 --dry-run
What It Does
This master script automates the entire release process:
- ✅ Stops running Dolt servers (avoids version conflicts)
- ✅ Runs tests and linting
- ✅ Bumps version in all files
- ✅ Commits and pushes version bump
- ✅ Creates and pushes git tag
- ✅ Verifies or opens the Homebrew core formula PR
- ✅ Upgrades local Homebrew installation
- ✅ Verifies everything works
After this script completes, your system is running the new version!
Examples
# Release version 0.9.3
./scripts/release.sh 0.9.3
# Preview a release (no changes made)
./scripts/release.sh 1.0.0 --dry-run
Prerequisites
- Clean git working directory
- All changes committed
- golangci-lint installed
- Homebrew installed (for local upgrade)
- Push access to gastownhall/beads
Output
The script provides colorful, step-by-step progress output:
- 🟨 Yellow: Current step
- 🟩 Green: Step completed
- 🟥 Red: Errors
- 🟦 Blue: Section headers
What Happens Next
After the script finishes:
- GitHub Actions builds binaries for all platforms (~5 minutes)
- PyPI package is published automatically
- Homebrew core formula is verified or tracked through its canonical PR
- Users can
brew upgrade beadsto get the new version after Homebrew merges - GitHub Release is created with binaries and changelog
bump-version.sh
Bumps the version number across all beads components in a single command.
Usage
# Show usage
./scripts/bump-version.sh
# Update versions (shows diff, no commit)
./scripts/bump-version.sh 0.9.3
# Update versions and auto-commit
./scripts/bump-version.sh 0.9.3 --commit
What It Does
Updates version in all these files:
cmd/bd/version.go- bd CLI version constantplugins/beads/.claude-plugin/plugin.json- Claude plugin versionplugins/beads/.codex-plugin/plugin.json- Codex plugin version.claude-plugin/marketplace.json- Claude marketplace plugin versionintegrations/beads-mcp/pyproject.toml- MCP server versionREADME.md- Alpha status versionPLUGIN.md- Version requirements
Features
- Validates semantic versioning format (MAJOR.MINOR.PATCH)
- Verifies all versions match after update
- Shows git diff of changes
- Auto-commits with standardized message (optional)
- Cross-platform compatible (macOS and Linux)
Examples
# Bump to 0.9.3 and review changes
./scripts/bump-version.sh 0.9.3
# Review the diff, then manually commit
# Bump to 1.0.0 and auto-commit
./scripts/bump-version.sh 1.0.0 --commit
git push origin main
Why This Script Exists
Previously, version bumps only updated cmd/bd/version.go, leaving other components out of sync. This script ensures all version numbers stay consistent across the project.
Safety
- Checks for uncommitted changes before proceeding
- Refuses to auto-commit if there are existing uncommitted changes
- Validates version format before making any changes
- Verifies all versions match after update
- Shows diff for review before commit
sign-windows.sh
Signs Windows executables with an Authenticode certificate using osslsigncode.
Usage
# Sign a Windows executable
./scripts/sign-windows.sh path/to/bd.exe
# Environment variables required for signing:
export WINDOWS_SIGNING_CERT_PFX_BASE64="<base64-encoded-pfx>"
export WINDOWS_SIGNING_CERT_PASSWORD="<certificate-password>"
What It Does
This script is called automatically by GoReleaser during the release process:
- Decodes the PFX certificate from base64
- Signs the Windows executable using osslsigncode
- Timestamps the signature using DigiCert's RFC3161 server
- Replaces the original binary with the signed version
- Verifies the signature was applied correctly
Prerequisites
osslsigncodeinstalled (apt install osslsigncodeorbrew install osslsigncode)- EV code signing certificate exported as PFX file
- GitHub secrets configured:
WINDOWS_SIGNING_CERT_PFX_BASE64- base64-encoded PFX fileWINDOWS_SIGNING_CERT_PASSWORD- certificate password
Graceful Degradation
If the signing secrets are not configured:
- The script prints a warning and exits successfully
- GoReleaser continues without signing
- The release proceeds with unsigned Windows binaries
This allows releases to work before a certificate is acquired.
Why This Script Exists
Windows code signing helps reduce antivirus false positives that affect Go binaries.
Kaspersky and other AV software commonly flag unsigned Go executables as potentially
malicious due to heuristic detection. See docs/reference/antivirus.md for details.
Future Scripts
Additional maintenance scripts may be added here as needed.