Konfigurace pracovního postupu GitHub Actions

  • 10 min

Tady se dozvíte o některých běžných konfiguracích v souboru pracovního postupu. Prozkoumáte také kategorie typů událostí, zakázání a odstranění pracovních postupů a použití konkrétních verzí akce pro osvědčené postupy zabezpečení.

Konfigurace pracovních postupů pro spouštění naplánovaných událostí

Jak už bylo zmíněno dříve, můžete nakonfigurovat pracovní postupy tak, aby běžely, když dojde ke konkrétní aktivitě na GitHubu, když dojde k události mimo GitHub nebo v naplánovaném čase. Událost schedule umožňuje aktivovat pracovní postup, který se bude spouštět v určitých časech UTC pomocí syntaxe POSIX cron. Tato syntaxe cron má pět * polí a každé pole představuje jednotku času.

Diagram pěti časových polí pro naplánování události v souboru pracovního postupu

Pokud byste například chtěli spustit pracovní postup každých 15 minut, schedule událost by vypadala jako v následujícím příkladu:

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

A pokud byste chtěli spustit pracovní postup každou neděli v 3:00, schedule událost by vypadala takto:

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

Operátory můžete použít také k určení rozsahu hodnot nebo k vytáčení v naplánovaném pracovním postupu. Nejkratší interval, který můžete spouštět naplánované pracovní postupy, je jednou za pět minut a běží na nejnovějším potvrzení ve výchozí nebo základní větvi.

Konfigurace pracovních postupů pro spouštění ručních událostí

Kromě plánovaných událostí můžete pracovní postup aktivovat ručně pomocí workflow_dispatch události. Tato událost umožňuje spustit pracovní postup pomocí rozhraní REST API GitHubu nebo výběrem tlačítka Spustit pracovní postup na kartě Akce v úložišti na GitHubu. Pomocí workflow_dispatch můžete zvolit, pro kterou větev má pracovní postup běžet, a nastavit volitelné inputs, které GitHub prezentuje jako prvky formuláře v uživatelském rozhraní.

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

Kromě workflow_dispatchtoho můžete pomocí rozhraní API GitHubu aktivovat událost webhooku s názvem repository_dispatch. Tato událost umožňuje aktivovat pracovní postup pro aktivitu, která se vyskytuje mimo GitHub. V podstatě slouží jako požadavek HTTP do vašeho úložiště s žádostí GitHubu o aktivaci pracovního postupu mimo akci nebo webhook. Použití této ruční události vyžaduje, abyste udělali dvě věci: odešlete POST požadavek do koncového bodu /repos/{owner}/{repo}/dispatches GitHubu s názvy událostí webhooku v textu požadavku a nakonfigurujte pracovní postup tak, aby tuto událost používal repository_dispatch .

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]

Konfigurace pracovních postupů pro spouštění událostí webhooku

Nakonec můžete nakonfigurovat pracovní postup, který se má spustit, když na GitHubu dojde ke konkrétním událostem webhooku. U webhooku můžete aktivovat většinu událostí webhooku z více než jedné aktivity. Pokud pro webhook existuje více aktivit, můžete zadat typ aktivity, který má pracovní postup aktivovat. Můžete například spustit pracovní postup pro check_run událost, ale pouze pro aktivity typu rerequested nebo requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

Odeslání úložiště

repository_dispatch je vlastní událost v GitHub Actions, která umožňuje externím systémům (nebo dokonce jiným pracovním postupům GitHubu) ručně aktivovat pracovní postupy odesláním požadavku POST do rozhraní API GitHubu. Umožňuje flexibilní automatizaci a integraci s externími nástroji, skripty nebo systémy, které potřebují spouštět pracovní postupy v úložišti.

Případy použití

  • Spouštění pracovních postupů externími nástroji CI/CD.

  • Koordinovat nasazení několika repozitářů (například, po dokončení sestavení repozitáře A se spouští repozitář B).

  • Spusťte automatizaci na základě externích událostí (webhooky, výstrahy monitorování, úlohy CRON mimo GitHub).

  • Zřetězení spouštění pracovních postupů mezi úložišti nebo v rámci monorepos

Ukázkový pracovní postup, který naslouchá události 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 }}"

Klíčové prvky:

  • typy: Volitelné. Definuje vlastní typy událostí, jako je run-tests, deploy-to-prodatd.

  • github.event.client_payload: Přístup k jakýmkoli jiným vlastním datům předanými v události odeslání.

  • github.event.action: Název typu události, který byl odeslán.

Aktivace události prostřednictvím rozhraní API

Požadavek POST musíte odeslat do koncového bodu rozhraní REST API GitHubu v3:

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

Autorizace

  • Vyžaduje osobní přístupový token (PAT) s oborem úložiště.
  • Pro organizace zajistěte správné nastavení přístupu pro váš token.

Ukázková struktura příkazů

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 užitečného zatížení

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

Parametry

Pole Typ Popis Povinné
event_type řetězec Vlastní název události. Tento název odpovídá hodnotě typu ve spouštěči pracovního postupu. Ano
client_payload objekt Libovolná datová část JSON pro odesílání vlastních dat do pracovního postupu (github.event.client_payload) Ne

Rozpis parametrů pro Repository_dispatch

Při vytváření požadavku POST na koncový bod rozhraní API GitHubu musíte předat text JSON se dvěma hlavními parametry:

  • typ události
  • klientský_náklad
typ události

