Konfigurera ett GitHub Actions-arbetsflöde

  • 10 minuter

Här lär du dig några vanliga konfigurationer i en arbetsflödesfil. Du kan också utforska kategorier av händelsetyper, inaktivera och ta bort arbetsflöden och använda specifika versioner av en åtgärd för bästa praxis för säkerhet.

Konfigurera arbetsflöden som ska köras för schemalagda händelser

Som tidigare nämnts kan du konfigurera dina arbetsflöden så att de körs när en specifik aktivitet inträffar på GitHub, när en händelse utanför GitHub inträffar eller vid en schemalagd tidpunkt. Med schedule händelsen kan du utlösa ett arbetsflöde som körs vid specifika UTC-tider med hjälp av POSIX cron-syntax. Den här cron-syntaxen har fem * fält och varje fält representerar en tidsenhet.

Diagram över de fem tidsenhetsfälten för schemaläggning av en händelse i en arbetsflödesfil.

Om du till exempel vill köra ett arbetsflöde var 15:e minut schedule skulle händelsen se ut som i följande exempel:

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

Och om du vill köra ett arbetsflöde varje söndag klockan 03:00 schedule skulle händelsen se ut så här:

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

Du kan också använda operatorer för att ange ett intervall med värden eller för att ringa in ditt schemalagda arbetsflöde. Det kortaste intervallet du kan köra schemalagda arbetsflöden är en gång var femte minut och de körs på den senaste incheckningen på standard- eller basgrenen.

Konfigurera arbetsflöden som ska köras för manuella händelser

Förutom schemalagda händelser kan du manuellt utlösa ett arbetsflöde med hjälp workflow_dispatch av händelsen. Med den här händelsen kan du köra arbetsflödet med hjälp av GitHub REST API eller genom att välja knappen Kör arbetsflöde på fliken Åtgärder på din lagringsplats på GitHub. Med hjälp av workflow_dispatch kan du välja vilken gren du vill att arbetsflödet ska köras på och ställ in valfria inputs som GitHub presenterar som formulärelement i användargränssnittet.

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

Förutom workflow_dispatchkan du använda GitHub-API:et för att utlösa en webhook-händelse med namnet repository_dispatch. Med den här händelsen kan du utlösa ett arbetsflöde för aktivitet som inträffar utanför GitHub. Det fungerar i princip som en HTTP-begäran till din lagringsplats där GitHub uppmanas att utlösa ett arbetsflöde från en åtgärd eller webhook. Om du använder den här manuella händelsen måste du göra två saker: skicka en POST begäran till GitHub-slutpunkten /repos/{owner}/{repo}/dispatches med webhook-händelsenamnen i begärandetexten och konfigurera arbetsflödet så att det repository_dispatch använder händelsen.

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]

Konfigurera arbetsflöden som ska köras för webhook-händelser

Slutligen kan du konfigurera ett arbetsflöde så att det körs när specifika webhook-händelser inträffar på GitHub. Du kan utlösa de flesta webhook-händelser från flera aktiviteter. Om det finns flera aktiviteter för en webhook kan du ange en aktivitetstyp för att utlösa arbetsflödet. Du kan till exempel köra ett arbetsflöde för check_run händelsen, men bara för aktivitetstyperna rerequested eller requested_action .

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch är en anpassad händelse i GitHub Actions som gör att externa system (eller till och med andra GitHub-arbetsflöden) kan utlösa arbetsflöden manuellt genom att skicka en POST-begäran till GitHub-API:et. Det möjliggör flexibel automatisering och integrering med externa verktyg, skript eller system som behöver starta arbetsflöden på lagringsplatsen.

Användningsfall

  • Utlösa arbetsflöden från externa CI/CD-verktyg.

  • Samordna koddistributioner över flera repositories (till exempel slutför Repo A bygget → utlöser Repo B).

  • Starta automatisering baserat på externa händelser (webhooks, övervakningsaviseringar, CRON-jobb utanför GitHub).

  • Kedja arbetsflödeskörningar mellan lagringsplatser eller inom monorepos.

Exempelarbetsflöde som lyssnar på 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 }}"

Viktiga element:

  • typer: Valfritt. Definierar anpassade händelsetyper som run-tests, deploy-to-prodosv.

  • github.event.client_payload: Åtkomst till andra anpassade data som skickas i sändningshändelsen.

  • github.event.action: Namnet på eventtypen som skickades.

Utlösa händelsen via API

Du måste skicka en POST-begäran till GitHub REST API v3-slutpunkten:

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

Auktorisering

  • Kräver en personlig åtkomsttoken (PAT) med repo-behörighet.
  • För organisationer säkerställer du rätt åtkomstinställningar för din token.

Exempel på kommandostruktur

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"}}'

Nyttolaststruktur

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

Parameterar

Fält Typ Beskrivning Krävs
event_type snöre Ett anpassat namn för händelsen. Det här namnet mappar till typvärdet i arbetsflödesutlösaren Ja
client_payload objekt Valfri JSON-data för att skicka anpassad information till arbetsflödet (github.event.client_payload) Nej

Repository_dispatch parametrarnas uppdelning

När du gör en POST-begäran till GitHub API-slutpunkten måste du skicka en JSON-brödtext med två huvudparametrar:

  • händelsetyp
  • client_payload
händelsetyp

