GitHub Actions Matrix Strategy: English for CI/CD Pipeline Configuration Discussions (англійською)

Обговорення налаштування GitHub Actions мають дуже специфічний словник. Коли ваша команда обговорює, чи слід використовувати матрицю або потоки роботи з повторним використанням, чи слід встановити fail-fast: false або зберегти типові значення, або як зв’ язати завдання з вивантаженнями артефактів, вам слід стежити за цими розмовами і брати участь у них англійською мовою. У цьому повідомленні описано терміни, які найчастіше зустрічаються у переглядах коду конвеєра CI/ CD і обговореннях архітектури.

Терміни стратегії матриці

** Матрична стратегія ** — функція GitHub Actions, яка автоматично створює декілька запусків завдань з набору змінних комбінацій, що дозволяє вам тестувати різні операційні системи, версії мов або налаштування з одним визначенням завдання.

«Ми використовуємо матричну стратегію для запуску нашого тестового набору проти вузлів 18, 20 і 22 одночасно — це скорочує наш час зворотнього зв’язку на дві третини порівняно з їх послідовним запуском»

** Розмір матриці ** — одна змінна, визначена в матриці, наприклад os, node-version, або environment. Кілька вимірів об’ єднуються для створення всіх можливих пермутацій завдання.

«Ми маємо два матричні виміри: операційна система (ubuntu, windows, macos) і версія Python (3.10, 3.11, 3.12) — це дає нам дев’ять паралельних робіт»

** Включити/ виключити комбінації ** — спеціальні ключі матриці, які надають вам змогу додати певні комбінації, які зазвичай не існують у перехресному добутку ( include ) або вилучити певні комбінації, які ви бажаєте пропустити ( exclude ).

«Ми використовуємо включення, щоб додати спеціальне завдання, яке працює тільки на Ubuntu з Python 3.12 і додатковим набором змінних середовища — інші комбінації не потребують цієї конфігурації»

** fail- fast ** — параметр налаштування матриці (типове значення: true ), який скасує всі завдання, що виконуються, якщо якесь з завдань матриці зазнає невдачі. Встановлення цього параметра на false дозволяє завершити всі завдання незалежно від помилок у побратимських завданнях.

«Ми встановили fail-fast: false в матриці, тому що ми хочемо побачити всі неефективні комбінації ОС одночасно, а не тільки першу, яка зламалася»

** max- parallel ** — параметр налаштування матриці, який обмежує кількість завдань, які можна виконувати одночасно. Корисно для уникнення обмежень швидкості на зовнішніх службах або для керування використанням ресурсів.

«Сторонній API, який ми тестуємо, має обмеження швидкості, тому ми встановили max-parallel: 3, щоб запобігти матриці від удару 12 одночасними запитами»

Повторно використовуваний робочий процес і складні терміни дій

** Повторно використовуваний робочий процес ** — файл потоку дій GitHub, який можна викликати іншими потоками за допомогою тригера workflow_call. Це основний спосіб спільного використання логіки CI/CD у багатьох сховищах.

«Ми витягли наші спільні кроки build-and-push в багаторазовий робочий процес в репо платформи — тепер всі 15 сервісних репо викликають його замість дублювання 80 рядків YAML»

** workflow_ call trigger ** — подія, яка робить поток робіт доступним для повторного використання. Робочий потік повинен оголосити on: workflow_call, щоб його можна було викликати з іншого робочого потоку.

Не забувайте додавати тригер workflow_call до спільного потоку роботи — без нього інші репозитории можуть посилатися на нього, але він не буде виконуватися, як очікувалося

Складена дія — дія GitHub Actions (визначена в action.yml ), яка об’єднує декілька кроків в один повторюваний блок. На відміну від потоків робіт з повторним використанням, складні дії виконуються у контексті виклику завдання.

«Ми зробили кроки входу в Docker і мітки зображень в складну дію — вона називається так само, як і будь-яка інша дія uses:, яку команда вважає чистішою, ніж багаторазовий робочий процес для цього випадку використання»

** Завдання залежить від (потребує:) ** — ключове слово, яке вказує, які завдання слід успішно виконати перед початком поточного завдання. Крім того, програма керує порядком виконання завдань і надає змогу передавати виводи між завданнями.

«Задача розгортання має needs: [build, test] — вона починається тільки після того, як обидві завдання збирання і тестування пройшли успішно»

** Вивантаження/ звантаження артефактів ** — механізм передачі файлів між завданнями у одному і тому ж потоці роботи. actions/upload-artifact зберігає файли наприкінці одного завдання; actions/download-artifact отримує їх у наступному завданні.

«Ми завантажуємо скомпільований бінарний файл як артефакт в завдання збирання і завантажуємо його в завдання розгортання — це уникає перебудови і забезпечує, що розгорнутий бінарний файл є саме тим, який пройшов тести»

Контекстно-орієнтовані мови

Ці фрази з’ являються у переглядах запитів на завантаження GitHub Actions і обговореннях проектування CI/ CD:

