A GitHub Action to run ruff.

This action is commonly used as a pass/fail test to ensure your repository stays clean, abiding the rules specified in your configuration. Though it runs ruff check by default, the action can do anything ruff can (ex, fix).

• Usage
  • Basic
  • Specify a different source directory
  • Specify multiple files
  • Use to install ruff
  • Use ruff format
  • Install specific versions
    • Install the latest version
    • Install a specific version
    • Install a version by supplying a semver range or pep440 specifier
    • Install a version from a specified version file
    • Install using a custom manifest URL
  • Validate checksum
  • GitHub authentication token
• Outputs

By default, Ruff version metadata is resolved from the astral-sh/versions Ruff manifest.

- uses: astral-sh/ruff-action@v3

- uses: astral-sh/ruff-action@v3
  with:
    src: "./src"

- uses: astral-sh/ruff-action@v3
  with:
    src: >-
      path/to/file1.py
      path/to/file2.py

This action adds ruff to the PATH, so you can use it in subsequent steps.

- 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):

- name: Install ruff without running check or format
  uses: astral-sh/ruff-action@v3
  with:
    args: "--version"

- uses: astral-sh/ruff-action@v3
  with:
    args: "format --check --diff"

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.

- name: Install the latest version of ruff
  uses: astral-sh/ruff-action@v3
  with:
    version: "latest"

- name: Install a specific version of ruff
  uses: astral-sh/ruff-action@v3
  with:
    version: "0.4.4"

You can specify a semver range or pep440 specifier to install the latest version that satisfies the range.

- name: Install a semver range of ruff
  uses: astral-sh/ruff-action@v3
  with:
    version: ">=0.4.0"

- name: Pinning a minor version of ruff
  uses: astral-sh/ruff-action@v3
  with:
    version: "0.4.x"

- name: Install a pep440-specifier-satisfying version of ruff
  uses: astral-sh/ruff-action@v3
  with:
    version: ">=0.11.10,<0.12.0"

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.

- 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

You can override the default astral-sh/versions manifest with manifest-file. This affects both version resolution and artifact selection.

- name: Install Ruff from a custom manifest
  uses: astral-sh/ruff-action@v3
  with:
    version: "latest"
    manifest-file: "https://example.com/ruff.ndjson"

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 of the ruff repo.

- name: Install a specific version and validate the checksum
  uses: astral-sh/ruff-action@v3
  with:
    version: "0.7.4"
    checksum: "0de731c669b9ece77e799ac3f4a160c30849752714d9775c94cc4cfaf326860c"

By default, this action resolves available uv versions from 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 are not sufficient, you can provide a custom GitHub token with the necessary permissions.

- 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 }}