Adopt org-infra reusable release workflows across unbound-force repos

[jflowers]

Context

The complytime/org-infra repository provides 30+ reusable GitHub Actions workflows for CI, security scanning, dependency management, and releasing. Several unbound-force repos already consume these workflows for CI (linting, vulnerability scanning, dependency review, CRAP analysis, scheduled scans). However, the release workflow remains fully custom in each repo.

This discussion proposes adopting org-infra's release infrastructure across unbound-force repos, informed by how complytime/complyctl consumes it — and in particular by complyctl PR #742, which is actively adding Homebrew formula publishing to complyctl's release pipeline.

Current State

What unbound-force already delegates to org-infra (5 of 7 workflows)

Workflow	Reusable workflow consumed	Status
ci_checks.yml	reusable_ci.yml (MegaLinter + commitlint)	Adopted
ci_security.yml	reusable_vuln_scan.yml + reusable_security.yml	Adopted
ci_dependencies.yml	reusable_deps_reviewer.yml + reusable_dependabot_reviewer.yml	Adopted
ci_scheduled.yml	reusable_scheduled.yml	Adopted
ci_crapload.yml	reusable_crapload_analysis.yml	Adopted
ci_local.yml	N/A (project-specific build/test/coverage)	Stays local
release.yml	None — 399-line custom pipeline	Migration target

All org-infra references are pinned to commit 0c784711... (v0.7.1).

The unbound-force release pipeline today

The current release.yml is a 3-job, 399-line pipeline:

Job	Lines	What it does
preflight	~120	Tag format validation, semver ordering (sort -V), CI check verification, unreleased commit check, tag creation, macOS signing secret detection
release	~60	GoReleaser with cosign + syft, uploads Homebrew cask/formula templates as release artifacts
sign-macos	~175	Apple Developer ID codesigning, notarization via xcrun notarytool, checksum patching, Homebrew tap push

This requires 8 secrets: GITHUB_TOKEN, MACOS_SIGN_P12, MACOS_SIGN_PASSWORD, MACOS_SIGN_IDENTITY, MACOS_NOTARY_KEY, MACOS_NOTARY_KEY_ID, MACOS_NOTARY_ISSUER_ID, HOMEBREW_TAP_TOKEN.

