Автоматизация в GitHub

Monitoring и troubleshooting

Monitoring и troubleshooting в GitHub Actions — это не отдельная «панель с ошибками», а набор практик вокруг run history, visualization graph, logs, rerun, API и метрик. В production CI/CD важно не просто увидеть красный крестик, а быстро ответить на пять вопросов: какой workflow запустился, какой job сломался, что было в окружении runner, это единичный сбой или flaky-паттерн, и можно ли безопасно перезапустить только нужную часть.

Эта тема связывает эксплуатацию с CI pipeline, Matrix strategy, GitHub-hosted runners, Self-hosted runners, Runner governance, Artifacts и reports и Workflow commands и summaries.

Run history: журнал фактов, а не просто список запусков

Run history показывает workflow runs: событие, branch или tag, commit, actor, статус, длительность, попытки rerun и ссылку на конкретный run. Это первая точка входа при расследовании. Если workflow не запустился, проверяют Events и filters: branches, paths, types, workflow_dispatch, schedule, pull_request и skip-команды в commit message. Если workflow запустился, но job пропущен, расследование переходит к Jobs, dependencies и conditions и condition logs.

Для CLI-базового triage удобно начинать так:

gh run list --workflow ci.yml --limit 10
gh run view RUN_ID --verbose
gh run view RUN_ID --log-failed

gh run view --exit-status полезен в скриптах: команда возвращает non-zero exit code, если run failed. Это простой способ встроить проверку GitHub Actions в внешний мониторинг или release-script.

Visualization graph: карта зависимостей jobs

Visualization graph показывает jobs, их статусы и линии зависимостей needs. Это особенно полезно в workflows, где build, tests, package и deploy разбиты на несколько jobs. Если упал ранний job, downstream jobs могут быть skipped не потому, что их собственный код сломан, а потому что цепочка needs остановилась.

Типичный пример:

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v6
      - run: npm ci
      - run: npm run build

  test:
    needs: build
    runs-on: ubuntu-24.04
    steps:
      - run: npm test

  deploy:
    needs: [build, test]
    if: github.ref == 'refs/heads/main'
    environment: production
    runs-on: ubuntu-24.04
    steps:
      - run: ./scripts/deploy.sh

Если build failed, test и deploy могут не дать самостоятельных логов ошибки. Graph быстро показывает корень: первым красным узлом был build. Это важнее, чем читать все skipped jobs подряд.

Logs: читать снизу вверх, но начинать с failed step

Logs в GitHub Actions устроены по иерархии: workflow run → job → step. GitHub добавляет служебные steps вроде Set up job и Complete job; для GitHub-hosted runners в Set up job видны детали runner image и ссылка на список preinstalled tools. Это полезно при drift-проблемах: вчера ubuntu-latest проходил, сегодня сломался из-за версии системного пакета или toolchain.

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

1. открыть failed job из graph или списка jobs;

2. перейти к первому failed step, не к последней красной строке всего лога;

3. проверить команду, exit code, рабочую директорию и environment;

4. посмотреть Set up job, если подозрение на runner image, shell, OS или architecture;

5. искать по логу только в expanded steps — GitHub ищет не по всем свернутым блокам сразу.

Для больших логов используйте группировку:

echo "::group::Install dependencies"
npm ci
echo "::endgroup::"

echo "::group::Test environment"
node --version
npm --version
pwd
ls -la
echo "::endgroup::"

Но не превращайте CI в дамп всего окружения. В разделе Secure use и threat model уже есть причина: logs могут случайно раскрыть пути, internal URLs, package names или преобразованные secrets, которые masking не поймает.

Debug logging: включать точечно

GitHub поддерживает два специальных флага для verbose-логов: ACTIONS_STEP_DEBUG=true и ACTIONS_RUNNER_DEBUG=true. Их задают как secret или variable в repository; если заданы оба варианта, secret имеет приоритет. Step debug добавляет подробности в step logs, runner debug добавляет diagnostic logs, которые попадают в log archive в папку runner-diagnostic-logs.

Самый безопасный паттерн — не держать debug включённым постоянно, а делать rerun с debug logging для конкретного failed run:

gh run rerun RUN_ID --failed --debug

Или для конкретного job:

gh run rerun --job JOB_ID --debug

Это снижает шум, не размазывает чувствительную информацию по многим logs и экономит время на workflows с большой Matrix strategy.

Job condition logs: когда job skipped «без причины»

