GitHub Actions: переносна схема CI

1. Ви вивчаєте не GitHub, а межу перевірки

Коли новачки вперше бачать GitHub Actions, часто здається, що весь CI — це дивний YAML із незрозумілими заклинаннями. Відпустіть це. Я показую не таємну мову GitHub, а переносну інженерну схему. GitHub Actions взято тому, що Commerce OS живе в GitHub, — так PR і workflow-файли лежать в одному репозиторії.

Щойно локальний setup і diagnostics із попередньої лекції зібрані у відтворюваний набір артефактів, потрібен механізм, який проганятиме той самий контракт на віддаленому runnerʼі. Спочатку — каркас job (event, runner, permissions, artifacts), а build, smoke і test checks усередині нього — потім.

Головна думка лекції проста: ви вивчаєте не GitHub Actions як бренд, а CI як межу перевірки. Синтаксис у кожного провайдера свій, скелет один: подія запускає job, job отримує обмежені credentials, усередині виконується bounded команда Claude, далі зберігаються логи й artifacts, а потім вирішує людина.

flowchart TD
    A[pull_request або інша CI-подія] --> B[job на runner]
    B --> C[обмежені credentials]
    C --> D[bounded запуск Claude]
    D --> E[логи й artifacts]
    E --> F[перегляд людиною]

Для початківця це особливо корисна перспектива. Тримайте в голові не список ключових слів YAML, а чотири питання: що запускається, з якими правами, що зберігається як evidence, хто читає результат. YAML і версії actionʼів зміняться, поля в іншого провайдера будуть іншими — ці питання залишаться.

У цьому місці корисно одразу подумки розвести CI event і hook event. pull_request — зовнішня подія платформи GitHub, вона жодним чином не пов’язана з hookʼами Claude Code, які ви налаштовували раніше всередині локального workflow. Слово «event» тут оманливе: різні системи, різні рівні автоматизації.

2. Workflow — це файл, а не магія

Найкорисніший спосіб подружитися з GitHub Actions — перестати дивитися на workflow як на магічний об’єкт. Це просто файл у репозиторії: живе в Git, проходить diff review, змінюється маленькими кроками, має бути зрозумілим наступному, хто його відкриє.

Наш перший артефакт зазвичай лежить за шляхом .github/workflows/pr-check.yml. Мінімальний каркас:

# .github/workflows/pr-check.yml
name: PR Check

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest

Тут немає нічого містичного. name — ім’я сценарію в інтерфейсі GitHub. on — коли запускатися (у нас на pull_request у main). jobs — що робити (поки одна job verify на машині ubuntu-latest).

Якщо перекласти основні слова на людську мову, вийде така карта:

workflow

event

job

step

runner

artifact

Дуже важливо зрозуміти ще одну річ: runner — це чиста тимчасова машина. Не ваш ноутбук, не машина тімліда, не «той сервер, де все налаштовано три роки тому». Тому reproducible setup із попередньої лекції тут особливо важливий: проєкт збирається тільки на одному «щасливому» ноутбуці — CI швидко викриє цю романтичну легенду.

І так, маленький жарт із світу YAML: він любить пробіли трохи більше, ніж багато людей люблять понеділки. Табуляція та випадкові відступи — часта причина дуже дурних помилок. Не страшний, просто вимагає акуратності: ліворуч ключ, праворуч значення, вкладеність — пробілами.

3. Збираємо перший PR-check для Commerce OS

Тепер зробимо наш перший справді корисний workflow для Commerce OS. У глибину build і test automation зараз не йдемо — це окрема розмова. Завдання — каркас CI job, який живе в PR, отримує код, перевіряє в чистому середовищі та залишає зрозумілий слід.

Зазвичай такий job починається з checkout, обмеження прав і тайм-ауту:

permissions:
  contents: read
  pull-requests: write   # потрібно лише якщо хочемо писати коментар у PR

timeout-minutes: 15

steps:
  - uses: actions/checkout@v4

Тут одразу кілька важливих рішень. contents: read — принцип мінімальних привілеїв: job лише читає код і запускає перевірки, зайвих прав не давайте. pull-requests: write потрібне не завжди — поки ви зберігаєте звіт як artifact, а не пишете коментар у PR, його можна прибрати. Спершу збирати evidence, публікувати автоматично — потім.

15 — теж не декоративний рядок. Зависла job — runner не повинен молотити без кінця. Особливо з Claude step усередині: мережеві проблеми, дивний prompt, завислий install-step. Тайм-аут робить pipeline передбачуваним.

Далі в job зазвичай ідуть кроки підготовки середовища та запуску базових команд проєкту. Запам’ятайте важливий принцип: CI повторює локальний базовий workflow команди, а не вигадує свої ритуали. Локально одні команди, а в CI інші — отримаєте два паралельні світи: «локально зелено» і «в CI червоно».

Саме тому попередня лекція про reproducible setup була фундаментом, а не вступом для краси. README, package scripts, команди Gradle, compose-конфіги і CI мають дивитися в один бік. Розійдуться — і Claude аналізує не код, а наслідки людської неузгодженості. Зовсім інший жанр.

