GitHub Actions выполняет заранее описанные действия после события в репозитории. Например, проверяет файлы при изменении проекта и показывает, какая проверка прошла, а какая завершилась ошибкой. Это полезно, если инструкция часто меняется и обязательный раздел легко потерять.

Разберём устройство Actions и первую проверку README. Для настройки понадобятся свой репозиторий, права записи и разрешённые Actions. Python-скрипт можно проверить на компьютере; устанавливать сервер не требуется.

Документация и версии действий сверены 3 октября 2026 года. Скрипт проверен локально. Workflow в GitHub при подготовке не запускался: его облачный результат читатель проверяет в своём проекте.

Событие, workflow, задание и runner

Workflow — рабочий процесс в YAML-файле внутри .github/workflows/. YAML описывает настройки через строки и отступы. Событие определяет, когда запустить процесс: например, ручное подтверждение, новый коммит или открытый Pull Request.

Внутри процесса находятся jobs, то есть задания. У задания есть шаги: получить файлы, подготовить среду, выполнить команду. Runner — машина, которая исполняет задание. GitHub может предоставить её сам; существующий сервер с собственным runner — другой вариант, для первого примера он не нужен.

Action — готовый компонент шага. actions/checkout получает файлы репозитория, actions/setup-python подготавливает Python. Строка run исполняет указанную команду. Как устроен ручной запуск workflow.

Результат относится к конкретной версии проекта. Зелёный значок означает успех описанных шагов; он не подтверждает всё, что workflow вообще не проверяет.

Сначала выберите проверку и проверьте расходы

Для примера у README обязательны три раздела: «Как начать», «Как проверить результат», «Ограничения». Автоматическая проверка заметит потерю заголовка. Пустой или неверный текст под ним она не оценит.

До запуска посмотрите владельца репозитория, политики разрешённых Actions, включённое использование и бюджет. Стандартные GitHub-hosted runners в публичных репозиториях имеют бесплатные условия; в приватных расходуют включённые минуты, а превышение может оплачиваться. Более мощные runners и хранение учитываются отдельно. Тарификация GitHub Actions.

Для этого примера нужен стандартный Ubuntu runner, без ключей сторонних сервисов и публикации сайта. Если Actions отключены политикой организации, сначала уточните допустимый процесс.

Подготовьте README и скрипт

Используйте отдельный разрешённый репозиторий для знакомства или свой проект, где такая проверка нужна. В README должны быть разделы:

# Описание проекта

## Как начать
Откройте инструкцию проекта и выполните её первый шаг.

## Как проверить результат
Сопоставьте полученный результат с примером в инструкции.

## Ограничения
Перед использованием проверьте требования и права доступа.

Это короткий пример структуры. В рабочем документе заполните разделы фактическими сведениями о проекте.

Создайте в корне check_readme.py:

from pathlib import Path
import re
import sys

file_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("README.md")
required = {"## Как начать", "## Как проверить результат", "## Ограничения"}
if not file_path.is_file():
    print(f"FAIL: файл не найден: {file_path}")
    raise SystemExit(1)

# Заголовки внутри примеров кода не считаются разделами документа.
headings = set()
fence_char = None
fence_length = 0
for line in file_path.read_text(encoding="utf-8-sig").splitlines():
    marker = re.match(r"^\s{0,3}(`{3,}|~{3,})", line)
    if fence_char:
        if re.fullmatch(r"\s{0,3}" + re.escape(fence_char) +
                        "{" + str(fence_length) + r",}\s*", line):
            fence_char = None
        continue
    if marker:
        fence_char = marker[1][0]
        fence_length = len(marker[1])
        continue
    headings.add(line.rstrip())

missing = sorted(required - headings)
if missing:
    print("FAIL: нет разделов: " + ", ".join(missing))
    raise SystemExit(1)
print("PASS: обязательные разделы README найдены")

Скрипт читает файл, исключает ограждённые примеры кода и ищет точные строки заголовков. Он не обращается к сети и не требует сторонних пакетов. Если команда Python доступна локально, из папки этих файлов выполните:

python3 --version
python3 check_readme.py README.md

