Skip to content

Reference

Installation & Usage Modes

uvault can be executed in two different ways depending on your needs:

Installing uvault as a dev dependency gives it access to your project's environment. This is crucial if you want uvault add to automatically guess repository URLs based on the metadata of your installed packages.

uv add --dev uvault[github]
uv run uvault --help

Note: The [github] extra installs pygithub, which enables uvault sync to automatically fork repositories into your GitHub organization if they don't already exist.

2. As an Independent Tool via uvx

If you prefer keeping your dependencies minimal and don't need the automatic URL resolution feature, you can run uvault purely as an isolated, ephemeral tool using uvx.

uvx --with uvault[github] uvault sync

pyproject.toml Configuration

The intention configuration is located in the [tool.uvault] section:

[tool.uvault]
tag_prefix = "apycod"                   # (Optional) Prefix for generated tags. Defaults to "".
include_sha_in_release = false          # (Optional) Includes the commit SHA in the vault tag during releases. Defaults to true.
dev_directory = ".src/"                 # (Optional) Directory for developed sources. Defaults to ".src/".

# VCS Vault Configuration
[[tool.uvault.vcs_vaults]]
provider = "github.com"                 # (Required) The git hosting provider (e.g., "github.com" or "gitlab.com").
owner = "petrus-v"                      # (Optional) The user or organization owning the vault repository.
fetch_ssh = true                        # (Optional) If true, generates ssh:// URLs in [tool.uv.sources] instead of https://. Defaults to false.
push_ssh = true                         # (Optional) If true, pushes tags to the vault using ssh://. Defaults to true.
default = true                          # (Optional) Marks this vault as the default for synchronizing packages.

# Declaration of dependencies to synchronize
[tool.uvault.sources]
my-package = { git = "https://github.com/OCA/repository", rev = "refs/pull/100/head", subdirectory = "my_package" }

Tag Nomenclature

uvault uses a specific naming convention for the tags it pushes to your vault, depending on the command executed:

  • uvault sync: Generates tags in the format <tag_prefix>+<sha> (e.g., apycod+abcdef123...). The project version is deliberately omitted during standard synchronization to avoid polluting tags when the version hasn't officially changed.
  • uvault release: Generates tags that always include the project version. Depending on the include_sha_in_release setting, it takes the format <tag_prefix>-<project_version>+<sha> (if true) or simply <tag_prefix>-<project_version> (if false).

The include_sha_in_release Parameter

While include_sha_in_release defaults to true, it is highly recommended to set it to false if you are using a structured hook-based workflow (like bump-my-version).

Setting it to false yields much cleaner, uniform tags during a release (e.g., apycod-1.0.0).

Why does it default to true?

If your workflow does not guarantee that a single version string maps to a single atomic release commit (for instance, if you might run uvault release multiple times for the exact same project version), omitting the SHA would cause uvault to overwrite the same tag in the vault, potentially losing intermediate locked versions. Keeping the SHA by default acts as a safety mechanism against accidental tag collisions.

User Configuration

You can define local machine-specific configurations, such as custom git remotes and your GitHub token, in ~/.config/uvault/config.toml.

[remotes]
myorg = "https://gitlab.com/myorg/"
perso = "ssh://git@github.com/personal/"

[github]
token = "ghp_YOUR_GITHUB_TOKEN"
  • Remotes will be automatically added to the repository when running uvault develop.
  • The github token is used for automatically forking repositories when running uvault sync. For this to work, you need to have the pygithub optional dependency installed (e.g., uv pip install uvault[github]). In GitHub the token needs fork permissions.

CLI Commands

uvault sync

Synchronizes remote references to the vault repository and updates [tool.uv.sources].

Note: By default, uvault sync will skip any package that is already declared in [tool.uv.sources].

Flags:

  • -P <package>, --package <package> : Only sync the specified package. Can be used multiple times.
  • --update : Forces an update of the package(s) even if they are already present in [tool.uv.sources].
  • --delete-extra : Removes any package found in [tool.uv.sources] that is not declared in [tool.uvault.sources].
  • --keep-develop : By default, packages in develop mode (editable = true or using path) are restored to their vaulted state during sync. Use this flag to keep them in develop mode.

Automatic Forking (GitHub):

If uvault sync attempts to vault a repository that does not exist in your organization, it will automatically attempt to fork the original repository. To enable this feature:

  1. Ensure the optional dependency pygithub is installed (e.g., uv pip install uvault[github]).
  2. The source repository must be hosted on GitHub (provider = "github.com").
  3. You must provide a valid token in your user configuration (~/.config/uvault/config.toml) under the [github] section (key token).

How to create a secure Fine-grained GitHub Token for forking:

If you want to restrict your token so it can only fork repositories into your target organization (e.g., apycod) and nothing else:

  1. Go to your GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens.
  2. Click Generate new token.
  3. Resource owner: Select your target organization (e.g., apycod). Note: You must have sufficient privileges in the organization, and it must allow fine-grained PATs.
  4. Repository access: Select All repositories (required because the token needs permission to create new repositories that do not exist yet).
  5. Permissions:
  6. Under Repository permissions, set Administration to Read and write (required to create the fork).
  7. Set Contents to Read and write.
  8. Generate the token and paste it into your ~/.config/uvault/config.toml file. (Note: Fine-grained tokens have implicit read access to all public repositories, which allows them to read the upstream source repository before forking it into your organization).

uvault add

Adds a new dependency intention directly into [tool.uvault.sources] without manual file editing.

Arguments:

  • <package> : The name of the package to add.
  • [url] : (Optional) The VCS URL (e.g. https://github.com/OCA/my-addon). If omitted, uvault will attempt to guess it from PyPI metadata.

Options:

  • --branch <name> : Target a specific branch.
  • --tag <name> : Target a specific tag.
  • --pr <number> : Target a pull/merge request number.
  • --rev <hash> : Target a specific commit hash or exact reference.
  • --subdirectory <path> : The subdirectory within the repository where the Python package is located.

uvault develop

Switches a vaulted dependency into local editable mode for active development.

Arguments:

  • <package> : The name of the package to develop locally (must be declared in [tool.uvault.sources]).
  • <branch> : The name of the branch to checkout or create.

Workflow Details:

  1. Clones (using a fast partial blobless clone) or fetches the repository into your .src/ directory.
  2. Creates and checks out the new branch (git checkout -b <branch>), or switches to it if it exists (git checkout <branch>).
  3. Sets up remotes, including origin, vault, and any other custom remotes defined in ~/.config/uvault/config.toml.
  4. Modifies [tool.uv.sources] to use { path = "./.src/<package>", editable = true }.

uvault release

Updates the tags in [tool.uv.sources] with the new project version, keeping the exact same commit references.

Workflow Details:

When releasing a project (e.g., via bump-my-version), this command extracts the existing commit SHA from each vaulted package's tag in [tool.uv.sources]. It then constructs a new tag with the new project version and pushes it directly to the vault. This avoids fetching any new, unexpected commits from the source repository. Packages currently in develop mode will fall back to a standard sync.

Flags:

  • -P <package>, --package <package> : Apply the release tag only to the specified vaulted package. Can be used multiple times.
  • --keep-develop : By default, packages in develop mode are restored to their vaulted state before tagging. Use this flag to keep them in develop mode (skipping their release).