Add brew sync-tap-workflows developer command

[Copilot]

• Fix transforms not applying (psych-pure duck typing, YAML 1.1 on: key)
• Add end-of-run summary of synced paths
• Sync tests.yml and publish.yml for --formula (single source of truth via TapNew):
  • Minimally touch tap-new.rb: extract two class methods TapNew.render_tests_yml(branch:, github_packages: false, root_url: nil) and TapNew.render_publish_yml(branch:, label:, github_packages: false); update run to call them — ERB content identical, no other changes
  • sync_tap_workflows.rb: require "dev-cmd/tap-new", call TapNew.render_tests_yml/render_publish_yml; add write_static_workflow helper for dry-run/write path; add --pull-label= flag
  • Remove all inlined ERB templates from sync_tap_workflows.rb
• Revert all completions/manpages to base branch state (no brew generate-man-completions in this PR)
• Add brew sync-tap-workflows section to docs/How-to-Create-and-Maintain-a-Tap.md
• brew typecheck and brew tests pass

Original prompt

Summary

Add a new brew sync-tap-workflows developer command that fetches workflow files from upstream Homebrew taps (Homebrew/homebrew-cask or Homebrew/homebrew-core) and adapts them for use in third-party taps using YAML-aware mutations via the psych-pure gem (comment-preserving YAML parser).

Motivation

Third-party tap maintainers have no way to keep CI workflows in sync with upstream Homebrew. The existing tap-new embeds workflow templates as ERB heredocs that drift over time. This command provides both initial generation and ongoing sync, and will be called by tap-new in a follow-up PR to replace the ERB heredoc approach for cask/shared workflows.

Background discussions:

• https://github.com/orgs/Homebrew/discussions/6499#discussioncomment-14784828
• https://github.com/orgs/Homebrew/discussions/41#discussioncomment-93844

New dependency: psych-pure

Add psych-pure to Library/Homebrew/Gemfile in a new optional group:

group :sync_workflows, optional: true do
  gem "psych-pure", require: false
end

This gem provides comment-preserving YAML parsing/dumping. It is pure Ruby (no native extensions), stable, and used in production by Discourse. See: https://github.com/kddnewton/psych-pure

New file: Library/Homebrew/dev-cmd/sync_tap_workflows.rb

Note: Homebrew dev-cmd files use underscores in filenames (matching the Ruby class name), while the CLI command uses hyphens (brew sync-tap-workflows). Check existing dev-cmd files for the correct convention and follow it.

CLI interface

brew sync-tap-workflows [--cask] [--formula] [--branch=<branch>]
    [--bot-username=<user>] [--bot-email=<email>] [--dry-run] <user>/<repo>

Flags

switch "--cask",
       description: "Sync cask CI workflows from Homebrew/homebrew-cask."
switch "--formula",
       description: "Sync formula CI workflows from Homebrew/homebrew-core."
flag   "--branch=",
       description: "Branch name for push triggers in workflows (default: `main`)."
flag   "--bot-username=",
       description: "GitHub username for the automated bump bot (used in autobump.yml)."
flag   "--bot-email=",
       description: "Commit email for the automated bump bot (used in autobump.yml)."
switch "--dry-run", "-n",
       description: "Print what would be done rather than doing it."

named_args :tap, number: 1

Error if neither --cask nor --formula is specified.

How it works

