Отладка падающих пайплайнов

Системный подход к красным галочкам: где смотреть и что чаще всего ломается.

Падение пайплайна — это всегда конкретный шаг с ненулевым кодом; задача отладки — найти этот шаг и понять причину по логу.

Шаг 1. Найти упавший шаг

Откройте вкладку Actions → красный прогон → красный job. GitHub разворачивает именно тот step, что упал, и подсвечивает строку с ошибкой. Не угадывайте — читайте последние строки лога упавшего шага, там обычно текст ошибки и код возврата.

Типичные причины падений

Симптом	Частая причина
command not found	забыли setup-шаг или установку инструмента
файлов нет / пусто	забыли `actions/checkout`
тесты «вдруг» падают в CI	зависимость от локального окружения, часового пояса, порядка
permission denied при деплое	не хватает прав в `permissions` или неверный секрет
зависает на вводе	интерактивная команда без флага `-y`/неинтерактивного режима

Шаг 2. Воспроизвести локально

Самая мощная техника — повторить ровно те же команды у себя. Если в CI стоит npm ci && npm test, выполните их на чистой машине/в контейнере. Большинство багов «работает у меня, падает в CI» — это разница окружений: версия рантайма, отсутствующая зависимость, переменная окружения.

Шаг 3. Включить подробные логи

GitHub умеет писать debug-логи. Включаются они переменными-секретами репозитория:

ACTIONS_STEP_DEBUG = true
ACTIONS_RUNNER_DEBUG = true

После этого перезапустите job (Re-run) — в логах появятся подробности работы экшенов и runner. Это помогает, когда обычный лог немногословен.

Шаг 4. Точечная диагностика командами

Иногда стоит добавить временный диагностический шаг, чтобы увидеть состояние окружения (но без секретов!):

- name: Диагностика
  run: |
    node --version
    pwd
    ls -la
    env | grep -v -i token | sort

Здесь env отфильтрован, чтобы случайно не вывести токены. После починки такой шаг удаляют.

Re-run и кэш

Кнопка Re-run jobs перезапускает прогон — полезно при плавающих (flaky) падениях из-за сети. Если подозреваете протухший кэш, перезапустите без кэша или поменяйте ключ: иногда проблема именно в нём.

Итог

Начинайте с лога упавшего шага — там код и текст ошибки.
Главный приём — воспроизвести команды локально; большинство падений из-за разницы окружений.
Углубляться помогают ACTIONS_STEP_DEBUG и аккуратные диагностические шаги (без вывода секретов).