beads/scripts
Vishnu J 8f195454ef
fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134)
* fix(winget): require PortableCommandAlias for GasTownHall.Beads

GasTownHall.Beads 1.1.0 on winget-pkgs only sets Commands: (search
metadata) and never creates WinGet\Links\bd.exe, so already-running
shells never see bd after install (GH#4908).

- Add canonical GasTownHall.Beads.installer.yaml with PortableCommandAlias
- update-winget.sh regenerates that package id for new releases
- Document both package ids and the Links requirement in winget/README
- Add check-winget-portable-alias.sh guard

Fixes #4908

* fix(winget): address maphew's PR #5134 review (grep bug, guard, CI wiring)

Maintainer commits requested by the PR author on the reviewer's behalf,
addressing maphew's 2026-07-29 review of PR #5134:

- scripts/update-winget.sh: `grep windows` matched both amd64 and arm64
  checksum lines, corrupting InstallerSha256 into an unparseable
  two-line value. Narrow to `grep windows_amd64` (mirrors the existing
  arm64 grep on the next block).
- scripts/update-winget.sh: quote the arm64 InstallerSha256 placeholder
  so 64 bare zero digits don't parse as a YAML integer, matching the
  quoting already used in the checked-in SteveYegge.beads.installer.yaml.
- scripts/check-winget-portable-alias.sh: replace the bare
  `grep -q PortableCommandAlias:` substring check with a yq-based parse,
  so a corrupted manifest (like the one above) fails the guard instead
  of reporting OK; also fail closed on an empty winget/ glob instead of
  silently exiting 0.
- .github/workflows/pr.yml, main.yml: run the guard in the existing
  check-build-tags job so it executes on every PR instead of only when
  someone remembers to invoke it by hand.

Locally verified: guard passes against the current checked-in
manifests, fails against a reproduction of the exact grep-bug
corruption, fails on an empty winget/ dir, and the generator produces
a yq-parseable manifest against a synthetic checksums.txt. shellcheck
clean; both workflow files parse as valid YAML.

* fix(winget): harden the PortableCommandAlias guard and its release docs

Maintainer review fixups for the adopt-pr review of PR #5134 (iteration 1,
synthesis approve / 0 blockers and 0 majors; all seven items were non-gating).
Scorecard 961/1000, Required Changes: None. Every edit site below is a line
this PR itself added.

Finding 1 (minor, Error Handling) — `yq -e ... >/dev/null 2>&1` collapsed three
distinct failures (yq absent at exit 127, unparseable manifest, alias genuinely
missing) into "missing valid PortableCommandAlias", defeating the script's own
stated rationale and pointing a debugger at manifests that are already correct.
The guard now names a missing yq up front and no longer discards stderr, so
yq's own diagnostic reaches the log of a required-gate job. yq is CI's first and
only yq consumer, running in a bare actions/checkout job, and sits outside the
host-tools inventory declared in scripts/BUILD.bazel; that is now stated where
the dependency lives.

