git-buckets-keyring

A stateless keyring backend for git-buckets package registries. It turns your ambient AWS profile into a short-lived package token so uv sync and pip install can reach a private index with no login step.

It stores nothing. On each lookup it SigV4-signs an sts:GetCallerIdentity call with your profile, trades that proof for a 1-hour token at https://<host>/auth/token, and hands the token to the client as the HTTP Basic password. Tokens are cached in-process only, never on disk.

Setup

Once per machine:

uv tool install git-buckets-keyring
export UV_KEYRING_PROVIDER=subprocess         # or tool.uv.keyring-provider = "subprocess"
export GB_KEYRING_HOSTS=git.example.cloud     # hosts this backend is allowed to answer for
export GB_KEYRING_PROFILE=my-profile          # optional: the AWS profile to mint with

Then in the consuming project's pyproject.toml:

[[tool.uv.index]]
name = "demos"
url = "https://gb@git.example.cloud/packages/demos/pypi/"
explicit = true

[tool.uv.sources]
demos-cli = { index = "demos" }

The gb@ in the URL is load-bearing: uv only performs keyring discovery when the index URL carries a username.

GB_KEYRING_HOSTS

A comma-separated allowlist of hostnames, empty by default. The backend returns None for every host that is not listed, and for every username other than gb, so it is inert on other machines and other indexes. It is an allowlist, not a target: the host used is the one the client asked about, admitted only if it is listed.

GB_KEYRING_PROFILE

The AWS profile to mint with, overriding AWS_PROFILE and the rest of the default chain. Unset, the backend uses the ambient session as before. Set it when a project works against one AWS account while pulling packages entitled through another, so AWS_PROFILE is already pointed somewhere else. A profile that does not exist is treated like any other failure: no token, no exception.

GB_KEYRING_DEBUG

Set to anything non-empty to have the backend print one line on stderr explaining why it declined — wrong username, host not on the allowlist, or the mint failed and why. Off by default, and stdout stays clean either way so keyring get output is still just the token. The token is never printed to stderr.

Printing a token by hand

keyring get https://git.example.cloud/packages/demos/pypi/ gb

If the bundled keyring script collides

uv tool install git-buckets-keyring installs a keyring executable of its own. If that clashes with an existing one, install the other way round:

uv tool install keyring --with git-buckets-keyring