ruff Integration

Integrate ruff into editors, pre-commit hooks, and CI/CD pipelines.

When to Use This Skill

Use this skill when... Use ruff-linting instead when... Use ruff-formatting instead when...

Setting up VS Code / editor Configuring lint rules Configuring format options

Adding pre-commit hooks Selecting/ignoring rules Quote style, line length

Adding ruff to CI/CD Understanding rule categories Format differences

Docker/build integration Fixing lint violations Checking format compliance

VS Code Setup

// .vscode/settings.json { "[python]": { "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll": "explicit", "source.organizeImports": "explicit" }, "editor.defaultFormatter": "charliermarsh.ruff" }, "ruff.lint.args": ["--select=E,F,B,I"], "ruff.importStrategy": "fromEnvironment" }

Install extension

code --install-extension charliermarsh.ruff

Pre-commit Integration

.pre-commit-config.yaml

repos:

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

pre-commit install # Install hooks pre-commit run --all-files # Run manually pre-commit autoupdate # Update versions

GitHub Actions CI

.github/workflows/lint.yml

name: Lint on: [push, pull_request]

jobs: ruff: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: astral-sh/ruff-action@v3 with: args: 'check --output-format github'

Separate lint + format checks:

jobs: ruff-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: pip install ruff - run: ruff check --output-format github

ruff-format: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: pip install ruff - run: ruff format --check --diff

Configuration Hierarchy

• Command-line arguments (highest priority)

• Editor LSP settings

• ruff.toml in current directory

• pyproject.toml in current directory

• Parent directory configs (recursive)

• User config: ~/.config/ruff/ruff.toml

• Ruff defaults (lowest priority)

Best Practices

• Editor: Enable format-on-save, use project-specific .vscode/settings.json

• Pre-commit: Run ruff-check --fix first, then ruff-format

• CI/CD: Use --output-format github for PR annotations

• Performance: Cache ruff in CI, run on changed files only in pre-commit

• Team: Commit editor/pre-commit configs to version control

Agentic Optimizations

Context Command

Quick lint check ruff check --output-format github

Format check ruff format --check --diff

Auto-fix all ruff check --fix && ruff format

Errors only ruff check --select E

CI annotations ruff check --output-format github

JSON output ruff check --output-format json

Specific files ruff check --diff path/to/file.py

Quick Reference

Editor

code --install-extension charliermarsh.ruff

Pre-commit

pre-commit install && pre-commit run --all-files

CI (GitHub Actions)

uses: astral-sh/ruff-action@v3

Docker

docker run -v .:/app ghcr.io/astral-sh/ruff:0.14.0-alpine check /app

For editor configs (Neovim, Zed, Helix), GitLab/CircleCI/Jenkins CI, build system integration, Docker setup, LSP configuration, and migration guides, see REFERENCE.md.