Konfigurowanie przepływu pracy funkcji GitHub Actions

W tym miejscu poznasz niektóre typowe konfiguracje w pliku przepływu pracy. Zapoznasz się również z kategoriami typów zdarzeń, wyłączaniem i usuwaniem przepływów pracy oraz używaniem określonych wersji akcji w celu uzyskania najlepszych rozwiązań w zakresie zabezpieczeń.

Konfigurowanie przepływów pracy do uruchamiania dla zaplanowanych zdarzeń

Jak wspomniano wcześniej, możesz skonfigurować przepływy pracy tak, aby były uruchamiane po wystąpieniu określonego działania w usłudze GitHub, gdy wystąpi zdarzenie poza usługą GitHub lub w zaplanowanym czasie. Zdarzenie schedule umożliwia wyzwolenie przepływu pracy w celu uruchomienia o określonych godzinach UTC przy użyciu składni cron POSIX. Ta składnia cron ma pięć * pól, a każde pole reprezentuje jednostkę czasu.

Jeśli na przykład chcesz uruchomić przepływ pracy co 15 minut, schedule zdarzenie będzie wyglądać podobnie do następującego przykładu:

on:
  schedule:
    - cron:  '*/15 * * * *'

A jeśli chcesz uruchomić przepływ pracy w każdą niedzielę o godzinie 3:00, schedule wydarzenie będzie wyglądać następująco:

on:
  schedule:
    - cron:  '0 3 * * SUN'

Możesz również użyć operatorów, aby określić zakres wartości lub wybrać numer w zaplanowanym przepływie pracy. Najkrótszy interwał, który można uruchamiać zaplanowane przepływy pracy, wynosi co pięć minut i jest uruchamiany w najnowszym zatwierdzeniu w gałęzi domyślnej lub podstawowej.

Konfigurowanie przepływów pracy do uruchamiania dla zdarzeń ręcznych

Oprócz zaplanowanych zdarzeń można ręcznie wyzwolić przepływ pracy przy użyciu workflow_dispatch zdarzenia. To zdarzenie umożliwia uruchomienie przepływu pracy przy użyciu interfejsu API REST usługi GitHub lub wybranie przycisku Uruchom przepływ pracy na karcie Akcje w repozytorium w usłudze GitHub. Korzystając z workflow_dispatch, możesz wybrać gałąź, w której chcesz uruchomić przepływ pracy, i ustawić opcjonalne inputs prezentowane przez GitHub jako elementy formularza w interfejsie użytkownika.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'  

Oprócz workflow_dispatchprogramu można użyć interfejsu API usługi GitHub do wyzwolenia zdarzenia elementu webhook o nazwie repository_dispatch. To zdarzenie umożliwia wyzwolenie przepływu pracy dla działania wykonywanego poza usługą GitHub. Zasadniczo działa jako żądanie HTTP do repozytorium, po prośbie do usługi GitHub o wyzwolenie przepływu pracy z akcji lub webhooka. To zdarzenie ręczne wymaga wykonania dwóch czynności: wysłania POST żądania do punktu końcowego /repos/{owner}/{repo}/dispatches usługi GitHub z nazwami zdarzeń elementu webhook w treści żądania i skonfigurowania przepływu pracy do korzystania ze repository_dispatch zdarzenia.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Konfigurowanie przepływów pracy do uruchamiania dla zdarzeń elementu webhook

Na koniec można skonfigurować przepływ pracy do uruchamiania w przypadku wystąpienia określonych zdarzeń elementu webhook w usłudze GitHub. Większość zdarzeń webhook można wyzwalać z więcej niż jednej aktywności. Jeśli dla webhooku istnieje wiele aktywności, możesz określić typ aktywności, aby wyzwolić przepływ pracy. Na przykład można uruchomić przepływ pracy dla zdarzenia check_run, ale tylko dla typu aktywności rerequested lub requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

Wywołanie repozytorium

repository_dispatch to niestandardowe zdarzenie w funkcji GitHub Actions, które umożliwia zewnętrznym systemom (a nawet innym przepływom pracy usługi GitHub) ręczne wyzwalanie przepływów pracy przez wysłanie żądania POST do interfejsu API usługi GitHub. Umożliwia ona elastyczną automatyzację i integrację z zewnętrznymi narzędziami, skryptami lub systemami, które muszą uruchamiać przepływy pracy w repozytorium.

