From 94ed6f880f78bf1aa7f7d7b0a0fa092980b03409 Mon Sep 17 00:00:00 2001 From: Jack O'Connor Date: Thu, 5 Jun 2025 13:44:59 -0700 Subject: [PATCH] update Git and GitHub Actions docs to mention `gh auth login` (#13850) --- docs/concepts/authentication.md | 57 ++++++++++++++++++++++++++++--- docs/guides/integration/github.md | 29 ++++++++++++++++ 2 files changed, 82 insertions(+), 4 deletions(-) diff --git a/docs/concepts/authentication.md b/docs/concepts/authentication.md index a05a637ba..10bf57c21 100644 --- a/docs/concepts/authentication.md +++ b/docs/concepts/authentication.md @@ -21,12 +21,48 @@ Using a password or token: - `git+https://@/...` (e.g., `git+https://github_pat_asdf@github.com/astral-sh/uv`) - `git+https://@/...` (e.g., `git+https://git@github.com/astral-sh/uv`) -When using a GitHub personal access token, the username is arbitrary. GitHub does not support -logging in with password directly, although other hosts may. If a username is provided without -credentials, you will be prompted to enter them. +When using a GitHub personal access token, the username is arbitrary. GitHub doesn't allow you to +use your account name and password in URLs like this, although other hosts may. If there are no credentials present in the URL and authentication is needed, the -[Git credential helper](https://git-scm.com/doc/credential-helpers) will be queried. +[Git credential helper](#git-credential-helpers) will be queried. + +!!! important + + When using `uv add`, uv _will not_ persist Git credentials to the `pyproject.toml` or `uv.lock`. + These files are often included in source control and distributions, so it is generally unsafe + to include credentials in them. + + If you have a Git credential helper configured, your credentials may be automatically persisted, + resulting in successful subsequent fetches of the dependency. However, if you do not have a Git + credential helper or the project is used on a machine without credentials seeded, uv will fail to + fetch the dependency. + + You _may_ force uv to persist Git credentials by passing the `--raw` option to `uv add`. However, + we strongly recommend setting up a [credential helper](#git-credential-helpers) instead. + +### Git credential helpers + +Git credential helpers are used to store and retrieve Git credentials. See the +[Git documentation](https://git-scm.com/doc/credential-helpers) to learn more. + +If you're using GitHub, the simplest way to set up a credential helper is to +[install the `gh` CLI](https://github.com/cli/cli#installation) and use: + +```console +$ gh auth login +``` + +See the [`gh auth login`](https://cli.github.com/manual/gh_auth_login) documentation for more +details. + +!!! note + + When using `gh auth login` interactively, the credential helper will be configured automatically. + But when using `gh auth login --with-token`, as in the uv + [GitHub Actions guide](../guides/integration/github.md#private-repos), the + [`gh auth setup-git`](https://cli.github.com/manual/gh_auth_setup-git) command will need to be + run afterwards to configure the credential helper. ## HTTP authentication @@ -62,6 +98,19 @@ authenticating index URLs. See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on differences from `pip`. +!!! important + + When using `uv add`, uv _will not_ persist index credentials to the `pyproject.toml` or `uv.lock`. + These files are often included in source control and distributions, so it is generally unsafe + to include credentials in them. However, uv _will_ persist credentials for direct URLs, i.e., + `package @ https://username:password:example.com/foo.whl`, as there is not currently a way to + otherwise provide those credentials. + + If credentials were attached to an index URL during `uv add`, uv may fail to fetch dependencies + from indexes which require authentication on subsequent operations. See the + [index authentication documentation](./indexes.md#authentication) for details on persistent + authentication for indexes. + ## Authentication with alternative package indexes See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for diff --git a/docs/guides/integration/github.md b/docs/guides/integration/github.md index ac2ec637c..9dce72252 100644 --- a/docs/guides/integration/github.md +++ b/docs/guides/integration/github.md @@ -346,3 +346,32 @@ steps: ``` To opt-out again, the `--no-system` flag can be used in any uv invocation. + +## Private repos + +If your project has [dependencies](../../concepts/projects/dependencies.md#git) on private GitHub +repositories, you will need to configure a [personal access token (PAT)][PAT] to allow uv to fetch +them. + +After creating a PAT that has read access to the private repositories, add it as a [repository +secret]. + +Then, you can use the [`gh`](https://cli.github.com/) CLI (which is installed in GitHub Actions +runners by default) to configure a +[credential helper for Git](../../concepts/authentication.md#git-credential-helpers) to use the PAT +for queries to repositories hosted on `github.com`. + +For example, if you called your repository secret `MY_PAT`: + +```yaml title="example.yml" +steps: + - name: Register the personal access token + run: echo "${{ secrets.MY_PAT }}" | gh auth login --with-token + - name: Configure the Git credential helper + run: gh auth setup-git +``` + +[PAT]: + https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens +[repository secret]: + https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository