Migrate to Homebrew cask installation and sign your binaries with an Apple Developer certificate

[leggetter]

Summary

To properly support cask distribution, the macOS binaries must be signed and notarized with an Apple Developer certificate. This issue tracks the requirements, implementation steps, and migration strategy.

---

1. Validation: Signing required for cask

Yes. Signing (and notarization) is required for distributing the Hookdeck CLI via a Homebrew cask.

• Gatekeeper: Casks install pre-built binaries. macOS applies quarantine to downloaded files; unsigned/unnotarized binaries trigger Gatekeeper and can be blocked (e.g. "damaged and cannot be opened").
• Homebrew policy: Homebrew is removing --no-quarantine for casks. Support for casks that fail Gatekeeper checks ends September 1, 2026.
• Apple Silicon: Native arm64 code effectively requires a valid signature to run.
• Current state: The cask is disabled in .goreleaser/mac.yml with a TODO: "Cask distribution causes Gatekeeper issues with unsigned binaries."

---

2. Requirements

Apple Developer setup

• Enroll in the Apple Developer Program ($99/year)
• Create a Developer ID Application certificate (.cer → import to Keychain → export as .p12 with password)
• Create an App Store Connect API key (.p8) for notarization

Build pipeline (GoReleaser)

• Add notarize block to .goreleaser/mac.yml. The cross-platform (quill) method works for binaries (no .app/DMG).
• Sign darwin binaries (amd64 + arm64) before archiving; release assets used by both formula and cask will then be signed.
• Configure CI secrets: MACOS_SIGN_P12, MACOS_SIGN_PASSWORD, MACOS_NOTARY_KEY, MACOS_NOTARY_KEY_ID, MACOS_NOTARY_ISSUER_ID (base64-encoded where applicable).

Cask and tap

• Uncomment and adjust homebrew_casks in .goreleaser/mac.yml. Cask goes in Casks/ (default); formula stays in Formula/.
• Ensure the tap token has contents: write for hookdeck/homebrew-hookdeck (default GITHUB_TOKEN may not have access).
• Do not use xattr / --no-quarantine workarounds in the cask; proper signing is the correct approach.

Tests and docs

• Re-enable cask validation and install tests in test-scripts/test-homebrew-build.sh and test-homebrew-build.yml.
• Update README: recommend cask for macOS once signed; keep formula as alternative during migration.
• Keep "Binary Already Exists" troubleshooting (uninstall formula → install cask).

---

3. Migration strategy: support formula during transition

• Phase 1: Implement signing + notarization. Re-enable cask. Publish both formula and cask.
• Phase 2: Document cask as recommended for macOS. Keep formula available.
• Phase 3: Overlap period of 6–12 months (or two major versions) where both are supported.
• Phase 4: Add deprecate! to the formula with replacement_cask: "hookdeck/hookdeck/hookdeck", then optionally stop publishing the formula.

User migration: Existing formula users can run brew uninstall hookdeck then brew install --cask hookdeck/hookdeck/hookdeck when moving to the cask.

---

4. Workaround for users (temporary)

Until signing is implemented, users who hit Gatekeeper with an unsigned install can bypass quarantine by running:

xattr -d com.apple.quarantine $(which hookdeck)

This should be documented in troubleshooting guides only as a temporary workaround. Proper fix is code signing.

---

References

• GoReleaser: Notarize
• GoReleaser: Homebrew Casks
• Homebrew: Removing --no-quarantine (#20755)
• Apple: Signing your apps for Gatekeeper