Job-level if часто ломается не синтаксически, а логически: не тот event payload, другой branch ref, skipped dependency, needs.*.result, default success() или неверная строка в Contexts и expressions. GitHub пишет expression evaluation logs для job-level conditions. Их можно скачать из log archive и открыть файл вида JOB-NAME/system.txt.

Минимальный пример проблемного условия:

jobs:
  deploy:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-24.04
    steps:
      - run: ./scripts/deploy.sh

Если этот job skipped на workflow_dispatch, это корректное поведение, а не сбой. Condition logs помогают увидеть, какая часть выражения дала false. Для production deploy это особенно важно: skipped deploy может быть нормальной защитой, а может быть ошибкой в branch/tag policy из Deployment workflows или Environments и protection rules.

Rerun: лечит flaky, но не исправляет workflow

Rerun бывает трёх типов: весь workflow, только failed jobs или конкретный job. Partial rerun экономит минуты и обычно не перезапускает весь workflow, но rerun failed jobs может также перезапускать dependent jobs. Но rerun запускает тот же workflow definition и тот же ref, а не «новую исправленную версию YAML из будущего commit». Если ошибка в workflow-файле уже исправлена новым commit, старый run от этого не станет другим.

Для flaky failures полезно различать три класса:

Infrastructure flaky:
  network timeout, package registry 5xx, runner capacity, Docker pull timeout

Test flaky:
  race condition, order dependence, clock/timezone, shared state, random seed

Workflow flaky:
  cache key collision, missing needs, non-pinned tool version, brittle path filter

Если rerun стабильно чинит проблему, это не повод игнорировать её. Это сигнал завести метрику: failure rate по workflow/job, retry rate, среднее время до зелёного run, top failing steps. Для matrix jobs отдельно смотрят axis: например, failures только на windows-latest или только на Node 22 обычно указывают на совместимость, а не на случайность.

Artifacts, reports и API

Logs отвечают на вопрос «что произошло во время job». Artifacts и reports отвечают: «что job произвёл». Для troubleshooting тестов сохраняйте JUnit/XML, coverage, screenshots e2e-тестов, trace-файлы Playwright, bundle analysis и deployment manifests через Artifacts и reports. Это лучше, чем печатать всё в stdout.

Для автоматизации GitHub REST API даёт endpoints для workflow runs, jobs, logs и artifacts. Типичные операции: list workflow runs, get run, list jobs for run, download job logs, rerun job, list workflow run artifacts, download artifact. Это основа для собственного dashboard, incident bot или nightly отчёта по нестабильным jobs.

Пример ручного API-запроса:

gh api repos/OWNER/REPO/actions/runs/RUN_ID/jobs \
  --jq '.jobs[] | {name, conclusion, started_at, completed_at}'

А для логов чаще хватает CLI:

gh run view RUN_ID --log-failed > failed.log

Metrics: смотреть на тренды, а не на один красный run

Для GitHub Enterprise Cloud доступны Actions metrics на уровне organization и repository: usage metrics помогают понять расход минут, performance metrics — run time, queue time и failure rate. Даже без enterprise-панели можно строить минимальные operational metrics через REST API и gh: длительность jobs, количество failures, частота rerun, самые долгие matrix axes, очередь на self-hosted runner groups.

Хороший production-индикатор — не «все runs зелёные сегодня», а «p95 CI duration не растёт, failure rate низкий, flaky jobs известны, deploy jobs имеют понятный audit trail». Здесь monitoring напрямую связан с Оптимизация времени CI, Runner governance и Enterprise policies и migration.

See also

• Workflow: файл, запуск, jobs и steps — базовая структура run, job и step.
• Jobs, dependencies и conditions — needs, skipped jobs и condition logic.
• Contexts и expressions — данные, из которых вычисляются if и debug conditions.
• Artifacts и reports — как сохранять test reports, traces и build outputs.
• Workflow commands и summaries — группировка logs, annotations и job summaries.
• Matrix strategy — диагностика failures по axes и partial rerun.
• Runner governance — runner pools, queue, isolation и self-hosted diagnostics.
• Secure use и threat model — почему debug logs и artifacts нужно рассматривать как чувствительные данные.
• Enterprise policies и migration — org-level метрики, audit и стандартизация workflows.

Внешние справки: GitHub Docs по visualization graph, workflow run logs, rerun workflows/jobs, debug logging, job condition expression logs, REST API для workflow runs/jobs/artifacts, Actions metrics и troubleshooting self-hosted runners.