HOMEBREW_DOCKER_REGISTRY_TOKEN usage

[azatoth]

Output of brew config

HOMEBREW_VERSION: 4.2.10-81-gf1eea64
ORIGIN: https://github.com/Homebrew/brew
HEAD: f1eea6452304daf08ad5d52e1219d7175ef407b2
Last commit: 87 minutes ago
Core tap HEAD: c24187829054961b2f35a3219b817c12300392ca
Core tap last commit: 2 days ago
Core tap JSON: 01 Mar 10:02 UTC
HOMEBREW_PREFIX: /home/linuxbrew/.linuxbrew
HOMEBREW_CASK_OPTS: []
HOMEBREW_DISPLAY: :1
HOMEBREW_DOCKER_REGISTRY_TOKEN: set
HOMEBREW_EDITOR: vim
HOMEBREW_MAKE_JOBS: 16
HOMEBREW_SORBET_RUNTIME: set
Homebrew Ruby: 3.1.4 => /home/linuxbrew/.linuxbrew/Homebrew/Library/Homebrew/vendor/portable-ruby/3.1.4/bin/ruby
CPU: 16-core 64-bit zen3
Clang: N/A
Git: 2.43.2 => /home/linuxbrew/.linuxbrew/bin/git
Curl: 7.81.0 => /bin/curl
Kernel: Linux 5.15.0-97-generic x86_64 GNU/Linux
OS: Ubuntu 22.04.4 LTS (jammy)
Host glibc: 2.35
/usr/bin/gcc: 11.4.0
/usr/bin/ruby: 3.0.2
glibc: N/A
gcc@11: N/A
gcc: N/A
xorg: N/A

Output of 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 formulae are deprecated or disabled.
You should find replacements for the following formulae:
  openssl@1.1

Description of issue

After tinkering and troubleshooting accessing a private tap on GitHub I realized HOMEBREW_DOCKER_REGISTRY_TOKEN needed to be the base64 encoding of your personal access token (PAT). i.e:

export HOMEBREW_DOCKER_REGISTRY_TOKEN=$(echo $GITHUB_TOKEN | base64)
brew install my_org/my_package/my_formula

Is this documented anywhere? As I've been unable to find much on this subject and nothing about the base64 part.

Regards,

[p-linnane]

Looks like it's not documented, but it is for HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN: https://docs.brew.sh/Manpage#environment

Feel free to submit a PR to the brew repo to add that.

[azatoth]

I was a bit confused when reading that as both were talking about "a Docker registry proxying GitHub Packages" and I needed to access ghcr.io which in my mind wasn't a proxy.
Also as HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN talked about "username and password" and disregarded that as something I was meant to use; It wasn't until later when I in desperation tried to use HOMEBREW_DOCKER_REGISTRY_TOKEN with base64 encoded PAT it suddenly worked.

[azatoth]

Feel free to submit a PR to the brew repo to add that.

I'll look into if I can formulate some intelligible documentation for that variable.

[Bo98]

HOMEBREW_DOCKER_REGISTRY_TOKEN is basically just a straight passthrough to Authorization: Bearer $HOMEBREW_DOCKER_REGISTRY_TOKEN.

How Bearer tokens are encoded is not actually defined, at least on OAuth level. OAuth RFC6750 §2.1 doesn't actually mention it needs to be Base64 encoded and the example mF_9.B5f-4.1JqM doesn't decode to anything meaningful in base64. It makes uses of b64token in its syntax but that's because it's borrowed from a HTTP/1.1 draft that had the same name but clarifies it to have the description:

The "b64token" syntax allows the 66 unreserved URI characters ([RFC3986]), plus a few others, so that it can hold a base64, base64url (URL and filename safe alphabet), base32, or base16 (hex) encoding, with or without padding, but excluding whitespace ([RFC4648]).

This was later changed to be "token68" in the final RFC7235 but this was too late for the OAuth spec which had already been finalised.

So in short: it doesn't have to be base64 - it totally depends on the authentication your registry requires and you need to consult the documentation for that service. Homebrew actually cheats a bit here. The flow you're supposed to do is:

• HTTP request to https://ghcr.io/token?scope=repository:$IMAGE:pull with Basic authentication with a username of anything (not used with GitHub) and a password of your access token. Basic authentication isn't a requirement in the Docker specification, but GitHub doesn't appear to support Bearer here.
• This request returns a token which you then pass on as Bearer authentication to subsequent requests.

Homebrew never does the initial request. GitHub Container Registry internally uses your password (the access token), base64 encodes it and uses it as the token returned back. This is purely an implementation quirk, but it probably won't change so is unlikely to break.

But non-GitHub registries may vary. A big use of HOMEBREW_DOCKER_REGISTRY_TOKEN is for mirrors.