Przypadki użycia

• Rozpocznij przepływy pracy za pomocą zewnętrznych narzędzi CI/CD.

• Koordynuj wdrożenia wielu repozytoriów (na przykład repozytorium A kończy kompilację → wyzwala repozytorium B).

• Uruchom automatyzację na podstawie zdarzeń zewnętrznych (webhooków, alertów monitorujących, operacji CRON poza środowiskiem GitHub).

• Łączenie wykonywania procesów roboczych między repozytoriami lub w monorepozytoriach.

Przykładowy przepływ pracy, który nasłuchuje repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Kluczowe elementy:

• typy: opcjonalne. Definiuje niestandardowe typy zdarzeń, takie jak run-tests, deploy-to-proditp.

• github.event.client_payload: dostęp do innych danych niestandardowych przekazanych w zdarzeniu wysyłania.

• github.event.action: nazwa rodzaju zdarzenia wysłanego.

Wyzwalanie zdarzenia za pośrednictwem interfejsu API

Żądanie POST należy wysłać do punktu końcowego interfejsu API REST usługi GitHub w wersji 3:

POST https://api.github.com/repos/OWNER/REPO/dispatches

Autoryzacja

• Wymagany jest osobisty token dostępu (PAT) z uprawnieniami do repozytorium.
• W przypadku organizacji upewnij się, że odpowiednie ustawienia dostępu dla tokenu.

Przykładowa struktura poleceń

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Struktura ładunku

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Parametry

(No changes needed)	Typ	Opis	Wymagane
event_type	ciąg	Nazwa niestandardowa zdarzenia. Nazwa ta odnosi się do wartości typów w wyzwalaczu przepływu pracy.	Tak
client_payload	obiekt	Dowolny JSON-owy ładunek do wysyłania niestandardowych danych do przepływu pracy (github.event.client_payload)	Nie.

Podział parametrów repository_dispatch

Podczas wykonywania żądania POST do punktu końcowego interfejsu API usługi GitHub należy przekazać treść JSON z dwoma głównymi parametrami:

• typ_zdarzenia
• client_payload

typ_zdarzenia

Wymagany ciąg niestandardowy, który definiujesz. Usługa GitHub traktuje tę wartość jako "akcję" lub "typ" wysyłki. Służy do identyfikacji, co wyzwoliło przepływ pracy, i filtrowania przepływów pracy, które nasłuchują określonych typów.

• Układ

  • Typ: ciąg
  • Przykład: "deploy", "run-tests", "sync-db", "build-docker"

• Użyj w przepływie pracy: służy do nasłuchiwania określonych typów zdarzeń i uzyskiwania dostępu do wartości wewnątrz przepływu pracy. Ułatwia to ponowne użycie jednego przepływu pracy w wielu celach i sprawia, że automatyzacja jest bardziej zorganizowana i sterowana zdarzeniami.

• Przykład:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

Dowolny obiekt JSON, który umożliwia wysyłanie niestandardowych danych wraz z wysyłką. Zdefiniujesz strukturę i będzie ona dostępna w przepływie pracy.

• Układ

  • Typ: obiekt
  • Klucze niestandardowe i wartości

• Użycie w przepływie pracy: ten obiekt jest wykorzystywany do wdrożeń w wielu środowiskach, wersjonowanych wydań lub przekazywania kontekstu z innego systemu czy potoku. Umożliwia sparametryzowane przepływy pracy, podobnie jak argumenty wejściowe.

• Przykład:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

Przykładowy podział ładunku

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

Używanie słów kluczowych warunkowych

W pliku przepływu pracy można uzyskiwać dostęp do informacji kontekstowych i oceniać wyrażenia. Mimo że wyrażenia są często używane ze słowem kluczowym warunkowym if w pliku przepływu pracy w celu określenia, czy krok powinien zostać uruchomiony, czy nie, można użyć dowolnego obsługiwanego kontekstu i wyrażenia do utworzenia warunkowego. Należy pamiętać, że w przypadku korzystania z warunkowych w przepływie pracy należy użyć określonej składni ${{ <expression> }}. Ta składnia nakazuje usłudze GitHub obliczenie wyrażenia, a nie traktowanie go jako ciągu.

