# Ruff Integrations: Tooling Patterns

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

## Scope

This reference covers:

1. [pre-commit](https://pre-commit.com/) hooks for local and pre-push enforcement.
2. [GitHub Actions](https://docs.github.com/en/actions) checks for pull request and branch protection gates.

For Ruff-specific flags and settings, see [Ruff docs](./ruff-docs.md).

## 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](https://pre-commit.com/#2-add-a-pre-commit-configuration) with Ruff hooks from [astral-sh/ruff-pre-commit](https://github.com/astral-sh/ruff-pre-commit):

```yaml title=".pre-commit-config.yaml"
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

```bash
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](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions):

```yaml title=".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](https://docs.astral.sh/ruff/integrations/#github-actions). 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](https://docs.astral.sh/ruff/integrations/)
- [Ruff pre-commit docs](https://docs.astral.sh/ruff/integrations/#pre-commit)
- [Ruff GitHub Actions docs](https://docs.astral.sh/ruff/integrations/#github-actions)
- [pre-commit official docs](https://pre-commit.com/)
- [GitHub Actions documentation](https://docs.github.com/en/actions)