CI/CD — GitHub Actions

Локальный запуск Ruff — это отлично, но настоящая ценность линтера раскрывается, когда он запускается автоматически в CI/CD. Без автоматизации проверки кода человеческий фактор неизбежен: кто-то забудет запустить Ruff перед коммитом, кто-то проигнорирует предупреждения, а кто-то вообще не будет использовать линтер. CI/CD решает эту проблему: каждый коммит и каждый pull request проходят автоматическую проверку, и код с ошибками просто не может попасть в основную ветку.

Преимущества автоматической проверки кода в CI/CD:

• Гарантия качества — ни один коммит с синтаксическими ошибками или нарушением стиля не попадёт в main.
• Скорость ревью — код-ревьюеры тратят меньше времени на стилистические замечания и больше на логику.
• Единый стандарт — вся команда автоматически следует одним правилам, независимо от личных предпочтений.
• Экономия времени — Ruff делает проверку за секунды, а не минуты, как другие инструменты.
• Автоматические аннотации — ошибки отображаются прямо в diff Pull Request на GitHub.

Есть три основных способа запустить Ruff в GitHub Actions, и выбор между ними зависит от ваших потребностей:

astral-sh/ruff-action — официальный GitHub Action от команды Ruff. Он автоматически загружает последнюю версию Ruff, устанавливает её и запускает проверку. Это самый простой и рекомендуемый способ интеграции.

Создай файл .github/workflows/lint.yml в корне репозитория:

name: Lint

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3

Этот минимальный workflow:

• Запускается на push в main/master и на каждый pull request
• Выполняет ruff check на всём проекте
• Если найдены ошибки — workflow завершается с кодом 1 (failure)

Вот что делает Action «под капотом»:

1. Проверяет, установлен ли уже Ruff в кеше GitHub Actions
2. Если нет — скачивает готовый бинарник с GitHub Releases
3. Сохраняет бинарник в кеш для последующих запусков
4. Запускает ruff check с переданными аргументами

Action поддерживает ряд параметров, которые позволяют тонко настроить его поведение:

Пример с указанием версии и дополнительных аргументов:

- uses: astral-sh/ruff-action@v3
  with:
    version: "0.9.0"
    args: --output-format=github --line-length=120 --target-version=py311

Одна из самых полезных возможностей Ruff в GitHub Actions — автоматические аннотации ошибок в Pull Request. Когда Ruff запускается с флагом --output-format=github, он выводит результаты в формате, который GitHub Actions автоматически преобразует в аннотации прямо в diff затронутых файлов.

Пример workflow с аннотациями через astral-sh/ruff-action:

name: Lint with Annotations

on: [push, pull_request]

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

Если вы предпочитаете устанавливать Ruff через pip (например, если вы хотите контролировать версию через зависимости проекта):

name: Lint

on: [push, pull_request]

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

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

      - name: Install Ruff
        run: pip install ruff

      - name: Lint
        run: ruff check --output-format=github .

      - name: Format check
        run: ruff format --check .

Разберём этот workflow по шагам:

1. actions/checkout@v4 — клонирует репозиторий на runner
2. actions/setup-python@v5 — устанавливает Python 3.12
3. pip install ruff — устанавливает Ruff через pip
4. ruff check --output-format=github . — запускает линтинг с аннотациями
5. ruff format --check . — проверяет форматирование (без изменений, только проверка)

Ruff поддерживает несколько форматов вывода, каждый из которых имеет свои преимущества в CI/CD:

GitHub-формат особенно полезен: он выводит ошибки в формате ::warning file={file},line={line},col={col},title={code}::{message}, который GitHub Actions автоматически парсит и показывает как аннотации прямо в diff Pull Request. Ревьюеру не нужно открывать логи workflow — ошибки видны прямо в интерфейсе просмотра кода.

Если ваш проект уже использует uv (быстрый менеджер пакетов от Astral), вы можете запускать Ruff через uvx — утилиту, которая запускает инструменты без их явной установки. uvx скачивает и кеширует бинарник Ruff при первом запуске, а при повторных использует локальный кеш.

Преимущества uv-подхода в CI:

• Минимальное время установки — uv написан на Rust и работает намного быстрее pip
• Автоматическое кеширование — uv кеширует бинарники между запусками
• Не нужен Python — uvx может запускать Ruff без установленного Python
• Единый инструментарий — если вы уже используете uv для управления проектом

name: Lint

on: [push, pull_request]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4

      - name: Lint
        run: uvx ruff check --output-format=github .

      - name: Format check
        run: uvx ruff format --check .

Что происходит на каждом шаге:

1. astral-sh/setup-uv@v4 — устанавливает uv (занимает ~1 секунду)
2. uvx ruff check — uvx проверяет, есть ли ruff в кеше. Если нет — скачивает и кеширует. Затем запускает.
3. uvx ruff format --check — то же для проверки форматирования. Бинарник уже закеширован.

Полный рабочий процесс занимает 5–10 секунд на типичном проекте, что значительно быстрее альтернатив с pip.

GitHub Actions поддерживает матричные сборки — запуск одного и того же workflow с разными параметрами. Это полезно, если вы хотите проверить код на нескольких версиях Python, на разных ОС или с разными настройками Ruff.

Пример матричного запуска Ruff на нескольких версиях Python и ОС:

name: Ruff Matrix

on: [push, pull_request]

jobs:
  ruff:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.10", "3.11", "3.12"]
      fail-fast: false

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install Ruff
        run: pip install ruff

      - name: Run Ruff
        run: ruff check --output-format=github .

Параметры матрицы:

• os — три операционные системы (Ubuntu, macOS, Windows)
• python-version — три версии Python (3.10, 3.11, 3.12)
• fail-fast: false — если одна комбинация упала, остальные продолжают работу

Итого будет запущено 3 × 3 = 9 параллельных задач. Это может быть избыточно для Ruff (который проверяет статический анализ, не зависящий от версии Python), но полезно, если вы хотите убедиться, что код работает во всех окружениях.

Более практичный пример — матрица с разными наборами правил Ruff:

name: Ruff with Rule Sets

on: [pull_request]

jobs:
  ruff:
    strategy:
      matrix:
        ruleset:
          - "E,F"        # pycodestyle + Pyflakes
          - "I"          # isort
          - "N"          # pep8-naming
          - "UP,B,S"     # pyupgrade + bugbear + bandit

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          args: --select ${{ matrix.ruleset }} --output-format=github

Такой подход позволяет:

• Изолировать ошибки по категориям правил
• Быстро понять, какая группа правил вызывает проблемы
• Параллельно запускать проверки — общее время меньше

Линтинг и форматирование — разные задачи, и их можно (а иногда и нужно) запускать в отдельных workflow. Вот несколько причин для разделения:

• Разные триггеры — проверку форматирования можно запускать реже
• Разные требования к версиям — lint может требовать определенного набора правил
• Параллелизм — задачи выполняются одновременно, сокращая общее время
• Читаемость логов — проще найти проблему в отдельном workflow

Workflow для линтинга (.github/workflows/lint.yml)

name: Lint

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

Workflow для форматирования (.github/workflows/format.yml)

name: Format

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

Также можно объединить обе задачи в одном workflow, но в разных jobs — это даёт параллельный запуск и чистый интерфейс:

name: Ruff

on: [push, pull_request]

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

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

GitHub Actions определяет успешность шага по exit code — коду завершения процесса. Ruff использует следующие exit коды:

Как это работает в CI:

• Exit 0 — всё чисто, workflow помечается зелёной галочкой
• Exit 1 — найдены ошибки, workflow помечается красным крестом. PR нельзя смержить (если настроены branch protection rules)

Если вам нужно игнорировать exit code Ruff (например, в переходный период, когда вы постепенно внедряете правила), используйте continue-on-error: true:

- name: Lint
  continue-on-error: true
  run: ruff check --output-format=github .

- name: Format check
  continue-on-error: true
  run: ruff format --check .

С continue-on-error: true workflow продолжит работу, даже если Ruff найдёт ошибки. Шаг будет отмечен жёлтым предупреждением, но не заблокирует PR. Это полезно на этапе внедрения Ruff в существующий проект.

