softdevtools-dns

Подготовка и сопровождение: черновик для преподавателя

Статус: публичный пилот. Workflow проверки PR и применения DNS работают. После merge PR #4 запись denis-radchenko.softdevtools.ru создана через Cloudflare API и проверена на авторитетных NS и по HTTP. Проверенный HTTPS остаётся отдельным этапом.

До открытия студентам

  1. Провести пилот с двумя GitHub-аккаунтами и тестовыми поддоменами: Pages → Custom domain → CNAME → HTTP → проверенный HTTPS. Не подтверждать родительский softdevtools.ru в аккаунте преподавателя без проверки последствий для студенческих сайтов.
  2. Реализовать и проверить валидатор без секретов, затем проверяющий скрипт для опубликованной страницы. Убедиться, что сообщение об ошибке понятно студенту и временное ожидание не выглядит как провал.
  3. Реализовать идемпотентный деплой Cloudflare; проверить dry-run, отказ при конфликте и запрет изменения посторонних DNS-записей.
  4. Защитить main: обязательный PR, review, актуальные успешные проверки и контроль изменений workflow/скриптов. Протестировать параллельные заявки на одно имя и изменение системных файлов через fork. Перед открытием репозитория проверить, что политика GitHub разрешает pull_request_target для доверенной проверки заявок из fork.
  5. Выпустить отдельный Cloudflare API Token с правом DNS Edit только для softdevtools.ru; хранить его только в GitHub Actions Secrets или Environment Secrets. Не копировать значение токена в файлы и логи.
  6. Просмотреть всю историю и файлы перед сменой видимости репозитория: секреты, ФИО, группы и контактные email не должны оказаться публичными. Открывать репозиторий студентам после успешного пилота и проверки.

На текущем GitHub Free защита ветки для приватного репозитория недоступна: API GitHub возвращает требование GitHub Pro либо публичной видимости. Поэтому пункты о защите main и проверке внешнего fork завершаются после открытия репозитория. В пилоте только владелец имеет доступ на запись; CLOUDFLARE_DNS_DEPLOY_ENABLED=true уже включает запись после merge PR. Перед доступом студентов защитить main и проверить внешний fork. См. условия защиты веток GitHub.

Перед доступом студентов проверьте существующие GitHub Actions Secret CLOUDFLARE_API_TOKEN и Variable CLOUDFLARE_ZONE_ID. Для пробного чтения зоны запустите из доверенного checkout без --apply:

python3 -m scripts.apply_dns .

Токен и ID зоны берутся из переменных окружения с теми же именами; не вводите токен в командную строку или файлы. Пустой набор records/ даёт пустой план, поэтому для проверки нужен набор заявок и отдельная проверка получившихся записей. Сейчас шаг записи выполняется по слитым PR с изменениями в records/*.yaml. До открытия студентам прямые push в main должны быть запрещены правилами защиты ветки.

Во время выполнения

  1. Сверить автора PR с отдельным закрытым реестром. Способ создания реестра пока обсуждается; возможен отдельный закрытый репозиторий. Публичный email GitHub для этого не подходит как обязательный идентификатор.
  2. Проверить свободное имя, соответствие target и репозитория сайта, результат CI и отсутствие изменений рабочих файлов. Для имени вне предпочтительного формата imya-familiya согласовать псевдоним отдельно; не требовать публикации реальных имени и фамилии в DNS. Замечания валидатора приходят аннотациями к файлу и строке заявки, полный список — в сводке шага (Summary) прогона; формулировки адресованы студенту.
  3. Принять только проверенный PR. После merge проверить результат workflow деплоя и фактическую запись в Cloudflare. Ошибку деплоя не считать ошибкой студента без разбора причины.
  4. Для очной части принять DNS и нужную страницу по HTTP/HTTPS. Сертификат и Enforce HTTPS могут появиться позже; повторная автоматическая проверка должна довести статус до конца. Её план и ещё не принятые решения описаны в плане проверки сайтов.
  5. Оценивать отдельно объяснение студентом цепочки публикации. Автоматический статус не равен оценке.

Студенческая инструкция рассчитана на веб-интерфейс GitHub и браузер: командная строка, clone и curl не являются обязательными действиями. Перед выдачей инструкции проверить её на компьютере аудитории и добавить скриншоты.

Приёмка пачкой заявок

Защита main настроена без требования «Require branches to be up to date» (в API — requiresStrictStatusChecks: false). Обязательные проверки — validate и validate-student-request; для заявок из fork работает вторая, и она проверяет merge-ветку refs/pull/N/merge — голову PR, слитую с main на момент запуска. Поэтому «This branch is out-of-date» приёмку больше не блокирует, и кнопку «Update branch» нажимать не нужно.

Обратная сторона: проверка гарантирована только для того состояния main, которое было на момент запуска. Раньше требование «up to date» заставляло ветку обновиться и пройти проверку заново на свежем main; теперь этого шага нет, и слияние двух заявок проверяется только постфактум — прогоном на push в main. Для независимых records/*.yaml это почти всегда безопасно; единственный значимый случай — заявки на одно и то же имя.

Дубли поддоменов и красный прогон на main

Два студента могут занять одно имя: каждый PR в отдельности зелёный, потому что в его merge-ветке файла второго ещё нет. После merge обоих main становится красным:

Порядок разбора:

  1. Это не ошибка студента: расхождение создал порядок приёмки, а не его файл.
  2. Обычным PR восстановить main: оставить файл того, чей PR влит раньше (правило «первого merge» зафиксировать заранее), удалить второй файл и предложить второму студенту свободный вариант — суффикс -2 или согласованный псевдоним.
  3. Убедиться, что прогон Validate DNS requests на push в main снова зелёный. Применение повторится само при следующем merge с изменениями в records/*.yaml (в том числе при merge самого исправления) либо вручную через Re-run all jobs у Apply approved DNS requests.

Чтобы этого не возникало, перед merge очередной заявки сверяться с именами в records/ и среди других открытых PR. Если приоритет — гарантия проверенного слияния, требование можно вернуть: параметр requiresStrictStatusChecks: true через API или Settings → Branches → Require branches to be up to date before merging; тогда «устаревшие» ветки снова потребуют «Update branch» и повторной проверки.

Вопросы к следующему обсуждению

Подробности схемы и проверок: технический проект.