Document Homebrew tap install and notify it on release

.github/workflows/release.yml

@@ -47,3 +47,27 @@ jobs:
           args: release --release-notes=/tmp/release-notes.md --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  notify-tap:
+    name: Notify Homebrew tap
+    needs: release
+    runs-on: ubuntu-latest
+    # Purely an optimisation: cortexproject/homebrew-tap also polls for new
+    # releases every 6 hours, so this only shortens the wait to about a minute.
+    # It must never be able to fail a release that has already published images.
+    continue-on-error: true
+    permissions: {}
+    env:
+      # The `secrets` context is not available in `if:`, so route the gate
+      # through a job-level env var.
+      GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+    steps:
+      - name: Send repository_dispatch to cortexproject/homebrew-tap
+        if: env.GH_TOKEN != ''
+        run: |
+          TAG=${GITHUB_REF#refs/tags/}
+          # `gh api -f` has no well-defined syntax for nested objects, so build
+          # the body with jq and pipe it in.
+          jq -n --arg tag "${TAG}" \
+            '{event_type: "cortextool-release", client_payload: {tag: $tag}}' |
+            gh api --method POST /repos/cortexproject/homebrew-tap/dispatches --input -

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 Order should be `CHANGE`, `FEATURE`, `ENHANCEMENT`, and `BUGFIX`
 
+## unreleased
+* [FEATURE] Publish `cortextool` via the `cortexproject/homebrew-tap` Homebrew tap #65
+
 ## v0.21.1
 * [BUGFIX] Fix `rules lint`/`prepare`/`check` failing with "cortex address is required" #61
 

README.md

@@ -18,6 +18,29 @@ The various binaries are available for macOS, Windows, and Linux.
 
 Refer to the [latest release](https://github.com/cortexproject/cortex-tools/releases) for installation instructions on these.
 
+## Homebrew
+
+`cortextool` is available from the [`cortexproject/homebrew-tap`](https://github.com/cortexproject/homebrew-tap) tap:
+
+```bash
+brew install cortexproject/tap/cortextool
+```
+
+The formula builds from source, so Homebrew installs Go as a build dependency and
+the install takes about a minute. Building rather than downloading is what lets
+it cover Linux arm64, which we publish no binary for: macOS arm64, macOS x86_64,
+Linux arm64 and Linux x86_64 are all supported.
+
+Homebrew 6 and newer refuse to load formulae from an untrusted third-party tap.
+Passing the fully-qualified name above is enough on its own; to install by short
+name instead, trust the tap first:
+
+```bash
+brew tap cortexproject/tap
+brew trust cortexproject/tap
+brew install cortextool
+```
+
 ## cortextool
 
 This tool is designed to interact with the various user-facing APIs provided by Cortex, as well as, interact with various backend storage components containing Cortex data.

RELEASE.md

@@ -32,3 +32,38 @@ The workflow uses two repository secrets:
 - `QUAY_PASSWORD`
 
 `GITHUB_TOKEN` is provided automatically by Actions.
+
+`HOMEBREW_TAP_TOKEN` is **optional** — see below.
+
+## Homebrew tap
+
+`cortextool` is published through [`cortexproject/homebrew-tap`](https://github.com/cortexproject/homebrew-tap).
+Nothing in this repository builds or pushes the formula, and `.goreleaser.yml`
+does not know about Homebrew: **a release needs no Homebrew-specific steps.**
+
+The tap updates itself. Its `Update cortextool` workflow reads our latest
+release, rewrites the version and `sha256` with `brew bump-formula-pr`, then
+builds the candidate from source and `brew test`s it on macOS arm64, macOS
+x86_64, Linux x86_64 and Linux arm64, committing only if all four pass. It runs
+on a 6-hourly schedule, so a new release is picked up within 6 hours with no
+action from us.
+
+The `notify-tap` job in `release.yml` just shortens that wait: it sends a
+`repository_dispatch` so the bump starts within about a minute. The job is
+`continue-on-error: true` and is skipped entirely when `HOMEBREW_TAP_TOKEN` is
+unset, so **it can never fail a release** — if it is missing or its token has
+expired, the tap's schedule still picks the release up.
+
+`HOMEBREW_TAP_TOKEN` should be a fine-grained PAT scoped to
+`cortexproject/homebrew-tap` only, with `Contents: write`.
+
+To bump the tap by hand — after a retag, or if you would rather not wait:
+
+```bash
+gh workflow run "Update cortextool" --repo cortexproject/homebrew-tap
+gh workflow run "Update cortextool" --repo cortexproject/homebrew-tap -f tag=v0.21.1
+```
+
+Note that retagging a release changes the checksums under a fixed version, which
+users see as `SHA256 mismatch` until they `brew update` again. Prefer publishing
+a new patch tag.