Adds `require-checksums`, which enforces the "intrinsic or explicitly provided checksum" idea. See #1032. <details> <summary>Automated notes</summary> Add the opt-in input `require-checksums`. When enabled, setup-uv verifies the archive against the workflow's `checksum` input or the digest bundled for the resolved uv version, architecture, and platform. If neither is available, setup fails before downloading the archive. By default, setup-uv continues to accept manifest checksums as it does today. The setting also applies to custom manifests, which can still supply download URLs. On persistent runners, strict mode keys tool-cache entries by the expected archive digest so a previous manifest-verified installation cannot bypass the check. Closes #1032. Builds on #1033. ## Validation - `npm ci --ignore-scripts` and `npm run all` passed under Node 24 (182 tests). - The packaged-action regression test installs a custom build into a temporary runner tool cache. It checks that strict mode rejects a manifest-only version even with a warm cache, reuses a verified installation for the same digest, and rejects a changed digest or a custom build that conflicts with the bundled digest. </details> --------- Signed-off-by: William Woodruff <william@yossarian.net>
4.1 KiB
Advanced Version Configuration
This document covers advanced options for configuring which version of uv to install.
Install the latest version
- name: Install the latest version of uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: "latest"
Install the latest version with a checksum verified by this action
Use latest-known to install the newest uv version whose checksums were bundled with the version of setup-uv used by your workflow. Version resolution is performed locally without fetching the latest release, so updating setup-uv also updates the version selected by latest-known.
When manifest-file is set, latest-known still selects a version from setup-uv's bundled checksum table.
By default the custom manifest supplies the artifact and checksum. To require a bundled or explicitly
supplied checksum, enable require-checksums. Checksum validation
- name: Install the latest version of uv known to setup-uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: "latest-known"
Install a specific version
- name: Install a specific version of uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: "0.4.4"
Install a version by supplying a semver range or pep440 specifier
You can specify a semver range or pep440 specifier to install the latest version that satisfies the range.
- name: Install a semver range of uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: ">=0.4.0"
- name: Pinning a minor version of uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: "0.4.x"
- name: Install a pep440-specifier-satisfying version of uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: ">=0.4.25,<0.5"
Resolution strategy
By default, when resolving version ranges, setup-uv will install the highest compatible version.
You can change this behavior using the resolution-strategy input:
- name: Install the lowest compatible version of uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: ">=0.4.0"
resolution-strategy: "lowest"
The supported resolution strategies are:
highest(default): Install the latest version that satisfies the constraintslowest: Install the oldest version that satisfies the constraints
This can be useful for testing compatibility with older versions of uv, similar to uv's own --resolution-strategy option.
Install a version defined in a requirements or config file
You can use the version-file input to specify a file that contains the version of uv to install.
This can either be a pyproject.toml or uv.toml file which defines a required-version or
uv defined as a dependency in pyproject.toml or requirements.txt.
asdf .tool-versions is also supported for selecting uv. If neither
python-version nor UV_PYTHON is set, the python entry from the selected file is also exported
as UV_PYTHON. Only a single Python version is supported; multiple fallback versions and the asdf
ref:, path:, and system forms are ignored with a warning.
- name: Install uv based on the version defined in pyproject.toml
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version-file: "pyproject.toml"
If uv is locked as a dependency in your uv.lock, you can point version-file at the
lockfile to install the exact pinned version. This keeps CI runs deterministic and avoids
silently picking up a newer uv until the lockfile is updated.
- name: Install uv based on the version locked in uv.lock
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version-file: "uv.lock"