Кеширование позволяет ускорить повторные запуски workflow, сохраняя бинарник Ruff или виртуальное окружение между запусками. GitHub Actions предоставляет встроенное кеширование через actions/cache.

Кеширование бинарника Ruff через actions/cache

name: Lint with Caching

on: [push, pull_request]

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

      - name: Cache Ruff
        uses: actions/cache@v4
        id: cache-ruff
        with:
          path: ~/.cache/ruff
          key: ${{ runner.os }}-ruff-${{ hashFiles('**/ruff.toml', '**/pyproject.toml') }}
          restore-keys: |
            ${{ runner.os }}-ruff-

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

Как работает кеширование Ruff:

• Ruff хранит кеш анализа в ~/.cache/ruff
• При повторном запуске Ruff проверяет, изменились ли файлы
• Если файлы не изменились — Ruff использует кеш и завершается за миллисекунды
• Ключ кеша включает хеш конфигурационных файлов — при изменении настроек кеш сбрасывается

Кеширование виртуального окружения с pip

Если вы устанавливаете Ruff через pip, можно кешировать виртуальное окружение:

- name: Cache pip
  uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt', '**/pyproject.toml') }}
    restore-keys: |
      ${{ runner.os }}-pip-

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

- name: Install Ruff
  run: pip install ruff

Кеширование uv

Если вы используете uv, кеширование выполняется автоматически через astral-sh/setup-uv, но можно настроить и вручную:

- name: Cache uv
  uses: actions/cache@v4
  with:
    path: ~/.cache/uv
    key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml') }}
    restore-keys: |
      ${{ runner.os }}-uv-

- uses: astral-sh/setup-uv@v4

Запуск только на изменённых файлах

На больших проектах может быть полезно запускать Ruff только на изменённых файлах в PR, а не на всём проекте. Это ускоряет CI. Можно использовать tj-actions/changed-files для получения списка изменённых файлов:

name: Lint Changed Files

on: [pull_request]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed Python files
        id: changed-files
        uses: tj-actions/changed-files@v45
        with:
          files: |
            **/*.py

      - uses: astral-sh/ruff-action@v3
        with:
          src: ${{ steps.changed-files.outputs.all_changed_files }}

Проверка с фиксацией ошибок

Можно настроить workflow так, чтобы Ruff автоматически исправлял ошибки и коммитил изменения:

name: Auto-fix with Ruff

on:
  pull_request:
    branches: [main]

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: astral-sh/ruff-action@v3
        with:
          args: check --fix

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

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "style: auto-fix with Ruff"
          branch: ${{ github.head_ref }}

Отдельный workflow для разных веток

Можно настроить разные правила для разных веток — например, на main строгие правила, а на develop — более мягкие:

name: Strict Lint

on:
  push:
    branches: [main]

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

name: Basic Lint

on:
  push:
    branches: [develop]

jobs:
  basic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          args: check --output-format=github --select E,F

На main запускаются все правила (--select ALL), а на develop — только базовые (--select E,F). Это позволяет постепенно наводить порядок.

Давайте пройдём полный путь настройки Ruff в GitHub Actions — от создания файла до production-готового workflow.

Шаг 1: Создайте структуру директорий

mkdir -p .github/workflows
touch .github/workflows/lint.yml

Шаг 2: Напишите базовый workflow

name: Ruff

on: [push, pull_request]

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

Шаг 3: Закоммитьте и отправьте в GitHub

git add .github/workflows/lint.yml
git commit -m "ci: add Ruff linter and formatter"
git push

Шаг 4: Проверьте результат

Откройте вкладку Actions в вашем репозитории на GitHub. Вы должны увидеть запущенный workflow «Ruff». Если код чист — он будет зелёным. Если есть ошибки — красным.

Шаг 5: Настройте branch protection (опционально)

Чтобы запретить мёрж PR с ошибками Ruff, перейдите в Settings → Branches → Add branch protection rule. Включите «Require status checks to pass before merging» и выберите «Ruff / lint» и «Ruff / format».

Теперь вы знаете, как добавить Ruff в GitHub Actions. В следующем модуле мы рассмотрим настройку Ruff для больших проектов, работу с монорепозиториями и стратегии постепенного внедрения.