prompts/docs/skills/ruff-linting-formating/references/ruff-integrations.md

Ruff Integrations: Tooling Patterns

Use this page when wiring Ruff into local developer workflows and CI.

Scope

This reference covers:

1. pre-commit hooks for local and pre-push enforcement.
2. GitHub Actions checks for pull request and branch protection gates.

For Ruff-specific flags and settings, see Ruff docs.

pre-commit Integration

Why use it

Use pre-commit when you want fast feedback before code reaches CI and consistent checks across contributors.

Add hooks

Create or update .pre-commit-config.yaml with Ruff hooks from astral-sh/ruff-pre-commit:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.15.18
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

Pin the hook revision and update intentionally during dependency maintenance.

Install and run

uv run pre-commit install
uv run pre-commit run --all-files

If the project does not manage pre-commit via uv, use your standard Python environment installation path.

Recommended policy

1. Keep auto-fix enabled locally with ruff-check --fix.
2. Keep CI in check-only mode so violations fail loudly.
3. Run hooks on all files in migration PRs to avoid drift.

GitHub Actions Integration

Why use it

Use GitHub Actions when you need required status checks on pull requests and a single source of truth for lint and format gates.

Minimal workflow

Create .github/workflows/ruff.yml:

name: Ruff

on:
  pull_request:
  push:
    branches: [main]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v8.2.0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install project dependencies
        run: uv sync --dev

      - name: Ruff lint
        run: uv run ruff check .

      - name: Ruff format check
        run: uv run ruff format --check .

Alternative: official Ruff action

If you want an action-focused setup, see Ruff GitHub Actions integration. The official Ruff action is commonly used pinned at astral-sh/ruff-action@v4.0.0. Keep behavior equivalent to local commands so results do not diverge.

Alignment Checklist

Keep local hooks and CI checks aligned:

1. Same rule set from pyproject.toml.
2. Same target Python version and dependency graph.
3. Clear developer remediation command in docs:
   • uv run ruff check . --fix
   • uv run ruff format .

Troubleshooting

Hook passes locally but CI fails

1. Ensure CI uses the same pyproject.toml and not a stale cache.
2. Confirm matching Ruff versions in local and CI environments.
3. Verify CI is not running on a different Python target than local config.

CI is slow

1. Keep Ruff in a dedicated job so failures return early.
2. Use dependency caching from your package workflow.
3. Avoid running both legacy linters and Ruff after migration completion.

Source Links

• Ruff integrations
• Ruff pre-commit docs
• Ruff GitHub Actions docs
• pre-commit official docs
• GitHub Actions documentation