Керування робочими циклами та налагодження в діях GitHub

10 хв.

Нагадаємо, що ваша мета – автоматизувати процес побудови та публікації коду, щоб функції оновлюються щоразу, коли розробник додає зміни до бази коду.

Щоб реалізувати цей процес, ви дізнаєтеся, як це зробити:

Визначте подію, яка викликала робочий цикл.
Використовуйте журнали робочих циклів Дій GitHub.
Зберігайте артефакти збірки та отримуйте доступ до нього.
Автоматизуйте додавання підпису до запиту на витягування після перевірки.

Визначення події, яка ініціює робочий цикл

Розуміння того, що викликало робочий цикл GitHub Actions, має вирішальне значення для налагодження, аудиту та вдосконалення трубопроводів CI/CD. Тип тригерів включає натискання на гілку, створений або оновлений запит, заплановане завдання або ручне відправлення. Ви можете визначити подію, що запускається, вивчивши запуск робочого циклу, зміни сховища та пов'язану проблему GitHub або запит на витягнення.

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

Що таке тригер робочого циклу?

Тригер робочого циклу – це подія, через яку запускається робочий цикл. GitHub підтримує різні типи тригерів, зокрема:

push або pull_request (на основі змін коду)
workflow_dispatch (тригер вручну)
schedule (завдання cron)
repository_dispatch (зовнішні системи)
Події запитів на питання, обговорення та витягування (наприклад, issues.opened, pull_request.closed)

Визначення події тригера

Подію тригера робочого циклу можна визначити кількома способами:

Скористайтеся інтерфейсом користувача дій GitHub:
1. У вашому репозиторії виберіть вкладку Дії .
2. Виберіть робочий цикл.
У верхній частині зведення робочого циклу відображається тип події, наприклад push, pull_requestабо workflow_dispatch, .
Використовується github.event_name в журналах або в робочому циклі.
- GitHub надає контекстні дані під час запуску робочого циклу. Змінна github.event_name повідомляє, яка подія ініціює робочий цикл.
- Відомості можна надрукувати на кроці для налагодження:
```
-name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"
```
Використання відомостей про запуск робочого циклу:
- Якщо ви перевіряєте робочий цикл запускається програмно, наприклад за допомогою API, об'єкт виконання включає event властивість, яка визначає тригер.
- Ви можете знайти алгоритм безпечного гешування (SHA), актора та позначку часу, щоб відстежити причину тригера.

Вивести тригер із ефектів сховища

Можливо, у вас немає прямого доступу до робочого циклу, але все одно потрібно визначити, що ініціює запуск робочого циклу на основі дій сховища:

Спостережувана поведінка	Активувати подію
Було наштовхнуто нове комітування та запущено `main` робочий цикл.	`push` подія
Запит на витяг було відкрито або оновлено.	`pull_request` подія
Співавтор вручну запустив робочий цикл.	`workflow_dispatch`
Робочий цикл запускається щодня в певний час.	`schedule` (крон)
Робочий цикл запущено після виклику зовнішньої служби.	`repository_dispatch`
Робочий цикл запущено, коли до проблеми додано підпис або примітку.	`issues.*` подія

Переглядаючи позначки часу, виводячи запити на дії та здійснюючи журнал, ви часто можете визначити дію, яка спричинила запуск робочого циклу.

Щоб підсумувати, як визначити, що ініціює робочий цикл:

Перевірте підсумок виконання робочого процесу на вкладці Дії .
Друк або вхід github.event_name у робочий цикл для видимості.
Порівняйте позначки часу та дії сховища (коміти, запити на витягування, проблеми), щоб вивести тригер.
Використовуйте повний event контекст для глибшого дослідження.

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

Розуміння ефекту робочого циклу за допомогою читання файлу конфігурації

Щоб зрозуміти наслідки робочого циклу від читання файлу конфігурації, проаналізуйте структуру та вміст .yml файлу, який зберігається в .github/workflows/.

Файл конфігурації робочого циклу визначає такі відомості про робочий цикл:

