brew-publish

name	brew-publish
description	Operate the socket-release Homebrew tap flow - the binary-download formula model, tap repo layout, formula bumps tied to published releases, and sha256 verification against the release's own checksums.txt. Use when bumping a Homebrew formula or standing up a tap for a Socket CLI.

Homebrew tap (binary-download formula)

Model: no bottles, no source build - the formula downloads the release's prebuilt per-platform tarballs by EXACT releases/download/v<version>/<asset> URL (never latest) and pins the sha256 the release's own checksums.txt vouched for. brew-publish NEVER hashes an asset itself; the manifest is the authority.

Tap layout (one-time, manual)

The tap repo (SocketDev/homebrew-socket) carries an unsharded Formula/ dir plus a README documenting tap trust:

export HOMEBREW_REQUIRE_TAP_TRUST=1
brew trust SocketDev/socket

The exact layout is modeled by release-kit/examples/brew-cli/tap-fixture/ in sauce. Creating the tap repo is a human act (repo creation rights) - note it plainly; there is no script.

Bump cycle

Prerequisite: the release is CUT - tag on origin, release published (not draft), all four platform assets uploaded, checksums.txt attached (the github-release flow produces all of this).

node scripts/socket-release/brew-publish.mts --tag vX.Y.Z            # dry-run plan
node scripts/socket-release/brew-publish.mts --tag vX.Y.Z --apply    # commit the bump

The tool refuses, in order, with exit 1 and zero writes: a tag not on origin (it never creates tags), a draft/missing release, a missing templated asset, a missing/incomplete checksums.txt. An identical formula is a no-op ("already reads ", exit 0). --apply commits the formula DIRECT to the tap default branch with a GitHub-signed API commit (never a PR - the version-bump-PR shape is guard-blocked), then re-reads the tap: the committed bytes must parse back to the desired formula, or it exits 1 saved-state-unproven.

From CI, brew-publish.yml runs on release: published (or manual dispatch with tag + publish: true) and mints a per-run App token via the ./.github/actions/socket-release-app-token composite from the org-wide App credentials - org secrets are enterprise-wide; never treat them as missing setup or a human task.

sha256 verification

The formula's four sha256s come from checksums.txt - verify the chain, never re-hash locally as authority:

gh release download vX.Y.Z --pattern checksums.txt --output -

Both grammars count: plain <hex> <name> (shasum) and sha256: <hex> <name>, the kit release tail's form. A duplicate filename with differing hex is a hard refusal. After a bump, spot-check one platform: the url in Formula/<name>.rb must name the exact v<version> download path and its sha256 must equal the manifest line for that asset.

Auth moments (gate, never improvise)

• Local --apply uses ambient gh auth: if gh auth status fails, the operator runs gh auth login (browser) - render the gate.
• Manual audits run on an operator Mac: brew style / brew audit against the tap (deferred from CI).