How complyctl does it (current + PR #742)

complyctl's release workflow is much simpler — two reusable workflow calls plus a new local Homebrew job:

jobs:
  preflight:
    uses: complytime/org-infra/.github/workflows/reusable_release_preflight.yml@<pin>
    with:
      tag: ${{ inputs.tag }}
      ci_checks: '["unit-test", "e2e-test", "integration-test"]'

  release:
    needs: preflight
    uses: complytime/org-infra/.github/workflows/reusable_release_goreleaser.yml@<pin>
    with:
      tag: ${{ needs.preflight.outputs.tag }}

  homebrew:  # NEW in PR #742
    needs: [preflight, release]
    # Downloads source tarball, computes SHA256, templates a
    # source-build Formula, pushes to homebrew-tap via GitHub App token

Key design decision in PR #742: source-build Formula (Homebrew runs go build on the user's machine) instead of a pre-built binary Cask. This eliminates macOS signing entirely — no Apple Developer certificate, no xattr workaround, no notarization.

Comparison: unbound-force vs. complyctl release approach

Aspect	unbound-force (current)	complyctl (with PR #742)
Preflight	Hand-rolled (120 lines)	reusable_release_preflight.yml
GoReleaser	Hand-rolled job (60 lines)	reusable_release_goreleaser.yml
Homebrew model	Pre-built binary Cask + Formula	Source-build Formula
macOS signing	Full codesign + notarization (175 lines)	Not needed
macOS secrets	5 (P12, password, identity, notary key/ID/issuer)	0
Tap auth	PAT (HOMEBREW_TAP_TOKEN)	GitHub App (actions/create-github-app-token)
Total release lines	~399	~165 (with homebrew job)
macOS runner	Yes (macos-latest, ~10x cost)	No

Options

Option A: Full alignment with complyctl pattern

Replace all three jobs with org-infra reusable workflows + source-build Formula.

Changes:

1. Swap preflight job → reusable_release_preflight.yml
2. Swap release job → reusable_release_goreleaser.yml
3. Replace sign-macos + Cask with a simple homebrew job (complyctl PR #742 pattern)
4. Remove homebrew_casks and brews sections from .goreleaser.yaml (handle in workflow)
5. Adopt actions/create-github-app-token (replace HOMEBREW_TAP_TOKEN PAT)
6. Drop 5 macOS signing secrets

Result: ~399 lines → ~80 lines. 0 macOS secrets. No macOS runner costs.

Trade-off: Users who download binaries directly from GitHub Releases (not via Homebrew) will get unsigned darwin binaries — macOS Gatekeeper will prompt them to xattr -dr com.apple.quarantine on first run. Users who install via brew install are unaffected.

Option B: Adopt org-infra for preflight + GoReleaser, keep macOS signing

Delegate the first two jobs to org-infra but keep the sign-macos job custom.

Changes:

1. Swap preflight job → reusable_release_preflight.yml (add small local step for MACOS_SIGN_P12 detection)
2. Swap release job → reusable_release_goreleaser.yml (add follow-up job for cask/formula artifact upload)
3. sign-macos job stays as-is
4. Optionally adopt actions/create-github-app-token for tap push

Result: ~399 lines → ~250 lines. Still 5+ macOS secrets. Still needs macOS runner.

Trade-off: Preserves signed binary Cask experience but keeps maintenance burden. Diverges from complytime org pattern.

Option C: Hybrid — source-build Formula + unsigned pre-built binaries

GoReleaser still produces darwin binaries on GitHub Releases (for users who want direct download), but Homebrew distribution switches to source-build Formula.

Changes:
1-2. Same as Option A (reusable preflight + GoReleaser)
3. Add simple homebrew job (complyctl pattern)
4. Remove sign-macos job entirely
5. Remove homebrew_casks section from .goreleaser.yaml, keep brews as skip_upload: true or remove

Result: ~399 lines → ~100 lines. 0 macOS secrets. Darwin binaries still in Releases (unsigned).

Trade-off: Darwin binaries exist on Releases for manual download but aren't signed. Homebrew users get source-build (no signing needed). Middle ground.

Recommendation

Option A (full alignment) is the recommended target state, with phased adoption:

Phase 1 — Swap preflight + GoReleaser (low risk, immediate value)

• Replace hand-rolled preflight with reusable_release_preflight.yml
• Replace hand-rolled GoReleaser job with reusable_release_goreleaser.yml
• Keep sign-macos temporarily
• Estimated effort: small, mostly workflow YAML changes

Phase 2 — Switch to source-build Formula (after complyctl PR #742 merges)

• Replace sign-macos + Cask with complyctl-style homebrew job
• Adopt actions/create-github-app-token
• Remove 5 macOS secrets from repo settings
• Estimated effort: medium, but net-negative lines of code

Phase 3 — Evaluate reusable Homebrew workflow in org-infra

• If both complyctl and unbound-force use the same Homebrew publishing pattern, propose extracting it as reusable_release_homebrew.yml in org-infra
• Benefits any Go project in either org

Rationale

1. Maintenance cost: 5 macOS signing secrets + Apple Developer certificate renewal + macOS runner costs are significant overhead for a CLI tool that most users install via Homebrew.
2. Org consistency: Following the complytime org pattern means shared tooling improvements benefit everyone.
3. Source-build is the Homebrew norm: Most Homebrew formulae for Go/Rust CLIs build from source. It's expected and Homebrew auto-installs the Go toolchain.

Open Questions

1. Is the signed Cask experience important enough to justify the maintenance burden? Are there users who specifically need notarized macOS binaries (e.g., enterprise environments with strict Gatekeeper policies)?

2. GitHub App for unbound-force org: Do we already have one, or do we need to create one for the actions/create-github-app-token pattern? The complyctl PR uses APP_ID + PRIVATE_KEY secrets scoped to homebrew-tap.

3. Other repos: Should replicator, dewey, or gaze adopt the same release workflow pattern? If so, the case for extracting a reusable Homebrew workflow into org-infra gets stronger.

4. Coordination with complytime: Should we coordinate with the complyctl PR #742 author about extracting the Homebrew publishing step into org-infra as a reusable workflow once the pattern is proven?

5. Timing: Should Phase 2 block on complyctl PR #742 merging (to learn from any issues they hit), or can we move independently?

References

• complytime/org-infra — reusable workflows
• complyctl PR #742 — Homebrew formula + macOS binaries for complyctl
• complyctl release.yml — current complyctl release workflow
• unbound-force release.yml — current unbound-force release workflow
• org-infra reusable_release_preflight.yml — preflight validation
• org-infra reusable_release_goreleaser.yml — GoReleaser orchestration

[jflowers]

Option A deep-dive: full adoption plan

Assuming we proceed with Option A (full alignment with complyctl/org-infra + source-build Formulae), here is the detailed plan covering all four repos, uf setup/uf doctor impacts, and the user migration path.

---

Critical issue: Cask-to-Formula migration for existing users

Homebrew resolves brew install <tap>/<name> to Formula first, Cask second (documented in our own openspec/changes/linux-cross-platform-install/design.md). But when a user already has a Cask installed and we replace it with a Formula:

• brew upgrade does not silently convert a Cask to a Formula. The old Cask stays installed and becomes orphaned once the Cask file is removed from the tap.
• A fresh brew install <tap>/<name> may fail with "Cask already installed" or conflicting binary symlinks.
• Users must explicitly uninstall the Cask before installing the Formula.

This is the single biggest UX risk in this migration and drives most of the sequencing below.

---

Scope: 4 repos with near-identical release pipelines

Repo	Binary	Current dist	darwin arches	Cask deps	Notes
unbound-force	unbound-force + uf symlink	Cask and Formula (both binary-based)	amd64+arm64	cask: dewey	RPM via nfpms, uf alias
dewey	dewey	Cask only	amd64+arm64	cask: ollama-app	RPM via nfpms
gaze	gaze	Cask only	amd64+arm64	none	has unsigned-cask fallback job
replicator	replicator	Cask only	arm64 only	none	source-build would improve amd64 coverage

All 4 use the same custom preflight -> release -> sign-macos pipeline and the same 6 secrets (MACOS_SIGN_* x5 + HOMEBREW_TAP_TOKEN).

---

Per-repo changes (repeated 4x with minor variations)

A. Release workflow (.github/workflows/release.yml)

Replace the 3-job custom pipeline with:

jobs:
  preflight:
    uses: complytime/org-infra/.github/workflows/reusable_release_preflight.yml@<pin>
    with:
      tag: ${{ inputs.tag }}
      ci_checks: '["Build and Test", "Standardized CI / Run linters"]'  # varies per repo

  release:
    needs: preflight
    uses: complytime/org-infra/.github/workflows/reusable_release_goreleaser.yml@<pin>
    with:
      tag: ${{ needs.preflight.outputs.tag }}

  homebrew:
    needs: [preflight, release]
    if: needs.preflight.outputs.tag != ''
    runs-on: ubuntu-latest
    steps:
      - name: Generate tap token
        uses: actions/create-github-app-token@<pin>
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.PRIVATE_KEY }}
          repositories: homebrew-tap
          owner: unbound-force
      - name: Publish Formula
        # complyctl PR #742 pattern: download source tarball,
        # compute sha256, template source-build Formula, push to tap

Deleted: the entire sign-macos job (~175 lines), macOS secret detection step.

Per-repo ci_checks values:

• unbound-force: ["Build and Test", "Standardized CI / Run linters"]
• dewey: ["build-and-test", "MegaLinter"]
• gaze: ["Unit + Integration Tests (Go 1.24)", "Unit + Integration Tests (Go 1.25)", "MegaLinter"]
• replicator: ["Build and Test"]

B. GoReleaser config (.goreleaser.yaml)

• Remove homebrew_casks: section entirely (Homebrew handled in workflow).
• Remove brews: section (or repurpose if GoReleaser's source-build Formula support is viable -- but matching complyctl's inline heredoc pattern is more consistent).
• Keep builds:, archives:, sboms:, signs: (cosign), nfpms: (RPM where applicable). Binaries still ship to GitHub Releases for direct download / RPM / go install.
• Note: replicator currently only builds darwin/arm64 -- its source-build Formula will compile on any arch, actually improving Intel Mac and Linux coverage.

C. homebrew-tap repo restructuring

• Add Formula/{dewey,gaze,replicator}.rb as source-build Formulae.
• Convert existing Formula/unbound-force.rb from binary-download to source-build.
• Delete Casks/*.rb (all four) on cutover. See sequencing below.
• Dependency chain:
  • unbound-force Formula currently declares depends_on cask: "dewey". This must change to depends_on "dewey" (formula dep) or be removed entirely.
  • dewey Cask currently declares depends_on cask: "ollama-app". A Formula depending on a Cask is fragile/unusual. Likely best to drop this Homebrew-level dep and rely on uf setup's explicit installOllama() (which already handles macOS cask / Linux formula per existing design decision D6).

D. Secrets cleanup (per repo)

• Remove 5 secrets: MACOS_SIGN_P12, MACOS_SIGN_PASSWORD, MACOS_SIGN_IDENTITY, MACOS_NOTARY_KEY, MACOS_NOTARY_KEY_ID, MACOS_NOTARY_ISSUER_ID.
• Replace HOMEBREW_TAP_TOKEN (PAT) with GitHub App (APP_ID + PRIVATE_KEY) scoped to homebrew-tap write, following complyctl PR #742 pattern.

---

uf setup / uf doctor changes

Good news: the install command string is unchanged -- brew install unbound-force/tap/<x> works identically for Formulae. So installViaBrew() at internal/setup/setup.go:251 and homebrewInstallCmd() at internal/doctor/environ.go:261 need no syntactic change.

What does need work:

1. Cask-to-Formula migration detection (new, most important)

   • In uf doctor and/or uf setup, detect an existing Cask install (brew list --cask <name>) and offer to migrate: brew uninstall --cask <name> && brew install <tap>/<name>.
   • Decision needed: auto-migrate with confirmation prompt, or just print the commands?
   • New logic + tests in internal/doctor/ and/or internal/setup/.

2. Ollama dependency handling

   • installOllama() already correctly handles macOS cask / Linux formula (design decision D6 at openspec/changes/linux-cross-platform-install/design.md:136).
   • If dewey's Formula drops the depends_on cask: "ollama-app" declaration, uf setup's explicit ollama install becomes the sole guarantor of ollama presence. Verify install ordering: ollama before dewey.

3. Build time expectations

   • Source builds compile with Go (Homebrew auto-installs go as a build dep). First install takes minutes instead of seconds.
   • uf setup progress messaging should set expectations -- consider a note like "compiling from source, this may take a few minutes" or detect long-running brew installs.

4. .goreleaser.yaml cask dependency declaration

   • In unbound-force's .goreleaser.yaml:123, the line - cask: dewey must be removed (since the homebrew_casks: section itself is deleted).

5. Provenance / path detection

   • Any doctor code that checks /opt/homebrew/Caskroom/... vs /opt/homebrew/Cellar/... would break. Needs a grep pass to confirm -- preliminary research suggests doctor uses LookPath() (binary presence), not filesystem path detection, so this is likely a non-issue.

6. Tests

   • internal/setup/setup_test.go and doctor tests assert on brew command strings. Update expectations; add migration-path test cases (cask detected -> migration offered).

---

User migration experience

Today: brew upgrade pulls a new signed binary in seconds.

After cutover -- three user cohorts:

Cohort	Without migration help	With migration help (uf doctor)
Existing Cask users (most users)	brew upgrade silently does nothing or warns; old Cask orphaned; possible symlink conflict on next brew install	uf doctor detects Cask, prints/runs brew uninstall --cask X && brew install <tap>/X
Existing Formula users (unbound-force only, Linux users)	brew upgrade works but now compiles from source (slower first time, needs Go)	Same, with expectation-setting message
New users	brew install <tap>/X -> source build (slow first time, Homebrew auto-installs Go)	Docs explain build-from-source; uf setup handles everything

Recommended migration mechanics:

1. Ship Formulae in a coordinated release across all 4 repos (dewey first -- it's a dependency of unbound-force).
2. Add a one-time migration helper to uf doctor/uf setup that detects casks and offers to migrate.
3. Publish release notes + update docs/INSTALLATION.md with the manual path:

   brew uninstall --cask unbound-force dewey gaze replicator 2>/dev/null
   brew install unbound-force/tap/unbound-force
   # uf setup handles dewey, gaze, replicator

4. Post an org-level "Announcements" discussion.
5. After ~2 release cycles, confirm old Cask files can be permanently removed from the tap (they may already be deleted at cutover, depending on decision below).

---

Suggested sequencing

This spans 4 repos, changes signatures/tests, and touches CI + release -- it warrants Speckit (cross-repo, >=3 stories per AGENTS.md).

Phase	Scope	Risk	Description
0. Spec + design	unbound-force (this repo)	None	Speckit spec covering org-infra release adoption + cask-to-formula migration + uf setup/doctor changes. Resolve ollama/dewey dep and migration UX in design.
1. Swap preflight + GoReleaser	All 4 repos	Low	Replace hand-rolled preflight + GoReleaser jobs with reusable_release_preflight.yml + reusable_release_goreleaser.yml. Keep sign-macos temporarily. Ship one release cycle to verify.
2. Formula cutover	dewey first, then gaze/replicator/unbound-force	Medium	Add source-build Formulae. Remove sign-macos jobs. Remove Casks from tap. Secret cleanup. GitHub App creation.
3. uf setup/doctor migration	unbound-force	Low	Migration detection helper + tests + docs. Can ship alongside or just after Phase 2.
4. (Optional) Reusable Homebrew workflow	org-infra	Low	If both complyctl and unbound-force use the same Homebrew publishing pattern, propose extracting as reusable_release_homebrew.yml in org-infra.

---

Open questions to resolve before spec

1. Migration aggressiveness: Should uf doctor/uf setup automatically run brew uninstall --cask && brew install (with confirmation prompt), or just print the commands? Auto is friendlier but touches user's installed software.

2. Casks: delete or transition? Clean cut (delete Casks on cutover day) vs. keep Casks for one release cycle with a deprecation notice in the Cask description. Clean cut is simpler but harder on existing users who don't read release notes.

3. dewey -> ollama dependency: Drop the Homebrew-level depends_on for ollama and rely on uf setup's explicit installOllama() instead? A Formula depending on a Cask (ollama-app) is fragile across platforms. The cleaner path may be no Homebrew dep + uf setup guarantees ollama.

4. GoReleaser brews: vs. inline heredoc: complyctl PR #742 uses an inline heredoc Formula template in the workflow (not GoReleaser's brews:). Match that exactly for org consistency and future reusable-workflow extraction? Or use GoReleaser's built-in Formula generation?

5. Unsigned darwin binaries on Releases page: GoReleaser still uploads unsigned darwin tarballs to GitHub Releases (for direct download). OK with Gatekeeper xattr prompt for manual-download users, given Homebrew users build from source?

6. replicator arm64-only: Expand replicator's GoReleaser to build darwin/amd64 too (now cheap without signing), or leave as-is since source-build Formula covers all archs anyway?

7. Spec tier: Confirm Speckit (cross-repo umbrella) vs. one OpenSpec per repo. I lean Speckit given the coordinated tap changes and dependency ordering.

[hbraswelrh]

@jflowers some thoughts on your Option A comment.

1. I think printing to the terminal would suffice and also help with split-terminal following along. Then, users would be able to run the commands in the interactive terminal rather than spending tokens when they could copy and paste.
2. Personally I vote for deleting the casks.
3. 👏 I think it would be great to drop the direct depends_on ollama cask. Your suggested no Homebrew dep + uf setup sounds good.
4. GoReleaser's built-in Formula generation would be easier to maintain and validate as fields are deprecated, but according to PR 742 in complyctl the brews: field will be fully deprecated in v2.16. However, this would be a relevant discussion topic for the potential reusable homebrew workflow in org-infra.
5. No opinion at the moment.
6. The benefits and drawbacks may need to be weighed more in this scenario. What's easier to maintain with upstream? I think it's a safer bet to expand to build darwin/amd64.
7. No opinion at the moment.

[sonupreetam]

@jflowers & @hbraswelrh The discussion looks neat. Option A was actually the one I was suggesting in our messages to separate homebrew job and check the homebrew job in both uf and complypack to have consistency across the whole release process in org-infra using the reusables.