Na przykład przepływ pracy, który używa warunkowego if do sprawdzenia, czy github.ref (gałąź lub tag ref, który wyzwolił przebieg przepływu pracy) pasuje do refs/heads/main. Aby kontynuować, przepływ pracy będzie wyglądać mniej więcej tak:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Zwróć uwagę, ${{ }} że w tym przykładzie brakuje w składni . W przypadku niektórych wyrażeń, takich jak if warunkowe, można pominąć składnię wyrażeń. Usługa GitHub automatycznie ocenia niektóre z tych typowych wyrażeń, ale zawsze można je uwzględnić w przypadku zapomnienia, które wyrażenia są automatycznie obliczane przez usługę GitHub.

Aby uzyskać więcej informacji na temat składni i wyrażeń przepływu pracy, zapoznaj się ze składnią przepływu pracy dla funkcji GitHub Actions.

Wyłączanie i usuwanie przepływów pracy

Po dodaniu przepływu pracy do repozytorium może wystąpić sytuacja, w której chcesz tymczasowo wyłączyć przepływ pracy. Możesz zatrzymać wyzwalanie przepływu pracy bez konieczności usuwania pliku z repozytorium w usłudze GitHub lub za pośrednictwem interfejsu API REST usługi GitHub. Jeśli chcesz ponownie włączyć przepływ pracy, możesz to łatwo zrobić przy użyciu tych samych metod.

Wyłączenie przepływu pracy może być przydatne w niektórych z następujących sytuacji:

• Błąd w przepływie pracy powoduje generowanie zbyt wielu lub nieprawidłowych żądań wpływających negatywnie na usługi zewnętrzne.
• Chcesz tymczasowo wstrzymać przepływ pracy, który nie jest krytyczny i zużywa zbyt wiele minut na koncie.
• Chcesz wstrzymać przepływ pracy wysyłający żądania do usługi, która nie działa.
• Pracujesz nad forkiem i nie potrzebujesz całej funkcjonalności niektórych zawartych w nim przepływów pracy (jak zaplanowane przepływy pracy).

Możesz również anulować przebieg przepływu pracy, który jest w toku w interfejsie użytkownika usługi GitHub, na karcie Akcje lub przy użyciu punktu końcowego interfejsu DELETE /repos/{owner}/{repo}/actions/runs/{run_id}API usługi GitHub. Pamiętaj, że po anulowaniu uruchomienia przepływu pracy GitHub anuluje wszystkie jego zadania i kroki w ramach tego uruchomienia.

Korzystanie z szablonowego przepływu pracy organizacji

Jeśli masz przepływ pracy używany przez wiele zespołów w organizacji, nie musisz ponownie tworzyć tego samego przepływu pracy dla każdego repozytorium. Zamiast tego można podwyższyć spójność w całej organizacji przy użyciu szablonu przepływu pracy zdefiniowanego w repozytorium organizacji .github . Każdy członek w organizacji może używać przepływu pracy szablonu organizacji, a dowolne repozytorium w tej organizacji ma dostęp do tych przepływów pracy szablonów.

Te przepływy pracy można znaleźć, przechodząc do karty Akcje repozytorium w organizacji, wybierając pozycję Nowy przepływ pracy, a następnie znajdując sekcję szablonu przepływu pracy organizacji zatytułowaną "Przepływy pracy utworzone według nazwy organizacji". Na przykład organizacja o nazwie Mona ma szablon przepływu pracy, jak przedstawiono tutaj.

Używanie określonych wersji akcji

Podczas odwoływania się do akcji w przepływie pracy zalecamy odwoływanie się do określonej wersji tej akcji, a nie tylko samej akcji. Odwołując się do określonej wersji, umieszczasz zabezpieczenie przed nieoczekiwanymi zmianami wypchniętymi do akcji, która może potencjalnie przerwać przepływ pracy. Poniżej przedstawiono kilka sposobów odwołowania się do określonej wersji akcji:

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Niektóre odwołania są bezpieczniejsze niż inne. Na przykład odwoływanie się do określonej gałęzi powoduje uruchomienie akcji z najnowszymi zmianami z tej gałęzi, co może być lub nie być pożądane. Odwołując się do określonego numeru wersji lub zatwierdzenia skrótu SHA, bardziej szczegółowe informacje na temat wersji uruchomionej akcji. Aby uzyskać większą stabilność i bezpieczeństwo, zalecamy użycie zatwierdzenia sha akcji wydanej w przepływach pracy.