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 diff --git a/package-lock.json b/package-lock.json index 0a66155..1ed2af4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,7 +19,7 @@ "@octokit/rest": "^21.0.2" }, "devDependencies": { - "@types/node": "^22.5.3", + "@types/node": "^22.5.4", "@types/semver": "^7.5.8", "@typescript-eslint/eslint-plugin": "^7.15.0", "@typescript-eslint/parser": "^7.18.0", @@ -27,7 +27,7 @@ "eslint": "^8.57.0", "eslint-plugin-github": "^5.0.1", "eslint-plugin-import": "^2.30.0", - "eslint-plugin-jest": "^28.8.2", + "eslint-plugin-jest": "^28.8.3", "eslint-plugin-prettier": "^5.2.1", "jest": "^29.7.0", "js-yaml": "^4.1.0", @@ -2099,9 +2099,9 @@ "dev": true }, "node_modules/@types/node": { - "version": "22.5.3", - "resolved": "https://registry.npmjs.org/@types/node/-/node-22.5.3.tgz", - "integrity": "sha512-njripolh85IA9SQGTAqbmnNZTdxv7X/4OYGPz8tgy5JDr8MP+uDBa921GpYEoDDnwm0Hmn5ZPeJgiiSTPoOzkQ==", + "version": "22.5.4", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.5.4.tgz", + "integrity": "sha512-FDuKUJQm/ju9fT/SeX/6+gBzoPzlVCzfzmGkwKvRHQVxi4BntVbyIwf6a4Xn62mrvndLiml6z/UBXIdEVjQLXg==", "dependencies": { "undici-types": "~6.19.2" } @@ -3919,9 +3919,9 @@ } }, "node_modules/eslint-plugin-jest": { - "version": "28.8.2", - "resolved": "https://registry.npmjs.org/eslint-plugin-jest/-/eslint-plugin-jest-28.8.2.tgz", - "integrity": "sha512-mC3OyklHmS5i7wYU1rGId9EnxRI8TVlnFG56AE+8U9iRy6zwaNygZR+DsdZuCL0gRG0wVeyzq+uWcPt6yJrrMA==", + "version": "28.8.3", + "resolved": "https://registry.npmjs.org/eslint-plugin-jest/-/eslint-plugin-jest-28.8.3.tgz", + "integrity": "sha512-HIQ3t9hASLKm2IhIOqnu+ifw7uLZkIlR7RYNv7fMcEi/p0CIiJmfriStQS2LDkgtY4nyLbIZAD+JL347Yc2ETQ==", "dev": true, "dependencies": { "@typescript-eslint/utils": "^6.0.0 || ^7.0.0 || ^8.0.0" @@ -9567,9 +9567,9 @@ "dev": true }, "@types/node": { - "version": "22.5.3", - "resolved": "https://registry.npmjs.org/@types/node/-/node-22.5.3.tgz", - "integrity": "sha512-njripolh85IA9SQGTAqbmnNZTdxv7X/4OYGPz8tgy5JDr8MP+uDBa921GpYEoDDnwm0Hmn5ZPeJgiiSTPoOzkQ==", + "version": "22.5.4", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.5.4.tgz", + "integrity": "sha512-FDuKUJQm/ju9fT/SeX/6+gBzoPzlVCzfzmGkwKvRHQVxi4BntVbyIwf6a4Xn62mrvndLiml6z/UBXIdEVjQLXg==", "requires": { "undici-types": "~6.19.2" } @@ -10964,9 +10964,9 @@ } }, "eslint-plugin-jest": { - "version": "28.8.2", - "resolved": "https://registry.npmjs.org/eslint-plugin-jest/-/eslint-plugin-jest-28.8.2.tgz", - "integrity": "sha512-mC3OyklHmS5i7wYU1rGId9EnxRI8TVlnFG56AE+8U9iRy6zwaNygZR+DsdZuCL0gRG0wVeyzq+uWcPt6yJrrMA==", + "version": "28.8.3", + "resolved": "https://registry.npmjs.org/eslint-plugin-jest/-/eslint-plugin-jest-28.8.3.tgz", + "integrity": "sha512-HIQ3t9hASLKm2IhIOqnu+ifw7uLZkIlR7RYNv7fMcEi/p0CIiJmfriStQS2LDkgtY4nyLbIZAD+JL347Yc2ETQ==", "dev": true, "requires": { "@typescript-eslint/utils": "^6.0.0 || ^7.0.0 || ^8.0.0" diff --git a/package.json b/package.json index c136fde..026c84e 100644 --- a/package.json +++ b/package.json @@ -38,7 +38,7 @@ "@octokit/rest": "^21.0.2" }, "devDependencies": { - "@types/node": "^22.5.3", + "@types/node": "^22.5.4", "@types/semver": "^7.5.8", "@typescript-eslint/eslint-plugin": "^7.15.0", "@typescript-eslint/parser": "^7.18.0", @@ -46,7 +46,7 @@ "eslint": "^8.57.0", "eslint-plugin-github": "^5.0.1", "eslint-plugin-import": "^2.30.0", - "eslint-plugin-jest": "^28.8.2", + "eslint-plugin-jest": "^28.8.3", "eslint-plugin-prettier": "^5.2.1", "jest": "^29.7.0", "js-yaml": "^4.1.0",