Submit `hookdeck` to homebrew-core for the stable channel

[leggetter]

Motivation

Spun out of #294. With Homebrew making HOMEBREW_REQUIRE_TAP_TRUST the default in 5.2.0/6.0.0, every documented brew install hookdeck/hookdeck/hookdeck path will require an explicit brew trust step from end users.

Landing hookdeck in homebrew-core sidesteps tap-trust entirely for the stable channel — users just brew install hookdeck. Beta stays in our third-party tap regardless (homebrew-core doesn't accept pre-releases).

Current status (2026-06-03)

Phase 1 (Preparation) — complete on branch homebrew-core-prep:

Commit	Change
203bf40	chore(release): disable CGO for darwin builds in mac.yml
cff3184	docs: regenerate REFERENCE.md for connection pause/unpause command
3d369ce	feat(completion): output completion script to stdout

Phase 2 (Formula draft) — complete:

Formula drafted at /opt/homebrew/Library/Taps/homebrew/homebrew-core/Formula/h/hookdeck.rb:

class Hookdeck < Formula
  desc "Receive events and webhooks on localhost with history and replay"
  homepage "https://hookdeck.com"
  url "https://github.com/hookdeck/hookdeck-cli/archive/refs/tags/v2.1.1.tar.gz"
  sha256 "e5bc6cdb05a870cb8b595b49761d6789bc1b5553174ede5ba7c0ea06570df8fc"
  license "Apache-2.0"
  head "https://github.com/hookdeck/hookdeck-cli.git", branch: "main"

  livecheck do
    url :stable
    strategy :github_latest
  end

  depends_on "go" => :build

  def install
    ldflags = "-s -w -X github.com/hookdeck/hookdeck-cli/pkg/version.Version=#{version}"
    system "go", "build", *std_go_args(ldflags:)

    generate_completions_from_executable(bin/"hookdeck", "completion",
                                         shell_parameter_format: "--shell=",
                                         shells:                 [:bash, :zsh])
  end

  test do
    assert_match version.to_s, shell_output("#{bin}/hookdeck --version")
  end
end

brew audit --strict --new --online hookdeck passes clean (exit 0, no warnings).

Phase 3 (Submission) — blocked on release sequencing. See below.

Critical sequencing dependency

The drafted formula uses generate_completions_from_executable with the new stdout-based completion output. v2.1.1's tarball doesn't contain this change — it ships the old file-writing behavior. So brew install --build-from-source against v2.1.1 would fail at the completion-generation step.

Required order:

1. Merge homebrew-core-prep branch to main (PR pending)
2. Cut next stable release that rolls in both:
   • Existing v2.1.2-beta.1 functionality (being promoted to stable rather than continuing the beta line)
   • The changes from this branch (CGO cleanup, completion stdout)
3. Update homebrew-core formula's url + sha256 + version to point at the new release
4. Open homebrew-core PR

Breaking-change callout for release notes

Commit 3d369ce changes hookdeck completion --shell <shell> behavior:

• Before: writes hookdeck-completion.bash (or .zsh) to the current directory and prints multi-step setup instructions
• After: writes the completion script to stdout; no file created, no instructions

Anyone scripting against the old behavior is affected. Release notes for the next stable release must call this out explicitly. The hookdeck-cli-release skill handles release-note drafting — it should pick this up automatically from the conventional commit, but worth verifying when cutting.

Updated work breakdown

Phase 1 — Preparation ✅

• Verify and remove vestigial CGO_ENABLED=1 from .goreleaser/mac.yml. Smoke-test confirmed: build works, version-string injection intact, no behavior regression.
• Confirm completions and version-string injection. Discovered that hookdeck completion --shell bash writes a file rather than outputting to stdout — non-standard for Cobra CLIs and incompatible with Homebrew's generate_completions_from_executable. Fixed upstream as part of this phase.
• Decide on test do block. Using hookdeck --version (cobra built-in, no network calls, validates ldflag injection).
• NEW: Output completion script to stdout. Updated pkg/cmd/completion.go, scripts/completions.sh, README.md, and regenerated REFERENCE.md.

Phase 2 — Formula authoring ✅

• Draft Formula/h/hookdeck.rb based on goreleaser/gh patterns. Includes livecheck :github_latest, source build via std_go_args, completion install via generate_completions_from_executable (with shell_parameter_format: "--shell=" and shells: [:bash, :zsh]), and a network-free --version test.
• Audit pass: brew audit --strict --new --online hookdeck → clean.
• Full brew install --build-from-source test — blocked until we cut a release containing the completion change (otherwise install fails at completion-gen step).
• Fork Homebrew/homebrew-core to a personal/org account. Add as remote when ready to submit.

Phase 3 — Submission (blocked on releases)

• Merge PR for homebrew-core-prep branch.
• Cut next stable release that rolls v2.1.2-beta.1's functionality and this branch's changes into a single GA. No new beta cut — beta line is being promoted, not continued.
• Update formula url + sha256 + version for the stable release.
• Push formula branch to Homebrew/homebrew-core fork.
• Open PR to Homebrew/homebrew-core titled hookdeck X.Y.Z (new formula) (squashed single commit).
• Respond to maintainer review (typically nits around desc length, test do, livecheck).
• Bottles are built by BrewTestBot after merge — nothing for us to do there.

Phase 4 — Migration & comms (after homebrew-core merge)

Tracked separately in #297 — covers in-repo README updates, the version-update model documentation, tap_migrations.json for the existing tap, the decision about whether to keep/drop the stable hookdeck formula in the tap, hookdeck.com docs, marketing/onboarding updates, and release-notes announcement. Kept separate from #295 because the work spans different teams (docs, marketing) and shouldn't start until the homebrew-core PR is actually accepted.

Ongoing maintenance after acceptance

• BrewTestBot auto-detects new GitHub releases via livecheck :github_latest and opens version-bump PRs. Hands-off in the common case.
• Lag from upstream release → core formula updated: usually hours to a day or two.
• Occasional touch-ups needed if Go toolchain conventions in core change.

Tradeoffs (already discussed in #294)

• Release cadence: core lags our tap by hours/days, not minutes. Acceptable for most users.
• Beta stays in our tap. Beta users still need brew trust after the 5.2.0 default flip.
• Less control over caveats / install scripts / completions handling — all go through homebrew-core maintainer review.

References

• Homebrew Acceptable Formulae
• Homebrew Formula Cookbook
• goreleaser formula in homebrew-core — pattern to follow
• gh formula in homebrew-core — more complex Go example
• Parent issue: Homebrew tap trust will become default — update install docs and release notes ahead of 5.2.0 #294
• Existing beta release whose functionality rolls into the next stable: v2.1.2-beta.1