Support Docker Registry v2 API for custom artifact domains (Nexus, Harbor)

[jamessevener]

brew doctor output

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 kegs have no formulae!
This means they were either deleted or installed manually.
You should find replacements for the following formulae:
  terraform
  python-pyparsing

Warning: Some installed formulae are deprecated or disabled.
You should find replacements for the following formulae:
  icu4c@76

Warning: You have the following deprecated, official taps tapped:
  Homebrew/homebrew-services
Untap them with `brew untap`.

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/libDellMonitorSdkLib.dylib

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

Unexpected header files:
  /usr/local/include/node/*

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:
  wget
  bash-completion@2
  jq

Warning: You have uncommitted modifications to Homebrew/brew.
If this is a surprise to you, then you should stash these modifications.
Stashing returns Homebrew to a pristine state but can be undone
should you later need to do so for some reason.
  git -C "/opt/homebrew" stash -u && git -C "/opt/homebrew" clean -d -f

Uncommitted files:
   M Library/Homebrew/download_strategy.rb
   M Library/Homebrew/env_config.rb
   M Library/Homebrew/utils/bottles.rb

Warning: The following repositories are on the deprecated "master" branch.
The "master" branch sync will stop and this warning will become an error
when Homebrew 5.2.0 is released (no earlier than 2026-06-10).
Run `brew update` to migrate to "main":
  homebrew/services

Warning: /usr/bin occurs before /opt/homebrew/bin in your PATH.
This means that system-provided programs will be used instead of those
provided by Homebrew. Consider setting your PATH so that
/opt/homebrew/bin occurs before /usr/bin. Here is a one-liner:
  echo 'export PATH="/opt/homebrew/bin:$PATH"' >> /Users/home/.bash_profile

The following tools exist at both paths:
  bashbug
  openssl
  pip3
  pp
  python3
  stdbuf

Warning: Homebrew's "sbin" was not found in your PATH but you have installed
formulae that put executables in /opt/homebrew/sbin.
Consider setting your PATH for example like so:
  echo 'export PATH="/opt/homebrew/sbin:$PATH"' >> /Users/home/.bash_profile

Warning: Broken symlinks were found. Remove them with `brew cleanup`:
  /opt/homebrew/opt/jq

Warning: Some installed formulae are missing dependencies.
You should `brew install` the missing dependencies:
  brew install icu4c@78 pkgconf python@3.12

Run `brew missing` for more details.

Verification

• I ran brew update twice and am still able to reproduce my issue.
• My "brew doctor output" above says Your system is ready to brew or a definitely unrelated Tier message.
• This issue's title and/or description do not reference a single formula e.g. brew install wget. If they do, open an issue at https://github.com/Homebrew/homebrew-core/issues/new/choose instead.

brew config output

HOMEBREW_VERSION: 5.1.8-dirty
ORIGIN: https://github.com/Homebrew/brew
HEAD: b9763ee5280dc1acb3036383b3608084eebac6b7
Last commit: 4 days ago
Branch: stable
Core tap JSON: 30 Apr 20:36 UTC
Core cask tap JSON: 30 Apr 20:36 UTC
HOMEBREW_PREFIX: /opt/homebrew
HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK: set
HOMEBREW_CASK_OPTS: []
HOMEBREW_DOWNLOAD_CONCURRENCY: 20
HOMEBREW_FORBID_PACKAGES_FROM_PATHS: set
HOMEBREW_MAKE_JOBS: 10
HOMEBREW_SORBET_RUNTIME: set
Homebrew Ruby: 4.0.3 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/4.0.3/bin/ruby
CPU: deca-core 64-bit arm_firestorm_icestorm
Clang: 21.0.0 build 2100
Git: 2.50.1 => /Applications/Xcode.app/Contents/Developer/usr/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 26.4.1-arm64
CLT: 26.4.1.0.1775747724
Xcode: 26.4.1
Metal Toolchain: N/A
Rosetta 2: false

What were you trying to do (and why)?

HOMEBREW_ARTIFACT_DOMAIN doesn't work with custom Docker registries like Nexus or Harbor that proxy ghcr.io. Homebrew only uses Docker Registry v2 API when the URL domain is exactly ghcr.io, causing downloads from other registries to fail with checksum mismatches.

What happened (include all command output)?

When pointing HOMEBREW_ARTIFACT_DOMAIN to a Nexus or Harbor Docker registry:

• Homebrew attempts plain HTTP GET requests for .tar.gz files
• Docker registries require Docker Registry v2 API paths (/blobs/sha256:...)
• Downloads fail or return HTML error pages instead of bottles

What did you expect to happen?

Homebrew should be able to use Docker Registry v2 API for custom artifact domains when configured to do so.

Step-by-step reproduction instructions (by running brew commands)

When pointing `HOMEBREW_ARTIFACT_DOMAIN` to a Nexus or Harbor Docker registry:
- Homebrew attempts plain HTTP GET requests for `.tar.gz` files

This was generated in part by Claude with sonnet 4.5

[jamessevener]

Proposed Solution:

Add an environment variable (e.g., HOMEBREW_ARTIFACT_DOMAIN_USE_DOCKER_API) to explicitly enable Docker Registry v2 API protocol when using custom artifact domains.

This would allow organizations to use standard OCI-compliant registries (Nexus, Harbor, etc.) as Homebrew bottle caches with authentication, similar to the documented Artifactory setup but working with any Docker registry.

I have a working patch locally, and can open a PR if there is interest in supporting this. It would be really helpful in our environment, and would help get brew more in line with our corporate requirements.

[Bo98]

Not sure I understand what issue you're seeing. HOMEBREW_ARTIFACT_DOMAIN already requests /blobs/sha256: whereas HOMEBREW_BOTTLE_DOMAIN requests the non-OCI .tar.gz path.

$ HOMEBREW_ARTIFACT_DOMAIN=https://example.com HOMEBREW_DOWNLOAD_CONCURRENCY=1 brew fetch --verbose hello
==> Downloading https://example.com/v2/homebrew/core/hello/manifests/2.12.3
[...]
==> Downloading https://example.com/v2/homebrew/core/hello/blobs/sha256:ce9f4dd817532429fb3b890a901da44fa66f0540e242321f40fa12231f5ffa60

$ HOMEBREW_BOTTLE_DOMAIN=https://example.com HOMEBREW_DOWNLOAD_CONCURRENCY=1 brew fetch --verbose hello
==> Downloading https://example.com/hello-2.12.3.arm64_sequoia.bottle.tar.gz
[...]

[MikeMcQuaid]

Continue conversation here but as-is this doesn't sound like a bug.

[jamessevener]

Ah, okay. I found the problem I had. When testing I had HOMEBREW_BOTTLE_DOMAIN set incorrectly, and just needed to un-set it. Thanks for clarifying.