1. Fetch upstream files via GitHub raw content URL:

   • For --cask: fetch from Homebrew/homebrew-cask — files: ci.yml, ci-retry.yml, actionlint.yml, autobump.yml, cache.yml
   • For --formula: fetch from Homebrew/homebrew-core — files: autobump.yml, and from Homebrew/.github (the org-wide shared config repo) — files: actionlint.yml. For cache.yml, fetch from Homebrew/homebrew-cask (it's the same across repos, synced by the .github repo).

   Use Utils::Curl.curl_download or GitHub::API.open_rest or similar Homebrew patterns for fetching. Check how other dev-cmds fetch remote content and follow that pattern. The URL pattern is:

   https://raw.githubusercontent.com/Homebrew/homebrew-cask/HEAD/.github/workflows/<filename>
   

2. Parse with psych-pure (comment-preserving):

   require "psych/pure"
   yaml = Psych::Pure.load(content, comments: true)

3. Apply YAML-tree mutations (structural changes on the parsed data):

   For ALL workflow files that have on.push.branches:

   yaml["on"]["push"]["branches"] = [branch]  # default "main"

   For ALL workflow files that have on.merge_group:

   yaml["on"].delete("merge_group")

   Also remove merge_group references in if: conditions (these are strings, so use String#gsub on the if value).

   For files with org guards (if: conditions on jobs):

   • Replace github.repository_owner == 'Homebrew' with github.repository_owner == '<tap.user>'
   • Replace github.repository == 'Homebrew/homebrew-cask' with github.repository == '<tap.user>/homebrew-<tap.repository>'
   • Replace github.repository == 'Homebrew/homebrew-core' with github.repository == '<tap.user>/homebrew-<tap.repository>'

4. Apply string mutations on run: scalars (shell scripts inside run: keys are opaque to YAML — use String#gsub):

   • In generate-matrix run scripts: remove the merge_group elif branch; keep new_cask/--new logic
   • Replace ${{ join(matrix.audit_args, ' ') }} with --online --strict
   • Replace --tap=Homebrew/cask with --tap=<tap.user>/<tap.repository>
   • Replace --tap=Homebrew/core with --tap=<tap.user>/<tap.repository>

5. Apply autobump-specific mutations:

   • Remove the "Set up commit signing" step entirely (navigate yaml["jobs"]["autobump"]["steps"] and delete the step whose name matches)
   • Replace secrets.HOMEBREW_CASK_REPO_WORKFLOW_TOKEN → secrets.BOT_TOKEN (string replace in env values)
   • Replace...

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[toobuntu]

@copilot
Apply the following fixes based on a review against the patterns in Homebrew/brew#21418 (cmd/version-install) and Homebrew's AGENTS.md:

1. Remove # typed: strict from the spec file
   Library/Homebrew/test/dev-cmd/sync-tap-workflows_spec.rb has # typed: strict on line 1. Homebrew convention (and AGENTS.md) is to never use Sorbet typed: sigils in RSpec/test/*_spec.rb files. Remove that line entirely.

2. Add private_constant for implementation-detail constants
   In Library/Homebrew/dev-cmd/sync_tap_workflows.rb, the constants CASK_WORKFLOWS, FORMULA_WORKFLOWS, CASK_RAW_URL, CORE_RAW_URL, and ORG_GITHUB_RAW_URL are internal implementation details. Following the version-install pattern (which uses private_constant :DEFAULT_TAP_REPOSITORY), add after the constant definitions:

private_constant :CASK_WORKFLOWS, :FORMULA_WORKFLOWS, :CASK_RAW_URL, :CORE_RAW_URL, :ORG_GITHUB_RAW_URL

3. Update docs and completions for the new dev-cmd
   The version-install PR comprehensively updated docs. This PR adds a brand new developer command but doesn't update any docs or completions. Run brew generate-man-completions (per AGENTS.md rule: "After adding or modifying commands, run brew generate-man-completions and commit the result"), and commit the resulting changes. This should update:

• docs/Manpage.md
• manpages/brew.1
• completions/bash/brew
• completions/fish/brew.fish
• completions/zsh/_brew
• completions/internal_commands_list.txt

If brew generate-man-completions cannot be run in the sandbox, manually add sync-tap-workflows to completions/internal_commands_list.txt and add a command reference entry to docs/Manpage.md matching the format of other dev-cmd entries (look at how tap-new or version-install appear in that file).

[Copilot]

@copilot
Apply the following fixes based on a review against the patterns in Homebrew/brew#21418 (cmd/version-install) and Homebrew...

Done in 160f7f3:

1. Removed # typed: strict from sync-tap-workflows_spec.rb
2. Added private_constant :CASK_WORKFLOWS, :FORMULA_WORKFLOWS, :CASK_RAW_URL, :CORE_RAW_URL, :ORG_GITHUB_RAW_URL after the constant definitions in sync_tap_workflows.rb
3. Ran brew generate-man-completions and committed the results — docs/Manpage.md, manpages/brew.1, completions/bash/brew, completions/fish/brew.fish, completions/zsh/_brew, and completions/internal_commands_list.txt are all updated with the sync-tap-workflows entry

[toobuntu]

@copilot Are the transforms being applied when --dry-run is provided? They should be. Also, it would be nice to print a list of file names/paths which would be synced or newly-written. It might not be necessary, but perhaps as a summary at the end?

brew sync-tap-workflows --dry-run --cask toobuntu/testing | awk '/Would write/ {print $NF}'
/opt/homebrew/Library/Taps/toobuntu/homebrew-testing/.github/workflows/ci.yml
/opt/homebrew/Library/Taps/toobuntu/homebrew-testing/.github/workflows/ci-retry.yml
/opt/homebrew/Library/Taps/toobuntu/homebrew-testing/.github/workflows/actionlint.yml
/opt/homebrew/Library/Taps/toobuntu/homebrew-testing/.github/workflows/autobump.yml.disabled
/opt/homebrew/Library/Taps/toobuntu/homebrew-testing/.github/workflows/cache.yml

brew sync-tap-workflows --dry-run --formula toobuntu/testing | awk '/Would write/ {print $NF}'
/opt/homebrew/Library/Taps/toobuntu/homebrew-testing/.github/workflows/autobump.yml.disabled
/opt/homebrew/Library/Taps/toobuntu/homebrew-testing/.github/workflows/actionlint.yml
/opt/homebrew/Library/Taps/toobuntu/homebrew-testing/.github/workflows/cache.yml

It seems that --formula is not syncing all the correct files. brew tap-new is creating tests.yml and publish.yml, but I don't see those being synced.

[Copilot]

@copilot Are the transforms being applied when --dry-run is provided? They should be. Also, it would be nice to print a list of file names/paths which would be synced or newly-writ...

Addressed in 00f9496:

Transforms in --dry-run: Yes, all transforms are applied before the dry-run check — the ohai "Would write ..." + content output already shows the adapted YAML, not the raw upstream content.

Summary: Added an end-of-run summary that lists all file paths, e.g.:

==> Would sync 5 workflow file(s):
  /path/to/.github/workflows/ci.yml
  /path/to/.github/workflows/ci-retry.yml
  /path/to/.github/workflows/actionlint.yml
  /path/to/.github/workflows/autobump.yml.disabled
  /path/to/.github/workflows/cache.yml

tests.yml / publish.yml: These files are generated by tap-new from embedded ERB templates in tap-new.rb (lines 73–191) — they're not fetched from any upstream GitHub repository. sync-tap-workflows only syncs files that have an upstream source (homebrew-cask, homebrew-core, Homebrew/.github). tests.yml and publish.yml are tap-local, so there's no upstream to sync them from. Adding sync support for them would require a separate source (e.g. fetching from a reference tap or embedding updated templates).