Homebrew tap trust will become default — update install docs and release notes ahead of 5.2.0

[leggetter]

Summary

Homebrew is making HOMEBREW_REQUIRE_TAP_TRUST the default in 5.2.0 or 6.0.0, whichever comes first. Once that lands, formulae from untrusted third-party taps are ignored unless the user explicitly trusts the tap.

The Hookdeck CLI is distributed on macOS via the third-party tap hookdeck/homebrew-hookdeck (both hookdeck stable and hookdeck-beta), so every documented brew install hookdeck/hookdeck/… path is affected.

Current Homebrew warning (verbatim):

Warning: The following taps are not trusted:
  …
  hookdeck/hookdeck
  …

Homebrew will ignore formulae, casks and commands from these taps when
`HOMEBREW_REQUIRE_TAP_TRUST` is set.
This will become the default in Homebrew 6.0.0 or 5.2.0, whichever comes first.

Timeline

• Homebrew 5.0.0 → 2025-11-12
• Homebrew 5.1.0 → 2026-03-10
• Homebrew 5.2.0 → no earlier than 2026-06-10 (per Homebrew's deprecation notes for the master→main migration). ~4-month cadence → realistically June–July 2026.
• Homebrew 6.0.0 → no announced date.

5.2.0 is the likely trigger. We have roughly 4–8 weeks before users start hitting it.

Impact

Users

• New users following README install instructions (brew install hookdeck/hookdeck/hookdeck / hookdeck-beta) will silently get nothing until they trust the tap.
• Existing installations keep working, but brew upgrade, brew reinstall, and brew bundle from the tap break.
• CI / onboarding scripts / Dockerfiles / Brewfiles that install Hookdeck CLI break.
• Beta channel is affected identically — same tap.

Maintainers

• README install instructions become wrong overnight.
• GoReleaser flow itself is unaffected (we still publish to our own tap); the change is on the consumer side.

The trust command

Homebrew's own warning output now documents the exact syntax. For Hookdeck CLI users:

brew trust --formula hookdeck/hookdeck/hookdeck hookdeck/hookdeck/hookdeck-beta

(Users only need the formula they actually use; the combined form above covers both stable and beta.)

The env var also works today as an opt-in for users who want to try the new behavior before the default flips:

export HOMEBREW_REQUIRE_TAP_TRUST=1

What we need to do

• Update README install instructions (README.md lines ~78–90, ~1467–1471, ~1509–1513) to include the brew trust --formula step alongside the install command.
• Add a heads-up to the next release notes (the hookdeck-cli-release skill drives this) so users see it in brew upgrade output — include the exact brew trust command.
• Pin a Homebrew 5.2.0 release watch — track Homebrew/brew releases so the doc update lands before the flip, not after.
• Update the README troubleshooting section (around line 1213, currently the cask/formula migration note) with a new entry for tap-trust failures.
• Audit any external docs/marketing pages outside this repo that recommend brew install hookdeck/hookdeck/….
• Check whether test-homebrew-build.yml CI will need HOMEBREW_NO_REQUIRE_TAP_TRUST=1 once the default flips. Several upstream taps (e.g. Anspar-Org/homebrew-anspar#85) have already hit this with brew doctor / bottle-build steps; our workflow runs brew install goreleaser and a test install script, both of which may be affected.

Longer-term: homebrew-core submission

Tracked in #295. Initial feasibility review found this is more tractable than first assumed:

• Notability bar (≥225 stars for self-submission) is clear — we have 358.
• The codebase is pure Go (no actual CGO usage despite the CGO_ENABLED=1 flag in .goreleaser/mac.yml); the formula will be near-trivial.
• Apache-2.0 license is DFSG-compatible.
• Bottles are auto-built by BrewTestBot post-merge; version bumps are bot-managed.

Beta still needs to live in our third-party tap (homebrew-core rejects pre-releases), so the brew trust step above remains necessary for beta users even after a successful core submission.

Note: cask migration + code signing is tracked separately and is orthogonal to tap-trust (casks from third-party taps face the same trust requirement).

Open questions

• Whether Homebrew will print an actionable hint at install time once the default flips, or silently skip the formula.
• Whether brew trust syntax remains stable through 5.2.0 GA (it's already shown in current 5.1.x warning output, so likely yes).

References

• Homebrew 5.0.0 release notes
• Homebrew 5.1.0 release notes
• Homebrew::EnvConfig API docs — HOMEBREW_REQUIRE_TAP_TRUST definition
• Homebrew Taps docs