Skip to content

SETUP.md

Latest commit

 

History

History
290 lines (208 loc) · 11 KB

SETUP.md

File metadata and controls

290 lines (208 loc) · 11 KB

GitHub CI/CD Setup Guide

Этот документ содержит инструкции по настройке и активации CI/CD workflows для проекта.

📋 Обзор

В проекте настроены следующие автоматизации:

  1. CI Workflow - основная проверка кода и тесты
  2. Pull Request Workflow - расширенные проверки для PR
  3. Dependabot - автоматическое обновление зависимостей

🚀 Быстрый старт

1. Убедитесь, что все файлы залиты в репозиторий

git add .github/
git commit -m "ci: add GitHub Actions workflows"
git push origin main

2. Проверьте статус workflows

После пуша перейдите на GitHub:

  • Откройте вкладку Actions в вашем репозитории
  • Вы увидите запущенный workflow CI
  • Убедитесь, что все проверки прошли успешно ✅

📝 Настройка Workflows

CI Workflow (.github/workflows/ci.yml)

Автоматически запускается при:

  • Push в ветку main
  • Создании/обновлении Pull Request в main

Что делает:

  • ✅ Проверяет код с помощью Ruff (linter + formatter)
  • ✅ Запускает все тесты с pytest
  • ✅ Генерирует отчет о покрытии кода
  • ✅ Сохраняет отчеты в артефакты

Как просмотреть артефакты:

  1. Перейдите в Actions → выберите конкретный запуск workflow
  2. Прокрутите вниз до секции Artifacts
  3. Скачайте coverage-report для просмотра покрытия кода

Pull Request Workflow (.github/workflows/pr.yml)

Автоматически запускается при:

  • Создании Pull Request в main или develop
  • Обновлении (push) в ветку с открытым PR

Что делает:

  • ✅ Проверяет формат заголовка PR (conventional commits)
  • ✅ Запускает Ruff linter и formatter
  • ✅ Проверяет измененные файлы с pre-commit
  • ✅ Запускает тесты с проверкой покрытия
  • ✅ Выполняет security-проверки
  • ✅ Формирует общий отчет о статусе всех проверок

Требования к заголовкам PR:

PR должны следовать формату Conventional Commits:

<type>: <description>

Примеры:
feat: add user authentication
fix: resolve database connection timeout
docs: update API documentation
test: add tests for user service
ci: update GitHub Actions workflow

Допустимые типы:

  • feat - новая функциональность
  • fix - исправление бага
  • docs - документация
  • style - форматирование кода
  • refactor - рефакторинг
  • perf - улучшение производительности
  • test - тесты
  • build - сборка проекта
  • ci - CI/CD
  • chore - рутинные задачи
  • revert - откат изменений

Dependabot (.github/dependabot.yml)

Автоматически:

  • Проверяет обновления Python пакетов каждый понедельник в 09:00
  • Проверяет обновления GitHub Actions каждый понедельник в 09:00
  • Создает PR с группированными обновлениями (minor + patch вместе)

Настройка уведомлений:

Dependabot автоматически создаст PR при обнаружении обновлений. Чтобы настроить уведомления:

  1. Перейдите в Settings → Notifications вашего GitHub аккаунта
  2. Включите уведомления для Pull requests
  3. Можете настроить email/web уведомления по желанию

Автоматическое слияние Dependabot PR:

Чтобы автоматически мержить безопасные обновления:

# Включить auto-merge для Dependabot PR
gh pr list --author "app/dependabot" --json number --jq '.[].number' | \
  xargs -I {} gh pr merge {} --auto --squash

🔧 Локальная проверка перед push

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

1. Проверка с pre-commit (автоматически при commit)

# Установить pre-commit хуки (один раз)
uv run pre-commit install

# Проверить все файлы вручную
uv run pre-commit run --all-files

2. Проверка с Ruff

# Проверить код линтером
uv run ruff check .

# Автоматически исправить проблемы
uv run ruff check . --fix

# Проверить форматирование
uv run ruff format --check .