Ожидается сообщение PASS и код завершения 0. Если в отдельной копии убрать заголовок «Ограничения», должно появиться сообщение FAIL с этим разделом и код 1. Отсутствующий файл тоже даст объяснимую ошибку. Код завершения позволяет Actions отличить успех от провала.

Добавьте полный workflow

Сохраните .github/workflows/check-readme.yml в основной ветке:

name: Проверка README

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-24.04
    timeout-minutes: 3
    steps:
      # actions/checkout v7: получить файлы без сохранения токена для Git.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
        with:
          persist-credentials: false
      # actions/setup-python v7: выбрать версию Python явно.
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: '3.13'
      - name: Проверить обязательные разделы
        run: python check_readme.py README.md

Здесь workflow_dispatch разрешает ручной запуск. contents: read даёт токену чтение содержимого; timeout-minutes ограничивает длительность задания. Длинные значения после @ — commit SHA: они фиксируют конкретную редакцию компонента. Соответствие checkout v7 и setup-python v7 проверено на дату подготовки.

Через браузер файл можно добавить командой Add file → Create new file, указав весь путь. Сохраните README, скрипт и workflow. Для ручной кнопки workflow должен находиться в основной ветке (default branch).

Запустите и прочитайте конкретный результат

Откройте Actions, выберите «Проверка README», нажмите Run workflow и проверьте ветку перед запуском. Откройте созданный run, затем задание check и шаг «Проверить обязательные разделы».

Проверьте сообщение и commit SHA запуска. При успехе будет PASS: обязательные разделы README найдены. При отсутствующем разделе — FAIL с его именем. Отказ runner, квота и синтаксическая ошибка YAML — другие причины провала; их видно в соответствующем шаге или сообщении GitHub.

Для проверки ошибки создайте свою ветку, уберите один заголовок и вручную запустите процесс на этой ветке. Затем восстановите раздел, сохраните новый коммит и запустите процесс на новой версии. Повтор запуска старого run проверяет старую версию и не подтверждает исправление.

Когда подключать автоматический запуск

Когда ручной путь понятен, можно запускать ту же проверку при PR. Тогда автор правки увидит результат до её включения в основную ветку. В файле workflow замените блок on следующим фрагментом, сохранив остальные части:

on:
  workflow_dispatch:
  pull_request:
    paths:
      - README.md
      - check_readme.py
      - .github/workflows/check-readme.yml

Это изменение триггеров, а не самостоятельный workflow. Для доверия к проверке команда должна контролировать и документ, и скрипт: изменение проверяющего кода тоже требует ревью. Не передавайте секреты чужой ветке; для этой задачи они не нужны.

Полезные сценарии

Не потерять обязательные разделы документа. У команды есть согласованная структура README. Добавьте проверку, прочитайте результат для нужного коммита и исправьте пропущенный раздел. Получится видимое подтверждение структуры. Смысл текста по-прежнему проверяет человек.

Увидеть ошибку до принятия PR. Автор меняет инструкцию в отдельной ветке. Настройте событие pull_request, сопоставьте run с PR и изучите провалившийся шаг. Исправление должно пройти на новом коммите. Если проверка пропущена фильтром пути, отсутствие красного значка не означает, что она выполнялась.

Добавить проверку ссылок или сборки позже. Когда проекту нужна другая автоматизация, возьмите его штатную команду и объясните её вход и ожидаемый результат. Подключайте один понятный шаг за раз. Рабочий процесс не должен обещать проверку ссылок, пока такой команды в нём нет.

Если кнопка запуска не появилась, проверьте путь, основную ветку и политики Actions. Если скрипт не нашёл README, сопоставьте имена и ветку. Начальный результат — одна проверка с понятным содержанием, ошибкой и границей применимости.

Следующий шаг

Если после проверки нужен автоматический выпуск статического сайта, изучите отдельный процесс публикации: GitHub Pages — бесплатный хостинг статических сайтов прямо из GitHub.

Для проекта с регулярно меняющейся документацией полезно выбрать одну проверку, которая действительно ловит частую ошибку команды.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov.