Move integration guide docs and edit Azure integration guide (astral-…

…sh#5117)
exag · Jul 18, 2024 · 61a81da · 61a81da
1 parent fbb00f7
commit 61a81da
Show file tree

Hide file tree

Showing 8 changed files with 44 additions and 39 deletions.
diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md
@@ -66,3 +66,7 @@ system's trust store.
 
 If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment
 variable to the path of the PEM formatted file containing the certificate followed by the private key.
+
+## Authentication with commercial package indexes
+
+See the [commercial indexes integration guide](../guides/integration/commercial-indexes.md) for details on authentication with popular commercial Python package indexes.
diff --git a/docs/guides/integration/commercial-indexes.md b/docs/guides/integration/commercial-indexes.md
@@ -0,0 +1,35 @@
+# Using uv commercial package indexes
+
+While uv uses the official Python Package Index (PyPI) by default, it also supports commercial package indexes. Most commercial indexes require various forms of authentication, which requires some initial setup.
+
+## Azure Artifacts
+
+uv can install packages from [Azure DevOps Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver). Authenticate to a feed using a [Personal Access Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows) (PAT) or interactively using the [`keyring`](https://github.com/jaraco/keyring) package.
+
+### Authenticate using a PAT
+
+If there is a PAT available (eg [`$(System.AccessToken)` in an Azure pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)), credentials can be provided via the "Basic" HTTP authentication scheme. Include the PAT in the password field of the URL. A username must be included as well, but can be any string.
+
+```bash
+# With the token stored in the `ADO_PAT` environment variable
+export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
+```
+
+### Authenticate using the `keyring` plugin
+
+If there is not a PAT available, authenticate to Artifacts using the [`keyring`](https://github.com/jaraco/keyring) package with [the `artifacts-keyring` plugin](https://github.com/Microsoft/artifacts-keyring). Because these two packages are required to authenticate to Azure Artifacts, they must be pre-installed from a source other than Artifacts.
+
+The `artifacts-keyring` plugin wraps [the Azure Artifacts Credential Provider tool](https://github.com/microsoft/artifacts-credprovider). The credential provider supports a few different authentication modes including interactive login — see [the tool's documentation](https://github.com/microsoft/artifacts-credprovider) for information on configuration.
+
+uv only supports using the `keyring` package in [subprocess mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). The `keyring` executable must be in the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a username in the URL, so the index URL must include the default username `VssSessionToken`.
+
+```bash
+# Pre-install keyring and the Artifacts plugin from the public PyPI
+uv tool install keyring --with artifacts-keyring
+
+# Enable keyring authentication
+export UV_KEYRING_PROVIDER=subprocess
+
+# Configure the index URL with the username
+export UV_EXTRA_INDEX_URL=https://[email protected]/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
+```
diff --git a/docs/guides/docker.md → docs/guides/integration/docker.md b/docs/guides/docker.md → docs/guides/integration/docker.md
diff --git a/docs/guides/github.md → docs/guides/integration/github.md b/docs/guides/github.md → docs/guides/integration/github.md
diff --git a/docs/guides/pre-commit.md → docs/guides/integration/pre-commit.md b/docs/guides/pre-commit.md → docs/guides/integration/pre-commit.md
diff --git a/docs/guides/using-azure-artifacts.md b/docs/guides/using-azure-artifacts.md
diff --git a/docs/installation.md b/docs/installation.md
@@ -74,7 +74,7 @@ brew install uv
 
 uv provides a Docker image at [`ghcr.io/astral-sh/uv`](https://github.com/astral-sh/uv/pkgs/container/uv).
 
-See our guide on [using uv in Docker](./guides/docker.md) for more details.
+See our guide on [using uv in Docker](./guides/integration/docker.md) for more details.
 
 ## GitHub Releases
 

diff --git a/mkdocs.template.yml b/mkdocs.template.yml
@@ -90,9 +90,10 @@ nav:
       - Environment variables: configuration/environment.md
       - Settings: settings.md
   - Integration guides:
-      - Using in Docker: guides/docker.md
-      - Using in GitHub Actions: guides/github.md
-      - Using in pre-commit: guides/pre-commit.md
+      - Docker: guides/integration/docker.md
+      - GitHub Actions: guides/integration/github.md
+      - Pre-commit: guides/integration/pre-commit.md
+      - Commercial indexes: guides/integration/commercial-indexes.md
   - Low-level operations:
       - Using environments: pip/environments.md
       - Managing packages: pip/packages.md