From b4b5efea0a15fe77b3c4c6724cfc9bbf2659def5 Mon Sep 17 00:00:00 2001
From: Kristian Glass <kristian.glass@chainguard.dev>
Date: Wed, 8 Jul 2026 12:06:28 +0100
Subject: [PATCH] docs(libraries): document UV_INDEX env vars for uv
 authentication
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add uv's native index-scoped environment variable support
(UV_INDEX_<NAME>_USERNAME / UV_INDEX_<NAME>_PASSWORD) as the recommended
credential approach for CI/CD — avoiding hardcoded credentials in config
files without requiring .netrc.

Covered in both the Python build-configuration uv section and the
access.md environment variables section.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Kristian Glass <kristian.glass@chainguard.dev>
---
 content/chainguard/libraries/access.md        | 20 +++++++++
 .../libraries/python/build-configuration.md   | 41 ++++++++++++++++++-
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/content/chainguard/libraries/access.md b/content/chainguard/libraries/access.md
index c42c530c46..755383a646 100644
--- a/content/chainguard/libraries/access.md
+++ b/content/chainguard/libraries/access.md
@@ -224,6 +224,26 @@ tool configuration with environment variable placeholders:
 * [Python build tool
   configuration](/chainguard/libraries/python/build-configuration/)
 
+#### uv index-scoped environment variables
+
+When using `uv` for Python, you can supply credentials through index-scoped
+environment variables instead of a shared secrets file or `.netrc`. For a named
+index, uv reads `UV_INDEX_<NAME>_USERNAME` and `UV_INDEX_<NAME>_PASSWORD`, where
+`<NAME>` is the index name uppercased with hyphens replaced by underscores.
+
+For an index named `chainguard`, set:
+
+```shell
+export UV_INDEX_CHAINGUARD_USERNAME="${CHAINGUARD_PYTHON_IDENTITY_ID}"
+export UV_INDEX_CHAINGUARD_PASSWORD="${CHAINGUARD_PYTHON_TOKEN}"
+```
+
+This pairs well with the `eval` approach above: generate the
+`CHAINGUARD_PYTHON_IDENTITY_ID` and `CHAINGUARD_PYTHON_TOKEN` variables, then
+map them to uv's index-scoped names. See the [uv build
+configuration](/chainguard/libraries/python/build-configuration/#uv) for index
+setup details.
+
 <a id="netrc"></a>
 
 ### .netrc for authentication
diff --git a/content/chainguard/libraries/python/build-configuration.md b/content/chainguard/libraries/python/build-configuration.md
index 20618c8fed..9699a757c6 100644
--- a/content/chainguard/libraries/python/build-configuration.md
+++ b/content/chainguard/libraries/python/build-configuration.md
@@ -482,9 +482,46 @@ authentication](/chainguard/libraries/access/#netrc).
 #### Using direct access
 
 For [direct access](#direct-access) to Chainguard Libraries for Python with
-uv, use `.netrc` or your username `CG_PULLTOKEN_USERNAME` and password
+uv, use `.netrc`, environment variables, or embed credentials directly in the
+index URL using your username `CG_PULLTOKEN_USERNAME` and password
 `CG_PULLTOKEN_PASSWORD` values from the pull token creation and the URL with the
-simple context `https://libraries.cgr.dev/python/simple/`:
+simple context `https://libraries.cgr.dev/python/simple/`.
+
+The recommended approach for CI/CD and shared configurations is to use
+uv's native index-scoped environment variables. For a named index, uv reads
+credentials from `UV_INDEX_<NAME>_USERNAME` and `UV_INDEX_<NAME>_PASSWORD`,
+where `<NAME>` is the index name uppercased with hyphens replaced by underscores.
+This avoids storing credentials in config files while keeping the index
+configuration shareable.
+
+For example, with an index named `chainguard`:
+
+```shell
+export UV_INDEX_CHAINGUARD_USERNAME=CG_PULLTOKEN_USERNAME
+export UV_INDEX_CHAINGUARD_PASSWORD=CG_PULLTOKEN_PASSWORD
+```
+
+Configure the index without embedded credentials in `pyproject.toml`:
+
+```toml
+[[tool.uv.index]]
+name = "chainguard"
+url = "https://libraries.cgr.dev/python/simple/"
+default = true
+authenticate = "always"
+```
+
+Or in `uv.toml`:
+
+```toml
+[[index]]
+name = "chainguard"
+url = "https://libraries.cgr.dev/python/simple/"
+authenticate = "always"
+```
+
+Alternatively, embed credentials directly in the URL (avoid in shared or
+version-controlled files):
 
 Example for `pyproject.toml`: