diff --git a/README.md b/README.md index 35304c5..f3be5ea 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ Set up your GitHub Actions workflow with a specific version of [uv](https://docs.astral.sh/uv/). -- Install a version of uv and add it to the path +- Install a version of uv and add it to PATH - Cache the installed version of uv to speed up consecutive runs on self-hosted runners - Register problem matchers for error output -- Optional: Cache the uv cache -- Optional: Verify the checksum of the downloaded uv executable +- (Optional) Persist the uv's cache in the GitHub Actions Cache +- (Optional) Verify the checksum of the downloaded uv executable ## Contents @@ -26,35 +26,28 @@ Set up your GitHub Actions workflow with a specific version of [uv](https://docs Example workflow in a real world project can be found [here](https://github.com/eifinger/hass-weenect/blob/main/.github/workflows/ci.yml) -### Install specific version - -You can also specify a specific version of uv +### Install the latest version (default) ```yaml -- name: Install a specific version - uses: astral-sh/setup-uv@v1 - with: - version: "0.4.4" -``` - -### Install latest version - -By default this action installs the version defined as `default` in `action.yml`. This gets -automatically updated in a new release of this action when a new version of uv is released. If you -don't want to wait for a new release of this action you can use `version: latest`. - -> [!WARNING] -> Using the `latest` version means that the uv executable gets downloaded every single time instead -> of loaded from the tools cache. This can take up to 20s depending on the download speed. This does -> not affect the uv cache. - -```yaml -- name: Install a specific version +- name: Install the latest version of uv uses: astral-sh/setup-uv@v1 with: version: "latest" ``` +> [!TIP] Using `latest` requires that uv download the executable on every run, which incurs a cost +> (especially on self-hosted runners). As an alternative, consider pinning the version to a specific +> release. + +### Install a specific version + +```yaml +- name: Install a specific version of uv + uses: astral-sh/setup-uv@v1 + with: + version: "0.4.4" +``` + ### Validate checksum You can also specify a checksum to validate the downloaded file. Checksums up to the default version @@ -71,9 +64,9 @@ are automatically verified by this action. The sha265 hashes can be found on the ### Enable caching -If you enable caching the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be cached to -the GitHub Actions Cache. This can speed up runs which can reuse the cache by several minutes. The -cache will always be reused on self-hosted runners. +If you enable caching, the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be cached to +the GitHub Actions Cache. This can speed up runs that reuse the cache by several minutes. The cache +will always be reused on self-hosted runners. You can optionally define a custom cache key suffix. @@ -86,8 +79,8 @@ You can optionally define a custom cache key suffix. cache-suffix: "optional-suffix" ``` -When the cache was successfully restored the output `cache-hit` will be set to `true` and you can -use it in subsequent steps. For the example above you can use it like this: +When the cache was successfully restored, the output `cache-hit` will be set to `true` and you can +use it in subsequent steps. For example, to use the cache in the above case: ```yaml - name: Do something if the cache was restored @@ -97,8 +90,8 @@ use it in subsequent steps. For the example above you can use it like this: #### Local cache path -If you want to save the cache to a local path other than the default path (`/tmp/setup-uv-cache`) -you can specify the path with the `cache-local-path` input. +If you want to save the cache to a local path other than the default path (`/tmp/setup-uv-cache`), +specify the path with the `cache-local-path` input. ```yaml - name: Define a custom uv cache path @@ -110,7 +103,7 @@ you can specify the path with the `cache-local-path` input. #### Cache dependency glob -If you want to control when the cache is invalidated you can specify a glob pattern with the +If you want to control when the cache is invalidated, specify a glob pattern with the `cache-dependency-glob` input. The cache will be invalidated if any file matching the glob pattern changes. The glob matches files relative to the repository root. @@ -132,8 +125,8 @@ changes. The glob matches files relative to the repository root. ### API rate limit -To avoid hitting the error `API rate limit exceeded` you can supply a GitHub token with the -`github-token` input. +To avoid hitting the error `API rate limit exceeded`, supply a GitHub token with the `github-token` +input. ```yaml - name: Install uv and supply a GitHub token @@ -144,12 +137,13 @@ To avoid hitting the error `API rate limit exceeded` you can supply a GitHub tok ## How it works -This action downloads uv from the releases of the [uv repo](https://github.com/astral-sh/uv) and -uses the [GitHub Actions Toolkit](https://github.com/actions/toolkit) to cache it as a tool to speed -up consecutive runs on self-hosted runners. +This action downloads uv from the uv repo's official +[GitHub Releases](https://github.com/astral-sh/uv) and uses the +[GitHub Actions Toolkit](https://github.com/actions/toolkit) to cache it as a tool to speed up +consecutive runs on self-hosted runners. -The installed version of uv is then added to the runner path so other steps can just use it by -calling `uv`. +The installed version of uv is then added to the runner PATH, enabling subsequent steps to invoke it +by name (`uv`). ## FAQ @@ -157,7 +151,7 @@ calling `uv`. No! This action was modelled as a drop-in replacement for `actions/setup-python` when using uv. -A simple example workflow could look like this: +For example: ```yaml - name: Checkout the repository @@ -170,7 +164,7 @@ A simple example workflow could look like this: run: uv run --frozen pytest ``` -If you want to have a specific python version installed you can use the command +To install a specific version of Python, use [`uv python install`](https://docs.astral.sh/uv/guides/install-python/): ```yaml @@ -184,12 +178,10 @@ If you want to have a specific python version installed you can use the command ### What is the default version? -By default, this action installs the version defined as `default` in `action.yml`. When a new -release of uv is published this triggers an automatic release of this action with the new version as -`default`. +By default, this action installs the latest version of uv. -If you have to know the version installed for other steps of your workflow you can use the -`uv-version` output: +If you require the installed version in subsequent steps of your workflow, use the `uv-version` +output: ```yaml - name: Checkout the repository diff --git a/action.yml b/action.yml index 719dee6..bf24164 100644 --- a/action.yml +++ b/action.yml @@ -4,7 +4,7 @@ author: "eifinger" inputs: version: description: "The version of uv to install" - default: "0.4.4" + default: "latest" checksum: description: "The checksum of the uv version to install" required: false