• “Матриця генерує 24 завдання, але нам цікаві лише 6 — використаємо виключення, щоб обрізати їх.” — коментар перегляду коду, що зменшує непотрібні витрати CI
• ** “Цей поток роботи дублюється у трьох сховищах. Чи можемо ми витягнути його в багаторазовий робочий процес в платформі репо?” ** - рекомендаційна пропозиція в обговоренні команди
• ** « Артефакт з завдання збирання не збирається — перевірте, чи точно збігаються назви артефактів у вивантаженнях і звантаженнях. » ** — коментар зневадження під час дослідження помилки конвеєра
• ** « Ми повинні прикріпити цю дію до SHA замість мітки для безпеки — v3 може бути пересунуто супроводжувачем ». ** — коментар перегляду, орієнтований на безпеку
• ** “Потрібності: ланцюг тут занадто довгий. Завдання C і D можуть працювати паралельно, якщо ми перебудуємо залежності.”** — пропозиція оптимізації в огляді архітектури CI

Ключові слова

Collocation	Example
run a matrix job	”Each matrix job runs in a fresh VM — shared state between them is not possible.”
trigger a workflow	”The workflow is triggered on push to main and on pull_request events.”
pass outputs between jobs	”Use job outputs and needs.job-name.outputs.key to pass values between jobs.”
upload an artifact	”Upload the test report as an artifact so it’s available after the job completes.”
call a reusable workflow	”All service repos call the reusable workflow from the platform repository.”
cancel remaining jobs	”With fail-fast enabled, a single failure will cancel all remaining matrix jobs.”
pin an action	”Pin all third-party actions to a full commit SHA in security-sensitive workflows.”

Запис у реєстрі

GitHub Дії Обговорення YAML відбуваються у двох реєстрах. У коментарях запитів на витягування мова часто коротка: « pin this », « add needs: », « extract to composite ». У документах проектування і командних вікі, очікується повне речення: « Ця задача залежить від успішного завершення етапу збирання ». Використовуйте обидва варіанти — вам потрібен формальний реєстр для документації і неформальний реєстр для щоденних коментарів щодо перегляду.

Practice

Відкрийте будь- який файл потоку дій GitHub у сховищі вашої команди, який використовує більше трьох завдань. Накреслити графік залежностей на папері (від яких завдань залежать інші). Потім напишіть опис потоку роботи простою англійською мовою — без YAML, лише речення — який новий член команди зможе прочитати, щоб зрозуміти всю структуру конвеєра. Уключіть: що запускає поток робіт, що виконує кожне завдання, які залежності існують між завданнями, і чи використовується матрична стратегія. Намагайтеся написати 10-12 речень. Ця навички безпосередньо відображається на написання документації CI/CD і керівництва по впровадженню.

Не слід плутати з ненаціональними мовами

Будьмо чесними – термінологія навколо CI/CD конвеєрів, особливо в контексті GitHub Actions і матричних стратегій, може здатися неймовірно щільною. Це не просто про те, щоб знати * що * крок робить; це про розуміння * як * ефективно спілкуватися з вашою командою. Для розробників, чия перша мова не є англійською, ця складність посилюється незнайомою фразою, тонкими відмінностями в значенні і часто безособовим тоном технічної документації.

Однією з поширених перешкод є часте використання імперативних дієслів – «запустити», «розгорнути», «запустити» – які можуть здатися вкрай вимогливими і, можливо, залякуючими. Хоча це цілком прийнятно, корисно зрозуміти чому їх використовують. Вони представляють інструкції, завдання і очікування в рамках робочого потоку. Крім того, такі поняття, як «композиційні дії» або «повторно використовувані потоки робіт» часто вимагають ретельного пояснення. Просто перекладаючи буквальний термін не передається користь - що ви будуєте модульні компоненти для більшої ефективності і підтримки. Важливо будувати впевненість у чіткому вираженні цих ідей, зосереджуючись на тому, що дія досягає, а не тільки на тому, як вона виконується. Розглянемо сценарій: отримання коментаря перегляду коду на зразок: « Цей крок потребує більше контексту — чого ми намагаємося досягти тут? » Прямий переклад може призвести до плутанини. Замість цього, продумана відповідь буде: “Я додав коментар, пояснюючи, що цей крок призначений для перевірки схеми бази даних перед розгортанням, забезпечуючи цілісність даних”

Іншою областю, яка вимагає ретельної уваги, є точність при описі невдач і помилок. Фрази на зразок « роботу потоку було перервано » технічно правильними, але не містять інформації, яка могла б бути використана. Кращий підхід полягає в тому, щоб описати * чому * він зазнав невдачі: “Крок npm install зазнав невдачі через конфлікт залежностей - версія пакунка, вказана в package.json не відповідає тому, що доступно на npm.” Цей рівень деталізації дозволяє іншим швидко діагностувати і вирішити проблему, зменшуючи витрачений час і розчарування. Аналогічно, при написанні описів PR, фокусування на * результаті *, який ви доставляєте, є ключовим: «Цей запит на потягування вводить нову матричну стратегію, яка автоматично тестує програму проти трьох різних версій Node.js, покращуючи нашу впевненість у розгортанні»

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

# Example YAML file representing a GitHub Actions matrix strategy
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16.x'
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test