Skip to content

Releasing

This guide covers how to create a new release of the Archon CLI.

Versions follow Semantic Versioning:

  • Major (1.0.0): Breaking changes to CLI interface or workflow format
  • Minor (0.1.0): New features, new workflows, new commands
  • Patch (0.0.1): Bug fixes, documentation updates

Version is stored in the root package.json only — this is the single source of truth.

Releases are created by merging dev into main. Never commit directly to main.

Use the /release skill (or follow these manual steps):

Terminal window
# Ensure dev is up to date
git checkout dev
git pull origin dev
# Run default local validation
bun run validate
bun run validate --only format,workflow-fixtures

CI remains the full validation gate, including service and binary checks that local validation does not run.

The /release skill automates the following:

  1. Compares dev to main to generate changelog entries
  2. Bumps the version in root package.json (patch by default; use /release minor or /release major for other increments)
  3. Updates CHANGELOG.md following Keep a Changelog format
  4. Creates a PR from dev to main

Once the release PR is reviewed and merged:

Terminal window
# Create and push the tag from main
git checkout main
git pull origin main
git tag vX.Y.Z
git push origin vX.Y.Z

This triggers the GitHub Actions release workflow which:

  1. Builds binaries for all platforms (macOS arm64/x64, Linux arm64/x64, Windows x64)
  2. Generates checksums
  3. Creates a GitHub Release with all artifacts

After the release workflow completes:

Terminal window
# Update checksums in the Homebrew formula
./scripts/update-homebrew.sh vX.Y.Z
# Review and commit
git diff homebrew/archon.rb
git add homebrew/archon.rb
git commit -m "chore: update Homebrew formula for vX.Y.Z"
git push origin main

If you maintain a Homebrew tap (homebrew-archon), copy the updated formula there.

Terminal window
# Test the install script (only works if repo is public)
curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/scripts/install.sh | bash
# Verify version
archon version

Note: Private Repository Installation

If the repository is private, the curl install script won’t work for anonymous users. Use the GitHub CLI instead:

Terminal window
# Download and install using gh (requires GitHub authentication)
gh release download v0.2.0 --repo coleam00/Archon \
--pattern "archon-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/')" \
--dir /tmp/archon-install
# Install the binary
chmod +x /tmp/archon-install/archon-*
sudo mv /tmp/archon-install/archon-* /usr/local/bin/archon
# Verify
archon version

Manual Release (When GitHub Actions Unavailable)

Section titled “Manual Release (When GitHub Actions Unavailable)”

If GitHub Actions can’t run (billing issues, private repo limits), create the release manually:

Terminal window
# 1. Build binaries locally (every target in the script's local TARGETS list).
# TARGET or OUTFILE left set in the shell switches the script to single-target mode.
unset TARGET OUTFILE
./scripts/build-binaries.sh
# 2. Generate checksums.txt, which the install scripts verify against
./scripts/checksums.sh
# 3. Create the release with binaries and checksums
gh release create vX.Y.Z dist/binaries/* \
--title "Archon CLI vX.Y.Z" \
--generate-notes
# 4. Verify the release
gh release view vX.Y.Z

Note: With TARGET and OUTFILE unset, scripts/build-binaries.sh cross-compiles the CLI and server executables for every target in its local TARGETS list into dist/binaries/. That list has no Windows target.

A manual release is therefore incomplete. It lacks the assets only the CI release builds: the Windows binaries, the plugin executables (archon plugin add downloads these), and archon-web.tar.gz (archon serve downloads it). The files: list of the release step in .github/workflows/release.yml is the full set CI publishes.

To build binaries locally without creating a release:

Terminal window
# Build every target in the script's local TARGETS list (no Windows)
unset TARGET OUTFILE
./scripts/build-binaries.sh
# Binaries are in dist/binaries/
ls -la dist/binaries/
# Generate checksums
./scripts/checksums.sh

The .github/workflows/release.yml workflow:

  1. Triggers on:

    • Push of tags matching v*
    • Manual workflow dispatch with version input
  2. Build job (runs in parallel for each platform):

    • Sets up Bun
    • Installs dependencies
    • Compiles binary with bun build --compile
    • Uploads as artifact
  3. Release job (runs after all builds complete):

    • Downloads all artifacts
    • Generates SHA256 checksums
    • Creates GitHub Release with:
      • All binaries attached
      • checksums.txt
      • Auto-generated release notes
      • Installation instructions

Check the Actions tab for specific errors. Common issues:

  • Dependency installation failure: Check bun.lock is committed
  • Type errors: Run bun run type-check locally first

The install script requires:

  • curl for downloading
  • sha256sum or shasum for verification
  • Write access to /usr/local/bin (or custom INSTALL_DIR)

If users report checksum failures:

  1. Check the release artifacts are complete
  2. Verify checksums.txt was generated correctly
  3. Ensure binaries weren’t modified after checksum generation

For testing releases before public announcement:

Terminal window
# Create a pre-release tag
git tag v0.3.0-beta.1
git push origin v0.3.0-beta.1

Pre-releases (tags containing -) are marked as such on GitHub.

For urgent fixes to a released version:

Terminal window
# Create hotfix branch from tag
git checkout -b hotfix/0.2.1 v0.2.0
# Make fixes, then tag
git tag v0.2.1
git push origin v0.2.1
# Merge fixes back to dev
git checkout dev
git merge hotfix/0.2.1
git push origin dev