Vlastní řetězec, který definujete jako požadovaný. GitHub považuje tuto hodnotu za akci nebo typ odeslání. Slouží k identifikaci toho, co aktivovalo pracovní postup a filtrování pracovních postupů, které naslouchají konkrétním typům.

  • Formát:

    • Typ: řetězec
    • Příklad: "deploy", "run-tests", "sync-db", "build-docker"

  • Použití v pracovním postupu: Používá se při naslouchání konkrétním typům událostí a přístupu k hodnotě uvnitř pracovního postupu. To pomáhá s opětovným použitím jednoho pracovního postupu pro více účelů a zajišťuje automatizaci uspořádanější a řízenou událostmi.

  • Příklad:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"
klientský_náklad

Volný objekt JSON, který umožňuje odesílat vlastní data spolu s expedicí. Definujete strukturu a je přístupná uvnitř pracovního postupu.

  • Formát:

    • Typ: objekt
    • Vlastní klíče a hodnoty

  • Použití v pracovním postupu: Tento objekt se používá pro nasazení v různých prostředích, verzované vydání, nebo předávání kontextu z jiného systému nebo datového toku a umožňuje parametrizované pracovní postupy, podobně jako vstupní argumenty.

  • Příklad:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"
Příklad rozpisu datové zátěže
{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

Použití podmíněných klíčových slov

V souboru pracovního postupu můžete získat přístup k informacím o kontextu a vyhodnotit výrazy. Přestože se výrazy běžně používají s podmíněným if klíčovým slovem v souboru pracovního postupu k určení, jestli se má krok spustit nebo ne, můžete k vytvoření podmíněného výrazu použít libovolný podporovaný kontext a výraz. Je důležité vědět, že při použití podmíněných výrazů v pracovním postupu je potřeba použít konkrétní syntaxi ${{ <expression> }}. Tato syntaxe říká GitHubu, aby vyhodnotil výraz místo toho, aby s ním zacházel jako s řetězcem.

Například pracovní postup, který používá if podmínku ke kontrole, zda github.ref (větev nebo značka, která aktivovala spuštění pracovního postupu) odpovídá refs/heads/main. Aby bylo možné pokračovat, pracovní postup by vypadal přibližně takto:

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

Všimněte si, ${{ }} že v tomto příkladu chybí syntaxe. U některých výrazů, jako jsou if podmíněné výrazy, můžete vynechat syntaxi výrazu. GitHub automaticky vyhodnotí některé z těchto běžných výrazů, ale v případě, že zapomenete, které výrazy GitHub automaticky vyhodnotí, můžete je zahrnout.

Další informace o syntaxi a výrazech pracovního postupu najdete v syntaxi pracovního postupu pro GitHub Actions.

Zakázání a odstranění pracovních postupů

Po přidání pracovního postupu do úložiště můžete najít situaci, kdy chcete pracovní postup dočasně zakázat. Můžete zastavit aktivaci pracovního postupu, aniž byste museli odstranit soubor z úložiště, a to buď na GitHubu, nebo prostřednictvím rozhraní REST API GitHubu. Pokud chcete pracovní postup znovu povolit, můžete ho snadno provést stejnými metodami.

Snímek obrazovky se zákazem pracovního postupu na GitHubu

Zakázání pracovního postupu může být užitečné v některých z následujících situací:

  • Chyba pracovního postupu vytváří příliš mnoho nebo nesprávných požadavků, které mají negativní vliv na externí služby.
  • Chcete dočasně pozastavit pracovní postup, který není kritický a zabírají na vašem účtu příliš mnoho minut.
  • Chcete pozastavit pracovní postup, který odesílá požadavky do služby, která je v provozu.
  • Pracujete na forku a nepotřebujete všechny funkce některých pracovních postupů, které zahrnuje (například naplánované pracovní postupy).

Můžete také zrušit spuštění pracovního postupu, které probíhá v uživatelském rozhraní GitHubu, z karty Actions nebo pomocí koncového bodu DELETE /repos/{owner}/{repo}/actions/runs/{run_id}rozhraní API GitHubu . Mějte na paměti, že když zrušíte spuštění pracovního postupu, GitHub zruší všechny své úlohy a kroky v rámci tohoto spuštění.

Použití pracovního postupu v šabloně organizace

Pokud máte pracovní postup, který v organizaci používá více týmů, nemusíte pro každé úložiště znovu vytvářet stejný pracovní postup. Místo toho můžete zvýšit konzistenci ve vaší organizaci pomocí šablony pracovního postupu definované v úložišti organizace .github . Každý člen v organizaci může použít pracovní postup šablony organizace a jakékoli úložiště v organizaci má přístup k těmto pracovním postupům šablony.

Tyto pracovní postupy najdete tak, že přejdete na kartu Akce úložiště v organizaci, vyberete Nový pracovní postup a pak vyhledáte oddíl šablony pracovního postupu organizace s názvem Pracovní postupy vytvořené názvem organizace. Například organizace s názvem Mona má pracovní postup šablony, jak je znázorněno tady.

Snímek obrazovky pracovního postupu organizace šablony s názvem greet and triage by Mona

Použití konkrétních verzí akce

Při odkazování na akce v pracovním postupu doporučujeme místo samotné akce odkazovat na konkrétní verzi této akce. Odkazováním na konkrétní verzi umístíte ochranu před neočekávanými změnami nasdílenými do akce, která by mohla potenciálně narušit váš pracovní postup. Tady je několik způsobů, jak můžete odkazovat na konkrétní verzi akce:

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

Některé odkazy jsou bezpečnější než jiné. Například odkazování na konkrétní větev spustí akci z nejnovějších změn této větve, což můžete chtít nebo ne. Odkazováním na konkrétní číslo verze nebo potvrzením hodnoty hash SHA je konkrétnější o verzi spuštěné akce. Pro větší stabilitu a zabezpečení doporučujeme použít sha potvrzení vydané akce v rámci pracovních postupů.