# Отформатировать код
uv run ruff format .

3. Запуск тестов

# Установить зависимости
uv sync --group test --group dev

# Запустить все тесты
uv run pytest tests/ -v

# Запустить с покрытием кода
uv run pytest tests/ --cov=src --cov-report=term --cov-report=html

# Открыть HTML отчет о покрытии
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

🔒 GitHub Secrets (если требуется)

Если в будущем потребуется добавить секреты (API ключи, токены):

  1. Перейдите в Settings → Secrets and variables → Actions
  2. Нажмите New repository secret
  3. Добавьте секрет (например, DATABASE_URL, API_KEY)
  4. Используйте в workflow: ${{ secrets.YOUR_SECRET_NAME }}

📊 Status Badges

В README уже добавлен badge статуса CI:

[![CI](https://github.com/GAKiknadze/python_web_template/actions/workflows/ci.yml/badge.svg)](https://github.com/GAKiknadze/python_web_template/actions/workflows/ci.yml)

Можно добавить дополнительные badges:

<!-- PR Checks -->
[![PR Checks](https://github.com/GAKiknadze/python_web_template/actions/workflows/pr.yml/badge.svg)](https://github.com/GAKiknadze/python_web_template/actions/workflows/pr.yml)

<!-- Coverage -->
[![codecov](https://codecov.io/gh/GAKiknadze/python_web_template/branch/main/graph/badge.svg)](https://codecov.io/gh/GAKiknadze/python_web_template)

<!-- Python Version -->
[![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/release/python-3130/)

<!-- Code Style -->
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

🐛 Troubleshooting

Workflow не запускается

Проблема: После push workflow не появляется во вкладке Actions

Решение:

  1. Проверьте, что файлы workflow находятся в .github/workflows/
  2. Убедитесь, что YAML файлы валидны (проверьте синтаксис)
  3. Проверьте, что вы запушили в правильную ветку (main)

Тесты падают в CI, но проходят локально

Проблема: Локально тесты работают, в CI - нет

Возможные причины:

  1. Разные версии зависимостей - проверьте uv.lock
  2. Отсутствие переменных окружения - добавьте в GitHub Secrets
  3. Разные версии Python - убедитесь, что .python-version актуален
  4. Проблемы с путями - используйте относительные пути

Отладка:

# Запустить тесты точно так же, как в CI
uv sync --group test --group dev
uv run pytest tests/ -v --tb=short

Pre-commit блокирует коммит

Проблема: Pre-commit находит ошибки и не дает сделать commit

Решение:

# Автоматически исправить большинство проблем
uv run ruff check . --fix
uv run ruff format .

# Попробовать коммит снова
git add .
git commit -m "your message"

Dependabot создает слишком много PR

Проблема: Dependabot создает много PR с обновлениями

Решение:

Измените .github/dependabot.yml:

# Ограничить количество открытых PR
open-pull-requests-limit: 3  # вместо 10

# Реже проверять обновления
schedule:
  interval: "monthly"  # вместо weekly

📚 Дополнительные ресурсы

✅ Checklist для нового проекта

  • Залить все файлы .github/ в репозиторий
  • Проверить, что workflows запускаются
  • Установить pre-commit хуки локально
  • Убедиться, что все тесты проходят
  • Настроить уведомления от Dependabot
  • Добавить CI badge в README
  • Создать тестовый PR для проверки PR workflow
  • Настроить branch protection rules (опционально)

🛡️ Branch Protection Rules (рекомендуется)

Чтобы обязать проверки проходить перед мержем в main:

  1. Перейдите в Settings → Branches
  2. Нажмите Add rule для ветки main
  3. Включите:
    • ✅ Require status checks to pass before merging
    • ✅ Выберите: Lint with Ruff, Run Tests
    • ✅ Require branches to be up to date before merging
    • ✅ Require linear history (опционально)
    • ✅ Include administrators (рекомендуется)
  4. Сохраните правила

Теперь нельзя будет мержить PR, если проверки не прошли! 🎉