En obligatorisk anpassad sträng som du definierar. GitHub behandlar det här värdet som "åtgärd" eller "typ" av sändningen. Den används för att identifiera vad som utlöste arbetsflödet och filtrera arbetsflöden som lyssnar efter specifika typer.

  • Format:

    • Typ: sträng
    • Exempel: "deploy", "run-tests", "sync-db", "build-docker"

  • Använd i Arbetsflöde: Används för att lyssna efter specifika händelsetyper och få åtkomst till värdet i arbetsflödet. Detta hjälper till med återanvändning av ett enda arbetsflöde i flera syften och gör automatiseringen mer organiserad och händelsedriven.

  • Exempel:

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

Ett JSON-objekt i fritt format som gör att du kan skicka anpassade data tillsammans med sändningen. Du definierar strukturen och är tillgänglig i arbetsflödet.

  • Format:

    • Typ: objekt
    • Anpassade nycklar och värden

  • Använd i Arbetsflöde: Det här objektet används för distributioner i flera miljöer, versionsversioner eller för att skicka kontext från ett annat system eller en annan pipeline och aktiverar parameteriserade arbetsflöden, ungefär som indataargument.

  • Exempel:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"
Exempel på uppdelning av nyttolast
{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

Använda villkorsstyrda nyckelord

I arbetsflödesfilen kan du komma åt kontextinformation och utvärdera uttryck. Även om uttryck ofta används med det villkorsstyrda if nyckelordet i en arbetsflödesfil för att avgöra om ett steg ska köras eller inte, kan du använda alla kontexter och uttryck som stöds för att skapa en villkorsstyrd. Det är viktigt att veta att när du använder villkor i arbetsflödet måste du använda den specifika syntaxen ${{ <expression> }}. Den här syntaxen instruerar GitHub att utvärdera ett uttryck i stället för att behandla det som en sträng.

Ett arbetsflöde som till exempel använder villkoret if för att kontrollera om (grenen github.ref eller taggen ref som utlöste arbetsflödeskörningen) matchar refs/heads/main. För att kunna fortsätta skulle arbetsflödet se ut ungefär så här:

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

Observera att i det här exemplet ${{ }} saknas i syntaxen. Med vissa uttryck, till exempel villkorsstyrda if , kan du utelämna uttryckssyntaxen. GitHub utvärderar automatiskt några av dessa vanliga uttryck, men du kan alltid inkludera dem om du glömmer vilka uttryck GitHub utvärderar automatiskt.

Mer information om arbetsflödessyntax och uttryck finns i Arbetsflödessyntax för GitHub Actions.

Inaktivera och ta bort arbetsflöden

När du har lagt till ett arbetsflöde på lagringsplatsen kan du hitta en situation där du tillfälligt vill inaktivera arbetsflödet. Du kan förhindra att ett arbetsflöde utlöses utan att du behöver ta bort filen från lagringsplatsen, antingen på GitHub eller via GitHub REST API. När du vill aktivera arbetsflödet igen kan du enkelt göra det med samma metoder.

Skärmbild av inaktivering av ett arbetsflöde på GitHub.

Det kan vara användbart att inaktivera ett arbetsflöde i några av följande situationer:

  • Ett fel i ett arbetsflöde genererar för många eller felaktiga begäranden som påverkar externa tjänster negativt.
  • Du vill tillfälligt pausa ett arbetsflöde som inte är kritiskt och som förbrukar för många minuter för ditt konto.
  • Du vill pausa ett arbetsflöde som skickar begäranden till en tjänst som är nere.
  • Du arbetar med en gaffel och behöver inte all funktionalitet i vissa arbetsflöden som de inkluderar, såsom schemalagda arbetsflöden.

Du kan också avbryta en arbetsflödeskörning som pågår i GitHub-användargränssnittet från fliken Åtgärder eller med hjälp av GitHub API-slutpunkten DELETE /repos/{owner}/{repo}/actions/runs/{run_id}. Tänk på att när du avbryter en arbetsflödeskörning avbryter GitHub alla sina jobb och steg inom den körningen.

Använda en organisations mallade arbetsflöde

Om du har ett arbetsflöde som flera team använder i en organisation behöver du inte återskapa samma arbetsflöde för varje lagringsplats. I stället kan du främja konsekvens inom organisationen genom att använda en arbetsflödesmall som definierats i organisationens .github-arkiv. Alla medlemmar i organisationen kan använda ett arbetsflöde för organisationsmallar och alla lagringsplatser i organisationen har åtkomst till dessa mallarbetsflöden.

Du kan hitta dessa arbetsflöden genom att gå till fliken Åtgärder på en lagringsplats i organisationen, välja Nytt arbetsflöde och sedan hitta organisationens arbetsflödesmallavsnitt med titeln "Arbetsflöden som skapats efter organisationsnamn". Organisationen Mona har till exempel ett mallarbetsflöde som visas här.

Skärmbild av ett mallorganisationsarbetsflöde som heter greet och triage av Mona.

Använda specifika versioner av en åtgärd

När du refererar till åtgärder i arbetsflödet rekommenderar vi att du refererar till en specifik version av den åtgärden i stället för bara själva åtgärden. Genom att referera till en specifik version skyddar du mot oväntade ändringar som skickas till åtgärden som potentiellt kan bryta arbetsflödet. Här är flera sätt att referera till en viss version av en åtgärd:

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

Vissa referenser är säkrare än andra. Om du till exempel refererar till en specifik gren, utlöses den åtgärden av de senaste ändringarna från den grenen, beroende på om du vill det eller inte. Genom att referera till ett specifikt versionsnummer eller checka in SHA-hash är du mer specifik om vilken version av åtgärden du kör. För mer stabilitet och säkerhet rekommenderar vi att du använder inchecknings-SHA för en frisläppt åtgärd i dina arbetsflöden.