Release Process for Beads

This document describes the complete release process for beads, including GitHub releases, Homebrew, PyPI (MCP server), and npm packages.

Overview
Prerequisites
Release Checklist
1. Prepare Release
2. GitHub Release
3. Homebrew Update
4. PyPI Release (MCP Server)
5. npm Package Release
6. Verify Release
Prerelease / Release Candidate (RC) Workflow
Hotfix Releases
Rollback Procedure

Overview

A beads release involves multiple distribution channels:

GitHub Release - Binary downloads for all platforms
Homebrew - macOS/Linux package manager
PyPI - Python MCP server (beads-mcp)
npm - Node.js package for Claude Code for Web (@beads/bd)

The Easy Way (Recommended)

For routine releases, use the fully automated release script:

bash

./scripts/release.sh 0.22.0

This handles version bump, tests, git tag, Homebrew update, and local installation in one shot. See scripts/README.md for details. The rest of this document is the manual / step-by-step process, useful for understanding what release.sh does and for handling edge cases (hotfixes, rollbacks, manual PyPI/npm publishes).

Prerequisites

Required Tools

git with push access to gastownhall/beads
goreleaser for building binaries
npm with authentication (for npm releases)
python3 and twine (for PyPI releases)
gh CLI (GitHub CLI, optional but recommended)

Required Access

GitHub: Write access to repository and ability to create releases
GitHub: Ability to create protected v* release tags. The repository should restrict refs/tags/v* creation, updates, and deletion to trusted release maintainers.
PyPI: Maintainer access to beads-mcp package
npm: Member of @beads organization

Verify Setup

bash

# Check git
git remote -v  # Should show gastownhall/beads

# Check goreleaser
goreleaser --version

# Check GitHub CLI (optional)
gh auth status

# Check npm
npm whoami  # Should show your npm username

# Check Python/twine (for MCP releases)
python3 --version
twine --version

Release Checklist

Before starting a release:

All tests passing (go test ./...)
npm package tests passing (cd npm-package && npm run test:all)
Upgrade smoke tests pass (make test-upgrade) — see Release Stability Gate
Regression tests pass (make test-regression)
CHANGELOG.md updated with release notes (see format below)
Breaking changes documented with migration steps and recovery instructions
No uncommitted changes
On main branch and up to date with origin

1. Prepare Release

Update CHANGELOG.md

IMPORTANT: Do this FIRST before running bump-version script.

Add release notes to CHANGELOG.md:

markdown

## [0.22.0] - 2025-11-04

### Added
- New feature X
- New command Y

### Changed
- Improved performance of Z

### Fixed
- Bug in component A

### Breaking Changes
- Changed behavior of B (migration guide)

Commit the CHANGELOG changes:

bash

git add CHANGELOG.md
git commit -m "docs: Add CHANGELOG entry for v0.22.0"
git push origin main

Update Version and Create Release Tag

Use the version bump script to update all version references and create the release tag:

bash

# Dry run - shows what will change
./scripts/bump-version.sh 0.22.0

# Full release with all local installations
./scripts/bump-version.sh 0.22.0 --commit --tag --push --all

Available flags:

Flag	Description
`--commit`	Create a git commit with version changes
`--tag`	Create annotated git tag (requires --commit)
`--push`	Push commit and tag to origin (requires --tag)
`--install`	Build and install bd to `~/go/bin` AND `~/.local/bin`
`--mcp-local`	Install beads-mcp from local source via uv/pip
`--upgrade-mcp`	Upgrade beads-mcp from PyPI (after PyPI publish)
`--restart-servers`	Restart all Dolt servers to pick up new version
`--all`	Shorthand for `--install --mcp-local --restart-servers`

This updates:

cmd/bd/version.go - CLI version constant
integrations/beads-mcp/pyproject.toml - MCP server version
integrations/beads-mcp/src/beads_mcp/__init__.py - MCP Python version
plugins/beads/.claude-plugin/plugin.json - Claude plugin version
plugins/beads/.codex-plugin/plugin.json - Codex plugin version
.claude-plugin/marketplace.json - Claude marketplace version
npm-package/package.json - npm package version
cmd/bd/templates/hooks/* - Git hook versions
README.md - Documentation version
PLUGIN.md - Version requirements
CHANGELOG.md - Creates release entry from [Unreleased]

The --commit --tag --push flags will:

Create a git commit with all version changes
Create an annotated tag v0.22.0
Push both commit and tag to origin

This triggers GitHub Actions to build release artifacts automatically.

The tag workflow re-runs release-critical package gates before publishing:

make ci-package-mcp builds and validates the MCP package, then the PyPI job publishes the validated dist/* artifact from that gate.
make ci-package-npm validates the npm wrapper package before npm publish.
make ci-website validates the release docs/website build before GoReleaser publishes GitHub release assets.

The npm publish job also waits for the macOS release assets, because the npm postinstall script downloads platform-specific archives from the GitHub release.

Recommended workflow:

bash

# 1. Update CHANGELOG.md and cmd/bd/info.go with release notes (manual step)

# 2. Bump version and install everything locally
./scripts/bump-version.sh 0.22.0 --commit --all

# 3. Test locally, then tag and push
git tag -a v0.22.0 -m "Release v0.22.0"
git push origin main
git push origin v0.22.0

The release workflow is intentionally gated to refs/tags/v*. A manual workflow dispatch from a branch will skip publishing jobs; manual reruns must select the release tag.

Alternative (step-by-step):

bash

# Just commit
./scripts/bump-version.sh 0.22.0 --commit

# Then manually tag and push
git tag -a v0.22.0 -m "Release v0.22.0"
git push origin main
git push origin v0.22.0

2. GitHub Release

Using GoReleaser (Recommended)

GoReleaser automates binary building and GitHub release creation:

bash

# Clean any previous builds
rm -rf dist/

# Create release (requires GITHUB_TOKEN)
export GITHUB_TOKEN="your-github-token"
goreleaser release --clean

# Or use gh CLI for token
gh auth token | goreleaser release --clean

This will:

Build binaries for all platforms (macOS, Linux, Windows - amd64/arm64)
Create checksums
Generate release notes from CHANGELOG.md
Upload everything to GitHub releases
Mark as latest release

Manual Release (Alternative)

If goreleaser doesn't work:

bash

# Build for all platforms
./scripts/build-all-platforms.sh

# Create GitHub release
gh release create v0.22.0 \
  --title "v0.22.0" \
  --notes-file CHANGELOG.md \
  dist/*.tar.gz \
  dist/*.zip \
  dist/checksums.txt

Verify GitHub Release

Visit https://github.com/gastownhall/beads/releases
Verify v0.22.0 is marked as "Latest"
Check all platform binaries are present:
- beads_0.22.0_darwin_amd64.tar.gz
- beads_0.22.0_darwin_arm64.tar.gz
- beads_0.22.0_linux_amd64.tar.gz
- beads_0.22.0_linux_arm64.tar.gz
- beads_0.22.0_windows_amd64.zip
- checksums.txt

3. Homebrew Update

Homebrew uses the beads formula in homebrew-core. Do not publish or revive the old bd formula in gastownhall/homebrew-beads; having two independently updated Homebrew formulas causes version drift and installs the wrong binary for some users.

Updates to the supported Homebrew formula are handled through Homebrew core after GitHub Release artifacts are available.

Verify Homebrew

After the GitHub Release is published, verify the Homebrew package:

bash

# Update Homebrew
brew update

# Install/upgrade
brew upgrade beads  # or: brew install beads

# Verify
bd version  # Should show 0.22.0

4. PyPI Release (MCP Server)

The MCP server is a Python package published separately to PyPI.

Prerequisites

bash

# Install build tools
pip install build twine

# Verify PyPI credentials
cat ~/.pypirc  # Should have token or credentials

Build and Publish

bash

# Navigate to MCP server directory
cd integrations/mcp/server

# Verify version was updated
cat pyproject.toml | grep version

# Clean old builds
rm -rf dist/ build/ *.egg-info

# Build package
python -m build

# Verify contents
tar -tzf dist/beads-mcp-0.22.0.tar.gz

# Upload to PyPI (test first)
twine upload --repository testpypi dist/*

# Verify on test PyPI
pip install --index-url https://test.pypi.org/simple/ beads-mcp==0.22.0

# Upload to production PyPI
twine upload dist/*

Verify PyPI Release

bash

# Check package page
open https://pypi.org/project/beads-mcp/

# Install and test
pip install beads-mcp==0.22.0
python -m beads_mcp --version

5. Plugin Marketplace Update

Update the plugin marketplace metadata files:

bash

# Update .claude-plugin/marketplace.json
# Change version to match current release
vim .claude-plugin/marketplace.json

# Update plugins/beads/.claude-plugin/plugin.json if needed
vim plugins/beads/.claude-plugin/plugin.json

# Update plugins/beads/.codex-plugin/plugin.json if needed
vim plugins/beads/.codex-plugin/plugin.json

# Commit changes
git add .claude-plugin/ plugins/beads/.claude-plugin/ plugins/beads/.codex-plugin/
git commit -m "chore: Update plugin marketplaces to v0.22.0"

Note: These files define how beads appears in Claude Code and Codex plugin marketplaces. Version should match the release version.

Documentation Site (Docusaurus)

The published docs at GitHub Pages are versioned. Unreleased edits live in website/docs/ (Next); each release should add a snapshot:

bash

cd website
npm ci
npm run docusaurus docs:version X.Y.Z

Then set lastVersion in website/docusaurus.config.ts to X.Y.Z so visitors default to the latest stable docs (not Next).

Commit website/versioned_docs/, website/versioned_sidebars/, and website/versions.json with the release. The scripts/generate-llms-full.sh script pulls from the latest entry in versions.json so llms-full.txt stays aligned with that snapshot.

6. npm Package Release

The npm package wraps the native binary for Node.js environments.

Prerequisites

bash

# Verify npm authentication
npm whoami  # Should show your username

# Verify you're in @beads org
npm org ls beads

Update and Test

bash

# Navigate to npm package
cd npm-package

# Version should already be updated by bump-version.sh
cat package.json | grep version

# Run all tests
npm run test:all

# Should see:
# ✅ All unit tests passed
# ✅ All integration tests passed

Test Installation Locally

bash

# Pack the package
npm pack

# Install globally from tarball
npm install -g ./beads-bd-0.22.0.tgz

# Verify binary downloads correctly
bd version  # Should show 0.22.0

# Test in a project
mkdir /tmp/test-npm-bd
cd /tmp/test-npm-bd
git init
bd init
bd create "Test issue" -p 1
bd list

# Cleanup
npm uninstall -g @beads/bd
rm -rf /tmp/test-npm-bd
cd -
rm beads-bd-0.22.0.tgz

Publish to npm

bash

# IMPORTANT: Ensure GitHub release with binaries is live first!
# The postinstall script downloads from GitHub releases

# Publish to npm (first time use --access public)
npm publish --access public

# Or for subsequent releases
npm publish

Verify npm Release

bash

# Check package page
open https://www.npmjs.com/package/@beads/bd

# Install and test
npm install -g @beads/bd
bd version  # Should show 0.22.0

# Test postinstall downloaded correct binary
which bd
bd --help

7. Verify Release

After all distribution channels are updated, verify each one:

GitHub

bash

# Download and test binary
wget https://github.com/gastownhall/beads/releases/download/v0.22.0/beads_0.22.0_darwin_arm64.tar.gz
tar -xzf beads_0.22.0_darwin_arm64.tar.gz
./bd version

Homebrew

bash

brew update
brew upgrade beads
bd version

PyPI

bash

pip install --upgrade beads-mcp
python -m beads_mcp --version

npm

bash

npm install -g @beads/bd
bd version

Installation Script

bash

# Test quick install script
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
bd version

Prerelease / Release Candidate (RC) Workflow

Release candidates let a build be validated through the full release pipeline without promoting it to the stable channels. An RC carries a SemVer prerelease identifier (e.g. 1.1.0-rc.1); Python tooling normalizes this to PEP 440 form (1.1.0rc1).

How a prerelease tag differs from a stable release:

GitHub release is published and marked as a prerelease (goreleaser release.prerelease: auto), with binaries for all platforms.
Homebrew is not updated (goreleaser brews.skip_upload: true; the core formula only tracks stable releases).
PyPI and npm publish jobs are skipped. The publish-pypi and publish-npm jobs are gated with !contains(github.ref_name, '-'), so a tag containing a - never reaches the stable package channels.
The stable docs snapshot is not required. verify-version-consistency runs scripts/check-versions.sh without BEADS_REQUIRE_RELEASE_DOCS=1 for prerelease tags, and scripts/check-docs-version.sh treats a prerelease canonical version as non-strict. The versioned docs stay on the latest stable release until the base X.Y.Z ships.

Cut an RC

bash

# 1. Update CHANGELOG.md and cmd/bd/info.go with the RC notes (manual step),
#    same as a stable release. Date the CHANGELOG section.

# 2. Bump versions. update-versions.sh accepts a prerelease identifier and,
#    for prereleases, skips the Docusaurus docs snapshot automatically.
./scripts/update-versions.sh 1.1.0-rc.1
#    Windows PE numeric fields (winres file_version/product_version and the
#    manifest <assemblyIdentity> version) are set to the base version 1.1.0,
#    because PE versions must be purely numeric; gen-winres.sh strips the
#    prerelease suffix the same way at build time.

# 3. Keep the MCP lockfile in sync (PEP 440 normalizes to 1.1.0rc1), or the
#    Package Gate (MCP) check goes red:
(cd integrations/beads-mcp && uv lock)

# 4. Validate locally.
./scripts/check-versions.sh

# 5. Open a PR for the RC prep and have it reviewed. RC prep should land
#    through normal review, not auto-merge.

After the RC prep is merged to main, cut the tag from the merge commit:

bash

git checkout main && git pull
git tag -a v1.1.0-rc.1 -m "Release candidate v1.1.0-rc.1"
git push origin v1.1.0-rc.1

Pushing the v* tag triggers the release workflow with the prerelease behavior above. Tag creation is restricted to release maintainers; see Prerequisites.

Validate and promote

Install the RC from the GitHub prerelease assets and exercise the changes it is gating before promoting.
To promote to stable, bump to the base version with no suffix (./scripts/update-versions.sh 1.1.0). The stable bump does require the docs snapshot and does publish to Homebrew/PyPI/npm, so follow the standard Prepare Release steps from there.

Hotfix Releases

For urgent bug fixes:

bash

# Create hotfix branch from tag
git checkout -b hotfix/v0.22.1 v0.22.0

# Make fixes
# ... edit files ...

# Bump version to 0.22.1
./scripts/bump-version.sh 0.22.1 --commit

# Tag and release
git tag -a v0.22.1 -m "Hotfix release v0.22.1"
git push origin hotfix/v0.22.1
git push origin v0.22.1

# Follow normal release process
goreleaser release --clean

# Merge back to main
git checkout main
git merge hotfix/v0.22.1
git push origin main

Rollback Procedure

If a release has critical issues:

1. Mark GitHub Release as Pre-release

bash

gh release edit v0.22.0 --prerelease

2. Create Hotfix Release

Follow hotfix procedure above to release 0.22.1.

3. Deprecate npm Package (If Needed)

bash

npm deprecate @beads/[email protected] "Critical bug, please upgrade to 0.22.1"

4. Yank PyPI Release (If Needed)

bash

# Can't delete, but can yank (hide from pip install)
# Contact PyPI support or use web interface

Automation Opportunities

GitHub Actions

Create .github/workflows/release.yml:

yaml

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v4
      - uses: goreleaser/goreleaser-action@v4
        with:
          version: latest
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  npm:
    needs: goreleaser
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: cd npm-package && npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

  pypi:
    needs: goreleaser
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
      - run: |
          cd integrations/mcp/server
          pip install build twine
          python -m build
          twine upload dist/*
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

Post-Release

After a successful release:

Upgrade local beads-mcp installation to the new version:

bash

# Option 1: Use the bump-version.sh script (recommended during version bump)
./scripts/bump-version.sh <version> --upgrade-mcp

# Option 2: Manual upgrade via pip (if installed globally)
pip install --upgrade beads-mcp

# Option 3: Manual upgrade via uv tool (if installed as a tool)
uv tool upgrade beads-mcp

# Verify the new version
pip show beads-mcp | grep Version

# Restart Claude Code or MCP session to pick up the new version
# The MCP server will load the newly installed version

Note: The --upgrade-mcp flag can be combined with other flags:

bash

# Update versions, commit, install bd binary, and upgrade beads-mcp all at once
./scripts/bump-version.sh 0.24.3 --commit --install --upgrade-mcp

Verify the upgraded CLI:
bash
```
bd version
bd doctor quick
```
Announce on relevant channels (Twitter, blog, etc.)
Update documentation if needed
Close milestone on GitHub if using milestones
Update project board if using project management
Monitor for issues in the first 24-48 hours

Troubleshooting

"Tag already exists"

bash

# Delete tag locally and remotely
git tag -d v0.22.0
git push origin :refs/tags/v0.22.0

# Recreate
git tag -a v0.22.0 -m "Release v0.22.0"
git push origin v0.22.0

"npm publish fails with EEXIST"

bash

# Version already published, bump version
npm version patch
npm publish

"Binary download fails in npm postinstall"

bash

# Ensure GitHub release is published first
# Check binary URL is correct
# Verify version matches in package.json and GitHub release

"GoReleaser build fails"

bash

# Check .goreleaser.yml syntax
goreleaser check

# Test build locally
goreleaser build --snapshot --clean

Version Numbering

Beads follows Semantic Versioning:

MAJOR (x.0.0): Breaking changes
MINOR (0.x.0): New features, backwards compatible
PATCH (0.0.x): Bug fixes, backwards compatible

Examples:

0.21.5 → 0.22.0: New features (minor bump)
0.22.0 → 0.22.1: Bug fix (patch bump)
0.22.1 → 1.0.0: Stable release (major bump)

Prereleases: append a SemVer prerelease identifier for release candidates, e.g. 1.1.0-rc.1. Prerelease tags publish a GitHub prerelease only and stay off the stable Homebrew/PyPI/npm channels — see Prerelease / Release Candidate (RC) Workflow.

Release Cadence

Minor releases: Every 2-4 weeks (new features)
Patch releases: As needed (bug fixes)
Major releases: When breaking changes are necessary

Questions?

Open an issue: https://github.com/gastownhall/beads/issues
Check existing releases: https://github.com/gastownhall/beads/releases

Release Process for Beads

Release Process for Beads

Table of Contents

Overview

The Easy Way (Recommended)

Prerequisites

Required Tools

Required Access

Verify Setup

Release Checklist

1. Prepare Release

Update CHANGELOG.md

Update Version and Create Release Tag

2. GitHub Release

Using GoReleaser (Recommended)

Manual Release (Alternative)

Verify GitHub Release

3. Homebrew Update

Verify Homebrew

4. PyPI Release (MCP Server)

Prerequisites

Build and Publish

Verify PyPI Release

5. Plugin Marketplace Update

Documentation Site (Docusaurus)

6. npm Package Release

Prerequisites

Update and Test

Test Installation Locally

Publish to npm

Verify npm Release

7. Verify Release

GitHub

Homebrew

PyPI

npm

Installation Script

Prerelease / Release Candidate (RC) Workflow

Cut an RC

Validate and promote

Hotfix Releases

Rollback Procedure

1. Mark GitHub Release as Pre-release

2. Create Hotfix Release

3. Deprecate npm Package (If Needed)

4. Yank PyPI Release (If Needed)

Automation Opportunities

GitHub Actions

Post-Release

Troubleshooting

"Tag already exists"

"npm publish fails with EEXIST"

"Binary download fails in npm postinstall"

"GoReleaser build fails"

Version Numbering

Release Cadence

Questions?