# 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