Коли він запускається (у on розділі).
Що він робить (в jobs і steps).
Де він працює ( runs-on розділ).
Чому вона запускається (її призначення, наприклад тестування, розгортання або зв'язування).
Як вона працює в певних умовах (середовище, фільтри, логіка).

Тлумачення ефекту робочого циклу

Визначте тригер.

Щоб визначити дію, яка ініціювала робочий цикл, див on . розділ робочого циклу.

Приклад.
```
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:
```
У цьому прикладі робочий цикл:
- Запускається автоматично, коли код передається до головної гілки (push).
- Запускається, коли створюється або оновлюється запит на витягування (pull_request).
- Користувач може ініціювати їх вручну (workflow_dispatch).
Визначте завдання та кроки робочого циклу.

Щоб визначити, що робить робочий цикл, дивjobs. розділи робочого циклу.steps

Приклад.
```
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test
```
У цьому прикладі робочий цикл:
- Використовує віртуальне середовище Linux (runs-on).
- Перевіряє код сховища (steps>name).
- Інсталює залежності проекту (steps>name).
- Виконує автоматизовані тести (steps>name).
Оцініть призначення та результат робочого циклу.

Читаючи файл конфігурації, можна описати потрібний результат робочого циклу:

"Цей робочий цикл – це безперервна інтеграція (CI). Це гарантує, що будь-який новий код, який надсилається до сховища або надсилається через запит на витягнення, перевіряється автоматично. Якщо тести завершаться помилкою, інтерфейс користувача робочого циклу GitHub відображає цей результат, щоб допомогти вам зберегти якість коду"."
Визначте або встановіть необов'язкові функції, які впливають на запуск робочого циклу:
- env установлює змінні середовища.
- if додає умовну логіку, щоб виконувати певні кроки, лише коли виконуються умови.
- timeout-minutes або continue-on-error встановіть виконання робочого циклу та обробку помилок.

Діагностика невдалого запуску робочого циклу

У вашому репозиторії перейдіть на вкладку Дії .
Знайдіть невдалий запуск (зазвичай позначається червоним хрестиком).
Виберіть невдалий робочий цикл, щоб відкрити зведення запуску.
У журналах робочих циклів перевірте помилку.
1. У зведенні про запуск розгорніть кожне завдання та крок, доки не знайдете завдання, яке вказує на помилку.
2. Виберіть завдання або крок, щоб переглянути його журнали.
3. Шукати:
  - Повідомлення про помилки
  - Трасування стека
  - Коди виходу
Наприклад, може відобразитися npm ERR! Test failed невдала перевірка або exit code 1.
Перевірте файл конфігурації робочого циклу.

Скористайтеся файлом .yml , щоб визначити:
- Що намагався зробити кожен крок?
- Якщо існують змінні середовища (env) або умовні (if), які впливають на виконання.
- Якщо помилка виникає через відсутність залежності, синтаксична помилка або неправильний крок.
Якщо не вдається виконати крок, перевірте, чи є такі причини:
- Чи успішно інстальовано залежності на попередньому кроці?
- Чи існують тестові файли та проходять локально?

Типові сценарії помилок

У таблиці нижче описано типові сценарії помилок робочого циклу:

Symptom	Ймовірна причина
Не вдається виконати крок і повертає `command not found`l	Відсутня залежність або неправильне настроювання
`npm install` Не вдається.	Пошкоджений `package-lock.json` файл або неполадка мережі
Помилка тестового кроку	Проблеми з перевіркою одиниці, відсутній файл конфігурації або неприпустимий тестовий синтаксис
`Permission denied` З'являється.	Неправильні дозволи на доступ до файлів або відсутні секрети

Визначення способу доступу до журналів робочих циклів у GitHub

У вашому репозиторії перейдіть на вкладку Дії .
У списку робочих циклів виберіть відповідний робочий цикл.

Наприклад, якщо файл .yml має такий код, у списку з'явиться посилання під назвою «Робочий процес CI» :
```
name: CI Workflow
```
Виберіть певний запуск.

У списку запусків, які відображають стан, виберіть позначку часу або повідомлення про виконання певного запуску, який потрібно перевірити.
Розгорніть кожне завдання та крок.

На сторінці зведення виконання відображаються завдання, визначені у файлі робочого циклу, наприклад збірка або перевірка:
1. Виберіть завдання, щоб розгорнути його.
2. У межах завдання розгорніть окремі кроки, наприклад "Інсталювати залежності" або "Запустити тести".
Перегляд результатів журналу.

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

У наведеній нижче таблиці підсумовано дії, які потрібно виконати для доступу до журналів робочих циклів:

Action	Purpose
Вкладка «Дії»	Переглянути всі запущені робочі цикли.
Виберіть ім'я робочого циклу	Фільтр виконується за робочим циклом.
Виберіть запуск	Перегляньте конкретні результати завдань і кроків.
Розгорнути кроки	Перегляд докладних журналів.
Завантаження журналів	Завантаження журналів для виправлення неполадок в автономному режимі або групі.

Журнали дій для збірки

Коли робочий цикл запускається, створюється журнал, який містить відомості про те, що сталося, і будь-які помилки або помилки перевірки.

Якщо сталася помилка або не вдалося виконати перевірку, у журналах з'явиться червоний хрестик X замість зеленої позначки. Ви можете перевірити відомості про помилку або не в змозі дослідити, що сталося.

Знімок екрана: журнал дій GitHub із відомостями про невдалу перевірку.

Робота з артефактами

Коли робочий процес виробляє щось, крім запису в журналі, продукт називається артефактом. Наприклад, збірка Node.js створює контейнер Docker, який можна розгорнути. Контейнер — це артефакт, який ви можете завантажити до сховища за допомогою дії action/upload-artifact . Пізніше ви можете завантажити артефакт зі сховища за допомогою action/download-artifact.

Збереження артефакту зберігає його між завданнями. Кожне завдання використовує новий екземпляр віртуальної машини, тому ви не можете повторно використати артефакт, зберігши його на віртуальній машині. Якщо вам потрібен артефакт в іншому робочому місці, ви можете передати артефакт до сховища в одному робочому місці та завантажити його для іншого завдання.

Зберігання артефактів

Артефакти зберігаються в сховищі на GitHub. Простір вільний для загальнодоступних сховищ, а деяке сховище безкоштовне для приватних сховищ залежно від облікового запису. GitHub зберігає артефакти протягом 90 днів.

У наведеному нижче фрагменті робочого циклу зверніть увагу, що в дії actions/upload-artifact@main є атрибут path. Значення цього атрибута – шлях до збереження артефакту. У цьому прикладі ви вказуєте public/ , щоб завантажити все в каталог. Якщо ви хочете завантажити лише один файл, використовуйте щось на кшталт public/mytext.txt.

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

Щоб завантажити артефакт для тестування, збірка має завершитися успішно та передати артефакт. У наведеному нижче коді вказано, що завдання перевірки залежить від завдання збірки.

test:
    needs: build
    runs-on: ubuntu-latest

У наведеному нижче фрагменті робочого циклу ви завантажуєте артефакт. Тепер тестове завдання може використовувати артефакт для тестування.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

Докладні відомості про використання артефактів у робочих циклах див. в статті Зберігання даних робочого циклу як артефактів.

Автоматизація відгуків у GitHub за допомогою робочих циклів

На додачу до запуску робочого циклу за допомогою таких подій GitHub, як push і pull-request, ви можете запускати робочий цикл за розкладом або після певної події за межами GitHub.

Робочий цикл може виконуватися лише після того, як користувач виконає певну дію, наприклад після того, як рецензент затвердить запит на витяг. Для цього сценарію ви можете активувати .pull-request-review

Ще одна дія, яка можна виконати, – додати етикетку до запиту на витяг. У цьому випадку використовуйте дію pullreminders/label-коли-схвалено-дію.

Приклад.

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

У блоці env ви встановлюєте змінні середовища для дії. Наприклад, можна встановити кількість затверджувачів, потрібних для запуску робочого циклу. У цьому прикладі це один. Змінна автентифікації secrets.GITHUB_TOKEN необхідна, оскільки дія має вносити зміни до сховища, додавши підпис. Нарешті, ви введете ім'я підпису, який потрібно додати.

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

Зворотний зв’язок

Чи була ця сторінка корисна?