What's the best way to migrate internal taps?

[colindean]

My ideal experience is that the user can tap the new repo, run at most one command, and then untap the old repo as soon as they're not using anything that wasn't migrated to the new tap.

I think I can achieve this with tap_migrations.json but I'm not 100% sure, and, so far, it's not working as expected.

---

My org is moving from a GitHub Enterprise Server at, e.g., https://git.mycorp.com, to GitHub Enterprise Cloud at, e.g., https://github.com/my-corp.

We had a tap set up at https://git.mycorp.com/brew/house and we've chosen to create a whole new tap— primarily to migrate only actively-used tools— to https://github.com/my-corp/brew-house.

Users must use SSH to clone, so they've used and will use:

# old tap
brew tap mycorp/brewhouse git@git.mycorp.com:brew/house
# new tap
brew tap my-corp/brew-house git@github.com:my-corp/brew-house

To the new tap, I added an exact copy of a formula, let's just call it docker-tools, to https://github.com/my-corp/brew-house in Formula/docker-tools.rb. It's valid, no concerns about that here.

After deleting that formula from a branch on the old tap, I also added a tap_migrations.json. The file follows the same format as homebrew/core, e.g.

{
  "docker-tools": "my-corp/brew-house"
}

I switched to that branch in my local tap clone.

I tapped the new tap and ran brew upgrade. I didn't see anything about the migration. I expected to see something. I tried running brew migrate docker-tools but its output was empty.

brew info docker-tools shows my-corp/brew-house/docker-tools, so I thought I was good. Also, this looks good:

$ brew list --full-name | grep my-corp
my-corp/brew-house/docker-tools

However, when I ran another script that runs brew install docker-tools, expecting to install from whatever tap has it, I see this:

Error: docker-tools was installed from the mycorp/brewhouse tap
but you are trying to install it from the my-corp/brew-house tap.
Formulae with the same name from different taps cannot be installed at the same time.

To install this version, you must first uninstall the existing formula:
  brew uninstall docker-tools
Then you can install the desired version:
  brew install my-corp/brew-house/docker-tools
Error trying to 'brew install docker-tools'.

brew doctor output doesn't have anything surprising to me.

brew doctor output

$ brew doctor
Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!

Warning: Some installed casks are deprecated or disabled.
You should find replacements for the following casks:
  qlcolorcode
  qlmarkdown
  qlprettypatch
  qlstephen
Warning: Calling no_autobump! because: :requires_manual_review is deprecated! There is no replacement.
Warning: Calling no_autobump! because: :requires_manual_review is deprecated! There is no replacement.
Warning: Calling no_autobump! because: :requires_manual_review is deprecated! There is no replacement.
Warning: Calling no_autobump! because: :requires_manual_review is deprecated! There is no replacement.
Warning: Calling no_autobump! because: :requires_manual_review is deprecated! There is no replacement.
Warning: Calling no_autobump! because: :requires_manual_review is deprecated! There is no replacement.
Warning: Calling no_autobump! because: :requires_manual_review is deprecated! There is no replacement.

Warning: Unbrewed dylibs were found in /usr/local/lib.
If you didn't put them there on purpose they could cause problems when
building Homebrew formulae and may need to be deleted.

Unexpected dylibs:
  /usr/local/lib/libMsgCom.dylib
  /usr/local/lib/libSysCtlCom.dylib
  /usr/local/lib/libwep_airdrop.dylib
  /usr/local/lib/libwep_burn.dylib
  /usr/local/lib/libwep_cbcarbon.dylib
  /usr/local/lib/libwep_cbcocoa.dylib
  /usr/local/lib/libwep_chrome.dylib
  /usr/local/lib/libwep_dutil.dylib
  /usr/local/lib/libwep_ff.dylib
  /usr/local/lib/libwep_icloud.dylib
  /usr/local/lib/libwep_mail.dylib
  /usr/local/lib/libwep_post.dylib
  /usr/local/lib/libwep_pref.dylib
  /usr/local/lib/libwep_printer.dylib
  /usr/local/lib/libwep_proxy.dylib
  /usr/local/lib/libwep_screen.dylib

Warning: Found Ruby file outside mycorp/brewhouse tap formula directory.
(/opt/homebrew/Library/Taps/mycorp/homebrew-brewhouse/Formula):
  /opt/homebrew/Library/Taps/mycorp/homebrew-brewhouse/ghe_download_strategy.rb

Found Ruby file outside go-vela/vela tap formula directory.
(/opt/homebrew/Library/Taps/go-vela/homebrew-vela/Formula):
  /opt/homebrew/Library/Taps/go-vela/homebrew-vela/template.rb

Warning: You have unlinked kegs in your Cellar.
Leaving kegs unlinked can lead to build-trouble and cause formulae that depend on
those kegs to fail to run properly once built. Run `brew link` on these:
  openssl@3

Warning: Some taps are not on the default git origin branch and may not receive
updates. If this is a surprise to you, check out the default branch with:
  git -C $(brew --repo mycorp/brewhouse) checkout master

The workaround for this problem I'm having is to do exactly as the above says: direct the user to uninstall the old tap packages and install new tap packages. I'd like to minimize this or make it a one-shot command that handles all packages installed from the old that are available in the new— not all will be migrated.

I could basically do something like

old=mycorp/brewhouse
new=my-corp/brew-house
for pkg in `brew list --full-name | grep ${old}`; do
  brew uninstall ${pkg}
  brew install ${pkg/$old/$new}
done

At this point, my questions are:

1. Did I set up the tap_migrations.json correctly, given the expected name of the new tap when tapped?
2. Can I force a formula to be migrated in this way? I expected brew migrate to do that, but maybe it doesn't… maybe it's more of a renaming function and not a tap migration function.

[colindean]

We ended up recommending this approach:

OLD_TAP_PREFIX=mycorp/brewhouse
NEW_TAP_PREFIX=my-corp/brew-house
NEW_TAP_URL=git@github.com:my-corp/homebrew-brew-house.git

# get a list of packages installed on the old tap
declare -a pkgs=($(brew list --full-name | grep $(brew tap | grep ${OLD_TAP_PREFIX})))
# uninstall them
brew uninstall --force ${pkgs[*]}
# tap the new one, use --custom-remote to overwrite the URL
# if they already have it tapped so that *this cannot fail*
brew tap --custom-remote ${NEW_TAP_PREFIX} ${NEW_TAP_URL}
# 5.1.15+ requires this now?
brew trust ${NEW_TAP_PREFIX}
# install each previously installed package from the new tap using the new tap's full-name package
brew install ${pkgs[*]/${OLD_TAP_PREFIX}/${NEW_TAP_PREFIX}}
# remove the old tap
brew untap ${OLD_TAP_PREFIX}

Side note: Initially, the new tap was named my-corp/brew-house but sense came to rename it to my-corp/homebrew-brew-house so that folks could manually type brew tap my-corp/brew-house and it'd just work using Homebrew's tap resolution rules. We prefer SSH internally but not every has git or gh set up to handle it consistently, so we chose to push SSH while allowing HTTPS. I'd recommend sticking to a repo name prefixed with homebrew-.