actions/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff-action.git synced 2026-05-12 12:40:14 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
ruff/README.md
T
Kevin Stillhammer 0ce1b0bf8b refactor version resolving (#353)
2026-04-12 13:44:40 +02:00

232 lines
8.4 KiB
Markdown
Raw Permalink Blame History

# ruff-action
A GitHub Action to run [ruff](https://github.com/astral-sh/ruff).
This action is commonly used as a pass/fail test to ensure your repository stays
clean, abiding the [rules](https://docs.astral.sh/ruff/rules/) specified in your
configuration. Though it runs `ruff check` by default, the action can do
anything `ruff` can (ex, fix).
## Contents
- [Usage](#usage)
- [Basic](#basic)
- [Specify a different source directory](#specify-a-different-source-directory)
- [Specify multiple files](#specify-multiple-files)
- [Use to install ruff](#use-to-install-ruff)
- [Use `ruff format`](#use-ruff-format)
- [Install specific versions](#install-specific-versions)
- [Install the latest version](#install-the-latest-version)
- [Install a specific version](#install-a-specific-version)
- [Install a version by supplying a semver range or pep440 specifier](#install-a-version-by-supplying-a-semver-range-or-pep440-specifier)
- [Install a version from a specified version file](#install-a-version-from-a-specified-version-file)
- [Install using a custom manifest URL](#install-using-a-custom-manifest-url)
- [Validate checksum](#validate-checksum)
- [GitHub authentication token](#github-authentication-token)
- [Outputs](#outputs)
## Usage
| Input | Description | Default |
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
| `version` | The version of Ruff to install. See [Install specific versions](#install-specific-versions) | discovered from `pyproject.toml`, else `latest` |
| `version-file` | The file to read the version from. See [Install a version from a specified version file](#install-a-version-from-a-specified-version-file) | None |
| `manifest-file` | URL to a custom Ruff manifest in the `astral-sh/versions` format. | None |
| `args` | The arguments to pass to the `ruff` command. See [Configuring Ruff] | `check` |
| `src` | The directory or single files to run `ruff` on. | [github.workspace] |
| `checksum` | The sha256 checksum of the downloaded artifact. | None |
| `github-token` | The GitHub token to use when downloading Ruff release artifacts from GitHub. | `GITHUB_TOKEN` |
By default, Ruff version metadata is resolved from the
[`astral-sh/versions` Ruff manifest](https://github.com/astral-sh/versions/blob/main/v1/ruff.ndjson).
### Basic
```yaml
- uses: astral-sh/ruff-action@v3
```
### Specify a different source directory
```yaml
- uses: astral-sh/ruff-action@v3
with:
src: "./src"
```
### Specify multiple files
```yaml
- uses: astral-sh/ruff-action@v3
with:
src: >-
path/to/file1.py
path/to/file2.py
```
### Use to install ruff
This action adds ruff to the PATH, so you can use it in subsequent steps.
```yaml
- uses: astral-sh/ruff-action@v3
- run: ruff check --fix
- run: ruff format
```
By default, this action runs `ruff check` after installation.
If you do not want to run any `ruff` command but only install it,
you can use the `args` input to overwrite the default value (`check`):
```yaml
- name: Install ruff without running check or format
uses: astral-sh/ruff-action@v3
with:
args: "--version"
```
### Use `ruff format`
```yaml
- uses: astral-sh/ruff-action@v3
with:
args: "format --check --diff"
```
### Install specific versions
By default this action searches upward from `src` until the workspace root to find the nearest
`pyproject.toml` and determine the Ruff version to install. If no `pyproject.toml` file is found,
or no Ruff version is defined in `project.dependencies`, `project.optional-dependencies`,
`dependency-groups`, or supported Poetry dependency tables, the latest version is installed.
> [!NOTE]
> This action does only support ruff versions v0.0.247 and above.
#### Install the latest version
```yaml
- name: Install the latest version of ruff
uses: astral-sh/ruff-action@v3
with:
version: "latest"
```
#### Install a specific version
```yaml
- name: Install a specific version of ruff
uses: astral-sh/ruff-action@v3
with:
version: "0.4.4"
```
#### Install a version by supplying a semver range or pep440 specifier
You can specify a [semver range](https://github.com/npm/node-semver?tab=readme-ov-file#ranges)
or [pep440 specifier](https://peps.python.org/pep-0440/#version-specifiers)
to install the latest version that satisfies the range.
```yaml
- name: Install a semver range of ruff
uses: astral-sh/ruff-action@v3
with:
version: ">=0.4.0"
```
```yaml
- name: Pinning a minor version of ruff
uses: astral-sh/ruff-action@v3
with:
version: "0.4.x"
```
```yaml
- name: Install a pep440-specifier-satisfying version of ruff
uses: astral-sh/ruff-action@v3
with:
version: ">=0.11.10,<0.12.0"
```
#### Install a version from a specified version file
You can specify a file to read the version from.
Currently `pyproject.toml` and `requirements.txt` are supported. If the file cannot be parsed
or does not contain a Ruff version, the action warns and falls back to `latest`.
```yaml
- name: Install a version from a specified version file
uses: astral-sh/ruff-action@v3
with:
version-file: "my-path/to/pyproject.toml-or-requirements.txt"
```
Version resolution precedence is:
1. `version`
2. `version-file`
3. nearest discoverable `pyproject.toml` found by searching upward from `src`
4. `latest`
#### Install using a custom manifest URL
You can override the default `astral-sh/versions` manifest with `manifest-file`.
This affects both version resolution and artifact selection.
```yaml
- name: Install Ruff from a custom manifest
uses: astral-sh/ruff-action@v3
with:
version: "latest"
manifest-file: "https://example.com/ruff.ndjson"
```
### Validate checksum
You can specify a checksum to validate the downloaded executable. Checksums up to the default version
are automatically verified by this action. The sha256 hashes can be found on the
[releases page](https://github.com/astral-sh/ruff/releases) of the ruff repo.
```yaml
- name: Install a specific version and validate the checksum
uses: astral-sh/ruff-action@v3
with:
version: "0.7.4"
checksum: "0de731c669b9ece77e799ac3f4a160c30849752714d9775c94cc4cfaf326860c"
```
### GitHub authentication token
By default, this action resolves available uv versions from
[`astral-sh/versions`](https://github.com/astral-sh/versions) and downloads release artifacts from `https://releases.astral.sh`. If this fails this action falls back to downloading from the GitHub releases page of the ruff repository.
You can provide a token via `github-token` to authenticate those downloads. By default, the
`GITHUB_TOKEN` secret is used, which is automatically provided by GitHub Actions.
If the default
[permissions for the GitHub token](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)
are not sufficient, you can provide a custom GitHub token with the necessary permissions.
```yaml
- name: Install the latest version of ruff with a custom GitHub token
uses: astral-sh/ruff-action@v3
with:
github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
```
## Outputs
| Output | Description |
|----------------|-----------------------------------------|
| `ruff-version` | The version of Ruff that was installed. |
<div align="center">
<a target="_blank" href="https://astral.sh" style="background:none">
<img src="https://raw.githubusercontent.com/astral-sh/uv/main/assets/svg/Astral.svg" alt="Made by Astral">
</a>
</div>
[Configuring Ruff]: https://github.com/astral-sh/ruff/blob/main/docs/configuration.md
[github.workspace]: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context
Reference in New Issue View Git Blame Copy Permalink