https://github.com/razerm/keyring-gitlab-pypi
keyring backend for GitLab package indexes
https://github.com/razerm/keyring-gitlab-pypi
Last synced: 4 months ago
JSON representation
keyring backend for GitLab package indexes
- Host: GitHub
- URL: https://github.com/razerm/keyring-gitlab-pypi
- Owner: RazerM
- License: mit
- Created: 2025-04-15T19:48:53.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-08-09T22:28:33.000Z (5 months ago)
- Last Synced: 2025-08-09T23:28:02.065Z (5 months ago)
- Language: Python
- Size: 108 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
`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
```bash
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.tomlif directory$HOME/Library/Application Support/gitlab-pypiexists, or$HOME/.config/gitlab-pypi.tomlotherwise. - Linux
-
$XDG_CONFIG_HOME/gitlab-pypi.tomlifXDG_CONFIG_HOMEis set, or$HOME/.config/gitlab-pypi.tomlotherwise. - Windows
%LOCALAPPDATA%\gitlab-pypi\gitlab-pypi.toml
### System
- macOS
/Library/Application Support/gitlab-pypi/gitlab-pypi.toml- Linux
-
<config_dir>/gitlab-pypi/gitlab-pypi.tomlwhere<config_dir>is any of the paths set in$XDG_CONFIG_DIRSpaths, defaulting to/etc/xdg
/etc/gitlab-pypi.tomlis higher priority than the above.
- Windows
C:\ProgramData\gitlab-pypi\gitlab-pypi.toml
3. Create a personal access token with `read_api` scope and add it to the config file:
```toml
["https://gitlab.com"]
token = ""
```
4. Configure [`keyring-provider`] in uv:
- using an environment variable:
```bash
export UV_KEYRING_PROVIDER=subprocess
```
- or in `uv.toml`:
```toml
keyring-provider = "subprocess"
```
- or using the option
```bash
uv sync --keyring-provider=subprocess
```
5. Configure one or more GitLab package indexes
For example, in `pyproject.toml`:
```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 `__token__` 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:
```yaml
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:
```bash
printf '%s\n' keyring keyring-gitlab-pypi > keyring-constraints.in
uv pip compile --universal keyring-constraints.in -o keyring-constraints.txt
```
```yaml
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.
[keyring]: https://pypi.org/project/keyring/
[GitLab package registry]: https://docs.gitlab.com/user/packages/pypi_repository/#authenticate-with-the-gitlab-package-registry
[uv]: https://docs.astral.sh/uv/
[`keyring-provider`]: https://docs.astral.sh/uv/reference/settings/#keyring-provider