4. Обмежений запуск Claude всередині job

Тепер переходимо до найцікавішого місця лекції. Тут легко зісковзнути в небезпечну фантазію: «додамо рядок, і CI стане сам розумним інженером». Не стане. Claude у CI — той самий bounded run, що ви бачили раніше, тільки тепер усередині job на віддаленій машині.

Практично нам потрібні дві речі: на runner доступний сам Claude CLI і налаштована автентифікація через secret. Спосіб різний — install-step, готовий image, action-обгортка. Важлива не команда, а факт: без CLI і без автентифікації Claude step не існує.

Щоб bounded run не перетворився на магію, вхід має бути явним: job спочатку готує input artifact — diff або log. Claude у CI не «сам розуміє PR», він аналізує конкретний файл, який поклав поруч попередній step.

Мінімальний приклад кроку:

- name: Підготувати diff як вхідний артефакт
  run: git show --stat --patch --format=medium HEAD > pr.diff

- name: Короткий розбір diff через Claude
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    cat pr.diff | claude -p "Підсумуй зміни та виділи 3 ризики" > pr-review.md

Цей приклад потрібно читати правильно. Спочатку job виділяє diff у файл, потім bounded run перетворює саме цей вхід у звіт. Прапорець і prompt заучувати не треба — точний синтаксис non-interactive режиму та опцій звіряйте через claude --help і документацію тієї версії, що стоїть у вас у CI. Стійка навичка інша: у кроку є явний secret, зрозуміла мета і структурований результат у файлі, а не балаканина в stdout про життя. Із логами так само: замість pr.diff job кладе поруч ci-failure.log.

Дуже корисно зробити ще один інженерний крок і не ховати довгий prompt у YAML. Команда Workflow Kit веде це як окремий артефакт — тримайте текст CI-промпта поруч, файлом під версійним контролем. CI-файл залишається коротким, а промпт під час зміни видно як diff у нормальному markdown-файлі, а не всередині рядка на пів екрана.

Важливе й інше обмеження: Claude step у PR-check за замовчуванням працює лише на читання — аналізує diff, підсумовує, виділяє ризики. Не мрійте в першому ж workflow про pipeline, який сам себе лагодить, править код, пушить коміти й ще перепрошує колег. Це не навчання CI, а запрошення хаосу до репозиторію.

І ще одна тонка, але дуже важлива деталь: у bounded run має бути вузький вхід. Не «прочитай весь репозиторій і подумай про прекрасне», а «проаналізуй поточний diff» або «розбери конкретний лог падіння job». Claude добрий не тоді, коли йому дають увесь світ, а коли дають правильно вирізаний шматок світу.

5. Логи, артефакти та людське рішення

Коли job завершилася, у вас залишається два основні типи evidence. Лог відповідає на «що відбувалося під час виконання», артефакт — на «який файл-результат ми зберегли після».

Записав Claude step звіт у pr-review.md — збережіть його як artifact:

- name: Зберегти звіт як артефакт
  uses: actions/upload-artifact@v4
  with:
    name: pr-review
    path: pr-review.md

Тепер цей файл завантажується з інтерфейсу Actions і спокійно читається — краще, ніж вишукувати фрази в довгому логу між setup-step, checkout-step і службовими повідомленнями runner. Для людини зручніший markdown, для наступного шару автоматизації — просіть у Claude JSON.

Є й ще один психологічно важливий момент. Зелена job і навіть добрий Claude-звіт не дають автоматичного дозволу на merge. CI дає evidence, а не знімає відповідальність з розробника. Зелена галочка підступна: створює відчуття, ніби система вже все вирішила за вас. Насправді вона сказала одне: «Ось результат перевірки. Тепер прочитайте його й ухваліть рішення».

Якщо вам поки страшно давати workflow право писати коментарі в PR — це нормальний страх. Почніть з artifact: спокійніше і для безпеки, і для навчання. Команда звикне до формату звіту і зрозуміє, що хоче бачити від Claude, — тоді обережно рухайтеся до автоматичної публікації підсумку в pull request.

6. Патерн у GitLab, Jenkins, Bitbucket

Хороша новина в тому, що після цієї лекції ви знаєте не лише GitHub Actions, а й майже будь-який інший CI — на рівні інженерної моделі. Синтаксис, звісно, відрізняється. Але сама схема переноситься майже напряму.

on:

job

job

step

runner

runner

runner

Тому якщо завтра ви прийдете в команду, де не GitHub, а GitLab чи Jenkins, вам не доведеться вчитися з нуля. Вам потрібно буде лише перекласти знайомі питання на новий діалект: що тут вважається event, де задаються permissions або secrets, як зберігаються artifacts, де людина потім читає evidence.

Саме це і є durable skill. Не «я пам’ятаю, як виглядав checkout@v4». А «я розумію, як влаштована межа CI: що запускається, з якими правами, що Claude робить усередині job, який результат лишається після виконання і де людина ухвалює рішення». Коли таке розуміння з’являється, GitHub Actions перестає бути набором YAML-файлів і перетворюється на нормальний інженерний інструмент, який можна спокійно переносити з проєкту в проєкт.