keyring-gitlab-pypi 1.2

keyring-gitlab-pypi is a backend for keyring which recognises GitLab package registry URLs.

• ⚡️ Works seamlessly with uv
• 🚀 Zero config needed on GitLab CI
• 🗝️ No more per-index credentials on your machine

Using it locally

1. Install keyring with this backend

   uv tool install keyring --with keyring-gitlab-pypi
   

2. Open the config file for editing:

   User

   macOS

   $HOME/Library/Application Support/gitlab-pypi/gitlab-pypi.toml if directory $HOME/Library/Application Support/gitlab-pypi exists, or $HOME/.config/gitlab-pypi.toml otherwise.

   Linux

   $XDG_CONFIG_HOME/gitlab-pypi.toml if XDG_CONFIG_HOME is set, or $HOME/.config/gitlab-pypi.toml otherwise.

   Windows

   %LOCALAPPDATA%\gitlab-pypi\gitlab-pypi.toml

   System

   macOS

   /Library/Application Support/gitlab-pypi/gitlab-pypi.toml

   Linux

   <config_dir>/gitlab-pypi/gitlab-pypi.toml where <config_dir> is any of the paths set in $XDG_CONFIG_DIRS paths, defaulting to /etc/xdg

   /etc/gitlab-pypi.toml is higher priority than the above.

   Windows

   C:\ProgramData\gitlab-pypi\gitlab-pypi.toml

3. Configure a token

   Personal Access Token

   Create a personal access token with the read_api scope and add it to the config file:

   ["gitlab.com"]
   token = "<token>"
   

   or set environment variables where <name> is an arbitrary key to group the variables, e.g. MYORG

   export KEYRING_GITLAB_PYPI_<name>_INSTANCE=gitlab.com
   export KEYRING_GITLAB_PYPI_<name>_TOKEN=<token>
   

   Deploy Token

   Create a deploy token with the read_package_registry scope and add it to the config file:

   ["gitlab.com"]
   username = "<username>"
   token = "<token>"
   

   or set environment variables where <name> is an arbitrary key to group the variables, e.g. MYORG

   export KEYRING_GITLAB_PYPI_<name>_INSTANCE=gitlab.com
   export KEYRING_GITLAB_PYPI_<name>_USERNAME=<username>
   export KEYRING_GITLAB_PYPI_<name>_TOKEN=<token>
   

4. Configure keyring-provider in uv:

   • using an environment variable:

     export UV_KEYRING_PROVIDER=subprocess
     

   • or in uv.toml:

     keyring-provider = "subprocess"
     

   • or using the option

     uv sync --keyring-provider=subprocess
     

5. Configure one or more GitLab package indexes

   For example, in pyproject.toml:

   [[tool.uv.index]]
   name = "myindex"
   url = "https://gitlab.example.com/api/v4/projects/1/packages/pypi/simple"
   authenticate = "always"
   

   Note

   You need authenticate = "always" for uv to invoke keyring when no username is specified. This option is a good idea anyway!

   Alternatively, add the username (which is __token__ for personal access tokens) to the URL, but this is not recommended for pyproject.toml as you likely want to use a different username in CI, for example.

6. Done! keyring-gitlab-pypi will return your token for URLs that look like package installs.

Using it in GitLab CI

$CI_JOB_TOKEN will be used automatically as long as the index URL matches the running GitLab instance.

In principle this is all you need:

variables:
  UV_KEYRING_PROVIDER: subprocess
  UV_TOOL_BIN_DIR: /usr/local/bin

test:
  image: ghcr.io/astral-sh/uv:python3.13-bookworm
  before_script:
    - uv tool install keyring --with keyring-gitlab-pypi
    - uv sync

This assumes that you haven't set UV_INDEX. (uv tool ignores pyproject.toml so you don't need to worry about indexes configured there).

It's recommended to constrain the versions:

printf '%s\n' keyring keyring-gitlab-pypi > keyring-constraints.in
uv pip compile --universal keyring-constraints.in -o keyring-constraints.txt

variables:
  UV_KEYRING_PROVIDER: subprocess
  UV_TOOL_BIN_DIR: /usr/local/bin

test:
  image: ghcr.io/astral-sh/uv:python3.13-bookworm
  before_script:
    - uv tool install keyring --with keyring-gitlab-pypi -c keyring-constraints.txt
    - uv sync

Motivation

• When using multiple GitLab package indexes, it can be cumbersome to configure them with the same token via environment variables or otherwise.
• keyring's keychain backend on macOS does not support --mode creds
• uv will reuse credentials for URLs on the same host, but it feels fragile to just configure one of the indexes and let the credentials cache serve the rest. At the very least, keyring-gitlab-pypi is set-and-forget across multiple projects.