Releasing
This guide covers how to create a new release of the Archon CLI.
Version Management
Section titled “Version Management”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.
Release Process
Section titled “Release Process”Releases are created by merging dev into main. Never commit directly to main.
1. Prepare the Release
Section titled “1. Prepare the Release”Use the /release skill (or follow these manual steps):
# Ensure dev is up to dategit checkout devgit pull origin dev
# Run default local validationbun run validatebun run validate --only format,workflow-fixturesCI remains the full validation gate, including service and binary checks that local validation does not run.
The /release skill automates the following:
- Compares
devtomainto generate changelog entries - Bumps the version in root
package.json(patch by default; use/release minoror/release majorfor other increments) - Updates
CHANGELOG.mdfollowing Keep a Changelog format - Creates a PR from
devtomain
2. Merge and Tag
Section titled “2. Merge and Tag”Once the release PR is reviewed and merged:
# Create and push the tag from maingit checkout maingit pull origin maingit tag vX.Y.Zgit push origin vX.Y.ZThis triggers the GitHub Actions release workflow which:
- Builds binaries for all platforms (macOS arm64/x64, Linux arm64/x64, Windows x64)
- Generates checksums
- Creates a GitHub Release with all artifacts
3. Update Homebrew Formula (Optional)
Section titled “3. Update Homebrew Formula (Optional)”After the release workflow completes:
# Update checksums in the Homebrew formula./scripts/update-homebrew.sh vX.Y.Z
# Review and commitgit diff homebrew/archon.rbgit add homebrew/archon.rbgit commit -m "chore: update Homebrew formula for vX.Y.Z"git push origin mainIf you maintain a Homebrew tap (homebrew-archon), copy the updated formula there.
4. Verify the Release
Section titled “4. Verify the Release”# Test the install script (only works if repo is public)curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/scripts/install.sh | bash
# Verify versionarchon versionNote: 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 binarychmod +x /tmp/archon-install/archon-*sudo mv /tmp/archon-install/archon-* /usr/local/bin/archon# Verifyarchon 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:
# 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 checksumsgh release create vX.Y.Z dist/binaries/* \ --title "Archon CLI vX.Y.Z" \ --generate-notes
# 4. Verify the releasegh release view vX.Y.ZNote: With
TARGETandOUTFILEunset,scripts/build-binaries.shcross-compiles the CLI and server executables for every target in its localTARGETSlist intodist/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 adddownloads these), andarchon-web.tar.gz(archon servedownloads it). Thefiles:list of the release step in.github/workflows/release.ymlis the full set CI publishes.
Manual Build (for Testing)
Section titled “Manual Build (for Testing)”To build binaries locally without creating a release:
# 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.shRelease Workflow Details
Section titled “Release Workflow Details”The .github/workflows/release.yml workflow:
-
Triggers on:
- Push of tags matching
v* - Manual workflow dispatch with version input
- Push of tags matching
-
Build job (runs in parallel for each platform):
- Sets up Bun
- Installs dependencies
- Compiles binary with
bun build --compile - Uploads as artifact
-
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
Troubleshooting
Section titled “Troubleshooting”Build Fails on GitHub Actions
Section titled “Build Fails on GitHub Actions”Check the Actions tab for specific errors. Common issues:
- Dependency installation failure: Check
bun.lockis committed - Type errors: Run
bun run type-checklocally first
Install Script Fails
Section titled “Install Script Fails”The install script requires:
curlfor downloadingsha256sumorshasumfor verification- Write access to
/usr/local/bin(or customINSTALL_DIR)
Checksums Don’t Match
Section titled “Checksums Don’t Match”If users report checksum failures:
- Check the release artifacts are complete
- Verify checksums.txt was generated correctly
- Ensure binaries weren’t modified after checksum generation
Pre-release Versions
Section titled “Pre-release Versions”For testing releases before public announcement:
# Create a pre-release taggit tag v0.3.0-beta.1git push origin v0.3.0-beta.1Pre-releases (tags containing -) are marked as such on GitHub.
Hotfix Process
Section titled “Hotfix Process”For urgent fixes to a released version:
# Create hotfix branch from taggit checkout -b hotfix/0.2.1 v0.2.0
# Make fixes, then taggit tag v0.2.1git push origin v0.2.1
# Merge fixes back to devgit checkout devgit merge hotfix/0.2.1git push origin dev