From 6e88537e15fb287a306f7a7958ff45de19cf6125 Mon Sep 17 00:00:00 2001 From: Vinicius Rocha Date: Tue, 29 Sep 2026 19:34:30 -0400 Subject: [PATCH] Add Homebrew distribution --- .github/workflows/release.yml | 31 +++++++++++++++++++++++++++++++ README.md | 10 ++++++++-- docs/INSTALL.md | 17 +++++++++++++++++ docs/RELEASING.md | 19 +++++++++++++++++-- website/guide/installation.md | 16 +++++++++++++--- 5 files changed, 86 insertions(+), 7 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 72024cc..0130056 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -52,3 +52,34 @@ jobs: --verify-tag \ --notes-file "docs/releases/$GITHUB_REF_NAME.md" \ --title "Bible CLI $GITHUB_REF_NAME" + + - name: Check Homebrew tap credentials + if: ${{ !contains(github.ref_name, '-') }} + id: homebrew-token + env: + HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }} + run: | + if [[ -n "$HOMEBREW_TAP_TOKEN" ]]; then + echo "available=true" >> "$GITHUB_OUTPUT" + else + echo "available=false" >> "$GITHUB_OUTPUT" + fi + + - name: Update Homebrew tap + if: ${{ steps.homebrew-token.outputs.available == 'true' }} + uses: mislav/bump-homebrew-formula-action@f865c8b0dbebd6e263cc06782a0e974c61cf12d2 # v4 + with: + formula-name: bible-cli + formula-path: Formula/bible-cli.rb + homebrew-tap: vmrocha/homebrew-tap + base-branch: main + create-pullrequest: false + create-branch: false + env: + COMMITTER_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }} + GITHUB_TOKEN: ${{ github.token }} + + - name: Report missing Homebrew tap credentials + if: ${{ steps.homebrew-token.outputs.available == 'false' }} + run: | + echo "::warning::HOMEBREW_TAP_TOKEN is not configured; the Homebrew formula was not updated." diff --git a/README.md b/README.md index 57b3f5c..dc5a73f 100644 --- a/README.md +++ b/README.md @@ -164,11 +164,17 @@ text licensing requirements. ## Installation +Install the latest stable release with Homebrew on macOS or Linux: + +```console +brew install vmrocha/tap/bible-cli +``` + Tagged releases ship checksummed single-binary archives for macOS and Linux on Intel/AMD64 and ARM64. Public release downloads require no GitHub account, API token, or GitHub CLI. See the [installation guide](docs/INSTALL.md) for archive -verification, installation, source builds, and Bash, Zsh, Fish, and PowerShell -completion setup. +verification, Homebrew upgrades, source builds, and Bash, Zsh, Fish, and +PowerShell completion setup. ## License diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 976b3b1..f87895a 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,5 +1,22 @@ # Installing Bible CLI +## Homebrew + +Install the latest stable release from the project tap on macOS or Linux: + +```console +brew install vmrocha/tap/bible-cli +``` + +The formula builds from the immutable tagged source archive and installs the +`bible` executable plus Bash, Zsh, and Fish completions. Upgrade or remove it +with the usual Homebrew commands: + +```console +brew upgrade bible-cli +brew uninstall bible-cli +``` + ## Release archives Tagged releases provide single-binary archives for: diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 1754530..2b1e1b4 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -3,6 +3,14 @@ Release tags publish checksummed, self-contained archives through GitHub Actions. A release must come from a reviewed commit on `main`. +## Homebrew credentials + +The `HOMEBREW_TAP_TOKEN` repository secret must contain a fine-grained GitHub +personal access token restricted to `vmrocha/homebrew-tap`, with repository +contents read and write access. The workflow uses this token only to update the +tap after a stable release; the tag-bound `GITHUB_TOKEN` cannot write to a +different repository. + ## Prepare 1. Confirm `main` is clean, synchronized with `origin/main`, and green in CI. @@ -10,7 +18,9 @@ Actions. A release must come from a reviewed commit on `main`. 3. Add `docs/releases/.md` with user-facing release notes. 4. Confirm the installation examples and supported platforms are still accurate. -5. Run `make check` locally. +5. Confirm the `HOMEBREW_TAP_TOKEN` repository secret can write contents in + `vmrocha/homebrew-tap`. +6. Run `make check` locally. Pull-request CI builds all four archives once and executes the matching packaged binary on native macOS and Linux runners. The smoke test verifies checksums, @@ -27,7 +37,10 @@ git push origin v0.1.0 ``` The release workflow reruns `make check`, creates deterministic archives, and -publishes them with `checksums.txt` and the matching release-notes file. +publishes them with `checksums.txt` and the matching release-notes file. For a +stable tag, it then updates `Formula/bible-cli.rb` in +`vmrocha/homebrew-tap` with the new source URL and SHA-256. Prerelease tags do +not update Homebrew. ## Verify @@ -36,6 +49,8 @@ publishes them with `checksums.txt` and the matching release-notes file. 3. Download the archive for the current machine and verify its checksum. 4. Run `bible version` and confirm the version, commit, and build date. 5. Run `bible read "John 3:16"` without network access. +6. Confirm the tap formula references the new tag, then run + `brew update && brew upgrade bible-cli` and `brew test bible-cli`. Never move or reuse a published tag. If publishing fails after a release becomes visible, preserve the tag and diagnose the workflow before taking further diff --git a/website/guide/installation.md b/website/guide/installation.md index 5a20cee..50cb31b 100644 --- a/website/guide/installation.md +++ b/website/guide/installation.md @@ -1,8 +1,18 @@ # Installation -Bible CLI releases are single-binary archives for macOS and Linux on AMD64 and -ARM64. Downloads include checksums for verification and do not require a -GitHub account. +Bible CLI supports Homebrew and single-binary release archives on macOS and +Linux. + +## Homebrew + +Install the latest stable release from the project tap: + +```console +brew install vmrocha/tap/bible-cli +``` + +Homebrew also installs Bash, Zsh, and Fish completions. Use +`brew upgrade bible-cli` to install future stable releases. ## Download a release