Finding 4 (minor, Change Impact) — the glob is winget/*.installer.yaml but the
assertion was unconditional on installer type, so a future msi/exe/msix
manifest (no NestedInstallerFiles at all) would hard-fail a gate-feeding job
with no opt-out. Non-portable manifests are now classified out with a SKIP line.
The parse check deliberately precedes the class check: without that ordering an
unparseable manifest fails the NestedInstallerType test and is silently skipped
as "not portable", which is strictly worse than the behaviour being fixed.

Finding 2 (minor, Error Handling) — amd64 and arm64 had opposite failure
policies in one script: a missing amd64 checksum hard-fails, while a missing
arm64 checksum substituted 64 zeros and continued to success, disclosed only in
a source comment. The echoed "Next steps" block now ends in a loud
"DO NOT PUBLISH" warning naming the placeholder, emitted only when the fallback
actually fires.

  The finding's second arm — "teach the guard to reject an all-zero
  InstallerSha256" — is implemented as a WARNING rather than a failure, and
  that is a deliberate downgrade. winget/SteveYegge.beads.installer.yaml:15
  already carries exactly that placeholder for its arm64 entry; that file is
  base-owned and is not in this PR's six-file diff, so a fatal tripwire would
  turn a required check red over pre-existing content the PR never touched.
  The legacy heredoc in update-winget.sh emits no arm64 entry at all, so the
  placeholder is stale hand-authored state that the next generator run removes.
  Verified: the guard still exits 0 on the real tree and reports the warning.

Finding 3 (minor, Contract & Interface Fidelity) — a winget-pkgs version
directory needs a version + defaultLocale + installer set, but the repo carries
only GasTownHall.Beads.installer.yaml, so README step 2 as written produced a
set winget-pkgs validation rejects. Took the documentation arm: GasTownHall is
now steered to `wingetcreate update` (which supplies the other two manifests
from the published set) and the hand-copy path is marked as applying only to
the legacy id, which does have a complete three-file set. Generating two more
manifests would have changed the contribution's deliverable scope.

Finding 5 (nit, Architectural Consistency) — the first update-winget.sh run
overwrote the checked-in manifest with a three-line header, deleting this PR's
own GH#4908 rationale from the artifact whose purpose is to carry it. The
heredoc now emits the same header, plus a fresh ReleaseDate. Verified by
generating into a temp tree: the generated header is byte-identical to the
checked-in file's first ten lines.

Finding 6 (nit, Documentation Accuracy) — the README froze SteveYegge.beads at
the "0.30.x era" while the script rewrites all three of its manifests to the
new version. Note that the section already disclosed that both ids are
refreshed, so the residual gap was narrower than the finding stated: what was
missing is that the legacy id's version is bumped out of the era the table
advertises. That clause is now explicit.

Finding 7 (nit, Test Evidence Quality) — the guard's fail-closed behaviour was
pinned by nothing in-repo. Adds scripts/check_winget_portable_alias_test.go
with ten cases: alias present, alias missing, wrong alias, empty winget dir,
unparseable manifest (asserting it is neither skipped nor misreported and that
yq's stderr survives), missing yq, a skipped non-portable manifest, a violating
portable sibling of a skipped manifest, and the advisory placeholder warning.

  Deviates from the prescribed `requireHostTool(t, "yq")` on purpose.
  requireHostTool fails rather than skips under Bazel because
  //scripts:scripts_test is tagged host-tools, and that tag's declared
  inventory is "git, python3, awk, sed, find, grep and timeout" — yq is not in
  it, so the prescription would red the shared target on hosts that keep the
  promise the tag actually makes. A skip-only gate is used and the reason is
  recorded at the helper. Fixtures are synthetic so the target needs no new
  data dependency; the real manifests are covered by the check-build-tags job,
  which runs this script against the actual checkout.

Also fixed, found while editing and not raised by either lane: winget/README.md
told readers to run `grep windows` over checksums.txt, which is the exact
two-line ambiguity this PR fixed in the script (`grep windows` ->
`grep windows_amd64`). Before this PR the script and doc agreed; after it they
diverged, so the PR created the inconsistency. The doc now uses `grep windows_`
and says which line feeds which architecture.

Validation. `git diff --check` clean. The guard runs green on the real tree
(both manifests OK, rc=0) and on a freshly generated tree. go test ./scripts/
ok 21.7s (the package whose tests pin workflow content). Each new pin was
proven non-vacuous by reverting the corresponding fix and confirming the test
reds: dropping the class check reds the non-portable case; dropping the
placeholder tripwire reds the warning case; dropping the parse-before-classify
check reds the unparseable case; dropping the yq preflight reds the missing-yq
case; restoring `2>&1` reds the stderr assertion. All five arms red, and the
guard was restored byte-identical (md5 verified) after each. The arm64 warning
was exercised both ways against a stubbed curl: present arm64 checksum emits no
warning, absent one emits DO NOT PUBLISH.

New yq expressions stay inside the vocabulary shared by mikefarah yq v4 (what
ubuntu-latest ships) and python-yq/jq — identity, `==`, `[]`, `select` and
`-e`'s exit status — because only the pre-existing expression had been proven
green on mikefarah in CI, and this host has python-yq. Builtins the two flavours
spell differently (jq's `any(cond)` vs mikefarah's `any_c`) are avoided, and the
placeholder tripwire uses grep precisely because it looks for a known-bad
literal and so can only miss a bad value, never report OK on a manifest it
failed to parse.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Bee <bee@ghosttrack.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
2026-09-30 20:24:59 -07:00
..
bench-ready-indexes build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
ci test(init): make gateway credential fixtures portable across native shells (#5715) (#5725) 2026-09-30 20:10:22 -07:00
gitattributespolicy test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
hooks feat: Add post-push hook to auto-install bd CLI after git push 2025-10-14 17:23:43 -07:00
internal/testbash test(scripts): resolve Git Bash explicitly on Windows (#5727) (#5730) 2026-09-30 15:50:28 -07:00
migration-test test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
prlintmake fix(ci): resolve gofmt from go.mod's toolchain, not PATH (be-gx8) (#6294) 2026-09-30 18:38:46 -07:00
repro-be-1he-slow-path perf(dolt): eliminate 12s slow path on bd commands when .local_version is stale (#3710) 2026-07-24 00:53:06 -07:00
repro-dolt-hang build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
repro-dolt-prod-timeouts test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
bazel-autofix-push.sh ci: auto-push Bazel BUILD sync fixes to PRs; harden docs autofix (#6907) 2026-09-28 17:23:27 -07:00
bazel_autofix_push_test.go ci: auto-push Bazel BUILD sync fixes to PRs; harden docs autofix (#6907) 2026-09-28 17:23:27 -07:00
bazel_farm_workflow_test.go ci(bazel): remote-execution Bazel lanes for allowlisted fork authors (advisory) (#6994) 2026-09-30 14:54:06 -07:00
bazel_policy_test.go ci(bazel): server-Dolt storage and proxied tiers on remote execution (#6940) 2026-09-28 23:01:40 -07:00
build-examples.sh fix(examples): tidy both example modules and build them in CI (#5229) 2026-08-12 21:16:27 -07:00
BUILD.bazel fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
bump-version.sh refactor: replace bump-version.sh with molecule pointer 2026-01-14 21:53:06 -08:00
check-build-tags.sh build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
check-cli-docs-drift.sh docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
check-doc-flags.sh fix(scripts): make check-doc-flags portable to BSD grep and fail loud on grep errors (#6026) 2026-09-02 17:25:53 -07:00
check-doc-freshness.sh docs(recovery): init-safety re-clone playbook covers damaged-store and fresh-clone gotchas (#6431) 2026-09-27 03:41:05 -07:00
check-go-install-guidance.sh fix(install): use declared module path for go fallback (#4215) 2026-05-27 21:48:24 -07:00
check-migration-hygiene.sh fix(schema): CLI bundle never got migration 0065's wisp_comments widening (ga-61ruw) (#5910) 2026-08-20 23:38:48 -07:00
check-testing-short.sh Fix: check-testing-short.sh flags comments and misnames the offending function (round 2) (#5809) 2026-08-19 21:01:15 -07:00
check-versions.sh release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038) 2026-08-30 22:19:35 -07:00
check-winget-portable-alias.sh fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
check_build_tags_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
check_doc_freshness_test.go test(scripts): resolve Git Bash explicitly on Windows (#5727) (#5730) 2026-09-30 15:50:28 -07:00
check_testing_short_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
check_winget_portable_alias_test.go fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
ci_capability_selector_test.go ci: PR-CI lane runs the full internal/storage/dolt suite against a live Dolt server (#5836) 2026-08-19 20:39:38 -07:00
ci_workflow_apt_get_timeout_test.go fix: bound and retry apt-get calls in CI to avoid unbounded 15-minute job timeout (#5810) 2026-08-19 11:47:22 -07:00
ci_workflow_test.go test(init): make gateway credential fixtures portable across native shells (#5715) (#5725) 2026-09-30 20:10:22 -07:00
clean-test-tmp.sh test(cmd/bd): route sync.Once test temp dirs through TestMain cleanup (#4108) 2026-05-22 16:48:22 -07:00
complexity_script_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
conformance.sh ci: give conformance explicit timeout budgets (#5073) 2026-07-28 09:01:39 -07:00
conformance_script_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
cross-version-smoke-test.sh docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
docs-autofix-push.sh ci: auto-push Bazel BUILD sync fixes to PRs; harden docs autofix (#6907) 2026-09-28 17:23:27 -07:00
docs.md Validate doc freshness max age (#5524) (#5606) 2026-08-10 21:02:23 -07:00
gen-winres.sh chore: re-land v1.1.0-rc.1 release prep (#4486) 2026-06-25 20:10:18 -07:00
generate-cli-docs.sh docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
generate-newsletter.py Newsletter dropped every commit made before the hour it ran (#6491) 2026-09-26 18:56:29 -07:00
generate-newsletter_README.md Newsletter dropped every commit made before the hour it ran (#6491) 2026-09-26 18:56:29 -07:00
gh-body-lint docs: align agent maintainer conventions (#4237) 2026-06-20 20:44:08 -07:00
host_tools_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
install-hooks.sh feat: Add post-push hook to auto-install bd CLI after git push 2025-10-14 17:23:43 -07:00
install.sh docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
install_dolt_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
migrate-jsonl-to-dolt.sh feat: add JSONL-to-Dolt migration script (GH#2276) 2026-03-02 22:05:38 -08:00
migrate-legacy-to-current.sh Guard and qualify historical upgrades to v1.2 (#4907) 2026-08-06 18:45:04 -07:00
mutation-equivalence.sh Fix a SIGPIPE in the mutation harness's worktree guard (#5434) 2026-08-08 08:28:08 -07:00
pr-preflight.sh fix(pr-preflight): warn when a PR-gate workflow is red for every PR while the base shows green (#5251) 2026-08-01 22:46:44 -07:00
pr_preflight_test.go test(scripts): resolve Git Bash explicitly on Windows (#5727) (#5730) 2026-09-30 15:50:28 -07:00
pull_dolt_image_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
README.md fix(pr-preflight): warn when a PR-gate workflow is red for every PR while the base shows green (#5251) 2026-08-01 22:46:44 -07:00
release.sh fix(release): harden shipped release formula adoption (#3668) 2026-05-06 12:14:54 -07:00
release_script_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
resolve-docs-bd.sh docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
sign-windows.sh docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
test-cgo.sh Rename ICU-only test path to explicit opt-in workflow (bd-b18) (#3291) 2026-04-16 08:54:24 -07:00
test-git-remote.sh /{.github,docs,engdocs,go,internal,scripts}: bump dolt 2026-07-15 13:14:34 -07:00
test-icu-path.sh Rename ICU-only test path to explicit opt-in workflow (bd-b18) (#3291) 2026-04-16 08:54:24 -07:00
test.sh fix: export the native prebuilt test binary path (#5512) 2026-08-10 05:31:23 -07:00
test_script_test.go test(scripts): report helper-only probe as skipped (#5599) 2026-08-10 20:58:58 -07:00
update-nix-vendorhash.sh fix(scripts): update-nix-vendorhash writes a stray default.nix'' on BSD sed (#6096) 2026-09-02 17:33:58 -07:00
update-versions.sh fix(release): version bumps now own the tracked .githooks markers 2026-08-11 14:06:28 -07:00
update-winget.sh fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
upgrade-smoke-test.sh fix(smoke): clear the version list before child dispatch (#6398) 2026-09-28 08:25:22 -07:00
upgrade_smoke_loop_test.go fix(smoke): clear the version list before child dispatch (#6398) 2026-09-28 08:25:22 -07:00
verify-cgo.sh fix: remove ICU runtime dependency from release binaries (#3066) 2026-04-07 09:48:44 -07:00

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-mcp builds or consumes a bd binary, puts it on PATH as bd, then runs locked MCP package uv sync, Ruff, mypy, pytest, and build checks.
  • make ci-package-npm builds or consumes the native binary expected by npm-package/bin/bd, runs the npm package test suite, and checks npm 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:

  1. ✅ Stops running Dolt servers (avoids version conflicts)
  2. ✅ Runs tests and linting
  3. ✅ Bumps version in all files
  4. ✅ Commits and pushes version bump
  5. ✅ Creates and pushes git tag
  6. ✅ Verifies or opens the Homebrew core formula PR
  7. ✅ Upgrades local Homebrew installation
  8. ✅ 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 beads to 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 constant
  • plugins/beads/.claude-plugin/plugin.json - Claude plugin version
  • plugins/beads/.codex-plugin/plugin.json - Codex plugin version
  • .claude-plugin/marketplace.json - Claude marketplace plugin version
  • integrations/beads-mcp/pyproject.toml - MCP server version
  • README.md - Alpha status version
  • PLUGIN.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:

  1. Decodes the PFX certificate from base64
  2. Signs the Windows executable using osslsigncode
  3. Timestamps the signature using DigiCert's RFC3161 server
  4. Replaces the original binary with the signed version
  5. Verifies the signature was applied correctly

Prerequisites

  • osslsigncode installed (apt install osslsigncode or brew install osslsigncode)
  • EV code signing certificate exported as PFX file
  • GitHub secrets configured:
    • WINDOWS_SIGNING_CERT_PFX_BASE64 - base64-encoded PFX file
    • WINDOWS_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.