ruff/docs/integrations.md

Integrations

GitHub Actions

GitHub Actions has everything you need to run Ruff out-of-the-box:

name: CI
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install ruff
      # Update output format to enable automatic inline annotations.
      - name: Run Ruff
        run: ruff check --output-format=github .

Ruff can also be used as a GitHub Action via ruff-action.

By default, ruff-action runs as a pass-fail test to ensure that a given repository doesn't contain any lint rule violations as per its configuration. However, under-the-hood, ruff-action installs and runs ruff directly, so it can be used to execute any supported ruff command (e.g., ruff check --fix).

ruff-action supports all GitHub-hosted runners, and can be used with any published Ruff version (i.e., any version available on PyPI).

To use ruff-action, create a file (e.g., .github/workflows/ruff.yml) inside your repository with:

name: Ruff
on: [ push, pull_request ]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3

Alternatively, you can include ruff-action as a step in any other workflow file:

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

ruff-action accepts optional configuration parameters via with:, including:

• version: The Ruff version to install (default: latest).
• args: The command-line arguments to pass to Ruff (default: "check").
• src: The source paths to pass to Ruff (default: [".", "src"]).

For example, to run ruff check --select B ./src using Ruff version 0.8.0:

- uses: astral-sh/ruff-action@v3
  with:
    version: 0.8.0
    args: check --select B
    src: "./src"

GitLab CI/CD

You can add the following configuration to .gitlab-ci.yml to run a ruff format in parallel with a ruff check compatible with GitLab's codequality report.

.base_ruff:
  stage: build
  interruptible: true
  image:
    name: ghcr.io/astral-sh/ruff:0.12.12-alpine
  before_script:
    - cd $CI_PROJECT_DIR
    - ruff --version

Ruff Check:
  extends: .base_ruff
  script:
    - ruff check --output-format=gitlab > code-quality-report.json
  artifacts:
    reports:
      codequality: $CI_PROJECT_DIR/code-quality-report.json

Ruff Format:
  extends: .base_ruff
  script:
    - ruff format --diff

pre-commit

Ruff can be used as a pre-commit hook via ruff-pre-commit:

- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff version.
  rev: v0.12.12
  hooks:
    # Run the linter.
    - id: ruff-check
    # Run the formatter.
    - id: ruff-format

To enable lint fixes, add the --fix argument to the lint hook:

- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff version.
  rev: v0.12.12
  hooks:
    # Run the linter.
    - id: ruff-check
      args: [ --fix ]
    # Run the formatter.
    - id: ruff-format

To avoid running on Jupyter Notebooks, remove jupyter from the list of allowed filetypes:

- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff version.
  rev: v0.12.12
  hooks:
    # Run the linter.
    - id: ruff-check
      types_or: [ python, pyi ]
      args: [ --fix ]
    # Run the formatter.
    - id: ruff-format
      types_or: [ python, pyi ]

When running with --fix, Ruff's lint hook should be placed before Ruff's formatter hook, and before Black, isort, and other formatting tools, as Ruff's fix behavior can output code changes that require reformatting.

When running without --fix, Ruff's formatter hook can be placed before or after Ruff's lint hook.

(As long as your Ruff configuration avoids any linter-formatter incompatibilities, ruff format should never introduce new lint errors, so it's safe to run Ruff's format hook after ruff check --fix.)

mdformat

mdformat is capable of formatting code blocks within Markdown. The mdformat-ruff plugin enables mdformat to format Python code blocks with Ruff.

Docker

Ruff provides a distroless Docker image including the ruff binary. The following tags are published:

• ruff:latest
• ruff:{major}.{minor}.{patch}, e.g., ruff:0.6.6
• ruff:{major}.{minor}, e.g., ruff:0.6 (the latest patch version)

In addition, ruff publishes the following images:

• Based on alpine:3.20:
  • ruff:alpine
  • ruff:alpine3.20
• Based on debian:bookworm-slim:
  • ruff:debian-slim
  • ruff:bookworm-slim
• Based on buildpack-deps:bookworm:
  • ruff:debian
  • ruff:bookworm

As with the distroless image, each image is published with ruff version tags as ruff:{major}.{minor}.{patch}-{base} and ruff:{major}.{minor}-{base}, e.g., ruff:0.6.6-alpine.