Документация

Поддержка конвейеров CI

Этот документ описывает порядок обслуживания GitHub Actions в репозитории.

Канонический quality gate

Локальные команды и GitHub Actions используют один набор проверок:

.venv/bin/ruff check .
bash scripts/typecheck.sh
.venv/bin/j2lint templates
.venv/bin/pytest --ignore=tests/e2e --cov=app --cov=services --cov=utils --cov-fail-under=60
npm run test:frontend
npm run build
.venv/bin/mkdocs build --strict

Покрытие измеряется только при явном запуске coverage-команды. Обычный pytest не создаёт отчёты и не скрывает отсутствие pytest-cov. Текущий floor равен 60 % в Makefile, tox и compose-test. Базовый прогон от 2026-07-28: 767 passed, 62.11 % total coverage по app, services и utils.

make coverage повторяет CI-контур и исключает tests/e2e; браузерные проверки идут отдельным e2e gate. Для редкого полного локального замера вместе с e2e используйте make coverage-full.

GitHub Actions workflow пока оставлен на 55 %, потому что текущий GitHub token не имеет workflow scope и GitHub отклоняет push с изменением .github/workflows/main.yml. После обновления прав токена нужно поднять --cov-fail-under в workflow до 60 %.

Mypy проверяет стабильную типизированную границу из scripts/typecheck.sh. Динамические Flask-SQLAlchemy модели и миграционные маршруты остаются в задокументированном legacy-tier и не выдаются за полностью типизированные. Граница расширяется только вместе с исправлением модуля и его тестами; добавлять глобальные ignore_errors или ослаблять gate запрещено.

Для инвентаризации долга вне блокирующего gate используйте отдельный аудит:

.venv/bin/mypy --config-file=/dev/null --python-version 3.11 \
  --ignore-missing-imports --follow-imports=skip app services utils

Эта команда намеренно может завершаться ошибкой. Её результат классифицируют в датированном cleanup-отчёте; он не заменяет зелёный scripts/typecheck.sh.

Gitleaks блокирует секреты в текущем release tree. Переписывание истории для старых утечек выполняется только отдельной согласованной процедурой, поскольку оно меняет все commit SHA и требует повторной синхронизации клонов.

Обновление закреплённых GitHub Actions

Все используемые GitHub Actions закреплены на конкретные SHA-коммиты для повышения безопасности. Чтобы обновить действие до новой версии:

  1. Найдите свежий релиз нужного действия (через GitHub UI или gh release list).
  2. Получите SHA соответствующего тега. Самый простой способ – воспользоваться GitHub API: bash curl -s "https://api.github.com/repos/<owner>/<repo>/commits?sha=<tag>&per_page=1" \ | jq -r '.[0].sha' Например, для actions/checkout@v4.1.7 команда вернёт 692973e3d937129bcbf40652eb9f2f61becf3332.
  3. Обновите ссылку в .github/workflows/main.yml, подставив полученный SHA вместо старого значения.
  4. Пересмотрите журнал изменений действия и убедитесь, что оно совместимо с нашим пайплайном.
  5. Выполните локальный прогон ключевых задач (lint, type-check, tests) или запустите их через act, чтобы убедиться в отсутствии регрессий.
  6. Зафиксируйте изменения в Git вместе с кратким описанием обновления.

Примечание. Если обновляется сложный набор действий, удобнее сначала собрать список новых версий, а затем обновить их все в одном PR.

Защищённый деплой контейнеров

Job publish-container использует окружение container-registry. Чтобы включить ручное подтверждение перед публикацией образа:

  1. Откройте раздел Settings → Environments в репозитории.
  2. Создайте окружение container-registry (или отредактируйте существующее).
  3. Добавьте обязательных ревьюеров в блоке Required reviewers.
  4. Сохраните настройки. Теперь job остановится на этапе ожидания и продолжится только после одобрения.

Сохраняйте описание окружения в актуальном состоянии при смене процесса публикации.