From ece7f14e35f03bd0bb1c12fdbdb8868dddadaf37 Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Wed, 19 Aug 2026 10:10:36 -0700 Subject: [PATCH] Document Homebrew tap install and notify it on release MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the `brew install cortexproject/tap/cortextool` install path to the README, a RELEASE.md section covering the tap's self-update and the optional `HOMEBREW_TAP_TOKEN`, and a `notify-tap` job that sends a `repository_dispatch` so the tap bumps within a minute instead of waiting for its 6-hourly schedule. The tap's formula builds from source, so it covers Linux arm64 too — we publish no `linux/arm64` binary, so a binary-based formula could not have. `.goreleaser.yml` is unchanged and no release artifacts change. `notify-tap` is `continue-on-error`, has `permissions: {}`, and is skipped when the token is unset, so it cannot fail a release; the tap's schedule is the fallback. Refs #65 Signed-off-by: Charlie Le --- .github/workflows/release.yml | 24 ++++++++++++++++++++++++ CHANGELOG.md | 3 +++ README.md | 23 +++++++++++++++++++++++ RELEASE.md | 35 +++++++++++++++++++++++++++++++++++ 4 files changed, 85 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e56d2cef6..243288779 100644 --- a/.github/workflows/release.yml +++ b/.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 - diff --git a/CHANGELOG.md b/CHANGELOG.md index 81e427405..13f2e4bd4 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index c32df9b4b..acaf4d020 100644 --- a/README.md +++ b/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. diff --git a/RELEASE.md b/RELEASE.md index c40edd480..8cf58abef 100644 --- a/RELEASE.md +++ b/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.