mirror of
https://github.com/astral-sh/uv.git
synced 2025-10-10 18:42:10 +00:00
70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
# Git credentials
|
|
|
|
uv allows packages to be installed from private Git repositories using SSH or HTTP authentication.
|
|
|
|
## SSH authentication
|
|
|
|
To authenticate using an SSH key, use the `ssh://` protocol:
|
|
|
|
- `git+ssh://git@<hostname>/...` (e.g., `git+ssh://git@github.com/astral-sh/uv`)
|
|
- `git+ssh://git@<host>/...` (e.g., `git+ssh://git@github.com-key-2/astral-sh/uv`)
|
|
|
|
SSH authentication requires using the username `git`.
|
|
|
|
See the
|
|
[GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh)
|
|
for more details on how to configure SSH.
|
|
|
|
### HTTP authentication
|
|
|
|
To authenticate over HTTP Basic authentication using a password or token:
|
|
|
|
- `git+https://<user>:<token>@<hostname>/...` (e.g.,
|
|
`git+https://git:github_pat_asdf@github.com/astral-sh/uv`)
|
|
- `git+https://<token>@<hostname>/...` (e.g., `git+https://github_pat_asdf@github.com/astral-sh/uv`)
|
|
- `git+https://<user>@<hostname>/...` (e.g., `git+https://git@github.com/astral-sh/uv`)
|
|
|
|
!!! note
|
|
|
|
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](#git-credential-helpers) will be queried.
|
|
|
|
## Persistence of credentials
|
|
|
|
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.
|