Konfigurere en Arbeidsflyt for GitHub-handlinger

10 minutter

Her lærer du noen vanlige konfigurasjoner i en arbeidsflytfil. Du kan også utforske kategoriene for hendelsestyper, deaktivere og slette arbeidsflyter og bruke bestemte versjoner av en handling for anbefalte fremgangsmåter for sikkerhet.

Konfigurere arbeidsflyter til å kjøre for planlagte hendelser

Som nevnt tidligere kan du konfigurere arbeidsflytene til å kjøre når spesifikk aktivitet forekommer på GitHub, når en hendelse utenfor GitHub skjer, eller på et planlagt tidspunkt. Med schedule-hendelsen kan du utløse en arbeidsflyt som skal kjøres på bestemte UTC-tidspunkt ved hjelp av POSIX cron-syntaks. Denne cron-syntaksen har fem * felt, og hvert felt representerer en tidsenhet.

diagram over de fem enhetsfeltene for planlegging av en hendelse i en arbeidsflytfil.

Hvis du for eksempel vil kjøre en arbeidsflyt hvert 15. minutt, schedule vil hendelsen se ut som følgende eksempel:

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

Og hvis du vil kjøre en arbeidsflyt hver søndag klokken 03:00, vil schedule-hendelsen se slik ut:

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

Du kan også bruke operatorer til å angi et verdiområde eller ringe inn den planlagte arbeidsflyten. Det korteste intervallet du kan kjøre planlagte arbeidsflyter er én gang hvert femte minutt, og de kjører på den siste utførelsen på standard- eller basisgrenen.

Konfigurere arbeidsflyter til å kjøre for manuelle hendelser

I tillegg til planlagte hendelser kan du manuelt utløse en arbeidsflyt ved hjelp av workflow_dispatch hendelsen. Denne hendelsen lar deg kjøre arbeidsflyten ved hjelp av GitHub REST-API-en eller ved å velge Kjør arbeidsflyt-knappen i Handlinger--fanen i repositoriet på GitHub. Ved hjelp av workflow_dispatchkan du velge hvilken gren du vil at arbeidsflyten skal kjøre, og angi valgfritt inputs som GitHub presenterer som skjemaelementer i brukergrensesnittet.

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

I tillegg til workflow_dispatchkan du bruke GitHub-API-en til å utløse en webhook-hendelse kalt repository_dispatch. Denne hendelsen lar deg utløse en arbeidsflyt for aktivitet som forekommer utenfor GitHub. Det fungerer i hovedsak som en HTTP-forespørsel til repositoriet som ber GitHub om å utløse en arbeidsflyt av en handling eller webhook. Hvis du bruker denne manuelle hendelsen, må du gjøre to ting: Send en POST forespørsel til GitHub-endepunktet /repos/{owner}/{repo}/dispatches med navnene på webhook-hendelsen i meldingsteksten, og konfigurer arbeidsflyten til å bruke repository_dispatch hendelsen.

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]

Konfigurer arbeidsflyter til å kjøre for webhook-hendelser

Til slutt kan du konfigurere en arbeidsflyt til å kjøre når bestemte webhook-hendelser forekommer på GitHub. Du kan utløse de fleste webhook-hendelser fra mer enn én aktivitet for en webhook. Hvis det finnes flere aktiviteter for en webhook, kan du angi en aktivitetstype for å utløse arbeidsflyten. Du kan for eksempel kjøre en arbeidsflyt for check_run hendelsen, men bare for rerequested aktivitetstypene.requested_action

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch er en egendefinert hendelse i GitHub-handlinger som gjør det mulig for eksterne systemer (eller andre GitHub-arbeidsflyter) å utløse arbeidsflyter manuelt ved å sende en POST-forespørsel til GitHub-API-en. Det muliggjør fleksibel automatisering og integrering med eksterne verktøy, skript eller systemer som må starte arbeidsflyter i repo.

Brukstilfeller

Utløse arbeidsflyter fra eksterne CI/CD-verktøy.
Koordinere flerrepodistribusjoner (for eksempel fullfører repo A bygg → utløser Repo B).
Start automatisering basert på eksterne hendelser (webhooks, overvåkingsvarsler, CRON-jobber utenfor GitHub).
Kjedearbeidsflytkjøringer mellom repositorier eller innenfor monorepos.

Eksempelarbeidsflyt som lytter til 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 }}"

Viktige elementer:

typer: Valgfritt. Definerer egendefinerte hendelsestyper som run-tests, osv deploy-to-prod.
github.event.client_payload: Tilgang til eventuelle andre egendefinerte data som sendes i utsendelseshendelsen.
github.event.action: Navnet på event_type sendt.

Utløser hendelsen via API

Du må sende en POST-forespørsel til GitHub REST API v3-endepunktet:

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

Autorisasjon

Krever et personlig tilgangstoken (PAT) med repo-omfang.
For organisasjoner må du sikre riktige tilgangsinnstillinger for tokenet.

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

Nyttelaststruktur

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

Parametere

Felt	Type:	Beskrivelse	Obligatorisk
`event_type`	streng	Et egendefinert navn for hendelsen. Dette navnet tilordnes typeverdien i arbeidsflytutløseren	Ja
`client_payload`	objekt	Tilfeldig JSON-nyttelast for å sende egendefinerte data til arbeidsflyten (github.event.client_payload)	Nei

Repository_dispatch nedbryting av parametere

Når du gjør en POST-forespørsel til GitHub API-endepunktet, må du sende en JSON-brødtekst med to hovedparametere:

event_type
client_payload

event_type

En nødvendig egendefinert streng som du definerer. GitHub behandler denne verdien som «handling» eller «type» for utsendelsen. Den brukes til å identifisere hva som utløste arbeidsflyten og filterarbeidsflytene som lytter etter bestemte typer.

Format:
- Type: streng
- Eksempel: «distribuer», «kjøretester», «sync-db», «build-docker»
Bruk i arbeidsflyt: Brukes til å lytte etter bestemte hendelsestyper og få tilgang til verdien i arbeidsflyten. Dette hjelper med gjenbruk av én enkelt arbeidsflyt til flere formål, og gjør automatiseringen mer organisert og hendelsesdrevet.
Eksempel:

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

client_payload

Et JSON-objekt med fri form som lar deg sende egendefinerte data sammen med utsendelsen. Du definerer strukturen, og den er tilgjengelig i arbeidsflyten.

Format:
- Type: objekt
- Egendefinerte nøkler og verdier
Bruk i arbeidsflyt: Dette objektet brukes til distribusjoner med flere miljøer, versjonsversjoner eller sende kontekst fra et annet system eller datasamlebånd og aktiverer parameteriserte arbeidsflyter, på samme måte som inndataargumenter.
Eksempel:

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

Eksempel på nedbryting av nyttelast

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

Bruk betingede nøkkelord

I arbeidsflytfilen kan du få tilgang til kontekstinformasjon og evaluere uttrykk. Selv om uttrykk ofte brukes med det betingede if nøkkelordet i en arbeidsflytfil for å avgjøre om et trinn skal kjøres eller ikke, kan du bruke en hvilken som helst støttet kontekst og uttrykk til å opprette en betinget. Det er viktig å vite at når du bruker betingede faktorer i arbeidsflyten, må du bruke den bestemte syntaksen ${{ <expression> }}. Denne syntaksen forteller GitHub å evaluere et uttrykk i stedet for å behandle det som en streng.

En arbeidsflyt som for eksempel bruker den if betingede til å kontrollere om github.ref (grenen eller kodereferansen som utløste arbeidsflytkjøringen) samsvarer refs/heads/mainmed . Arbeidsflyten vil se omtrent slik ut for å fortsette:

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

Legg merke til at i dette eksemplet mangler ${{ }} fra syntaksen. Med noen uttrykk, for eksempel den betingede if , kan du utelate uttrykkssyntaksen. GitHub evaluerer automatisk noen av disse vanlige uttrykkene, men du kan alltid inkludere dem i tilfelle du glemmer hvilke uttrykk GitHub evaluerer automatisk.

Hvis du vil ha mer informasjon om arbeidsflytsyntaks og uttrykk, kan du se arbeidsflytsyntaks for GitHub-handlinger.

Deaktivere og slette arbeidsflyter

Når du har lagt til en arbeidsflyt i repositoriet, kan det hende du finner en situasjon der du vil deaktivere arbeidsflyten midlertidig. Du kan hindre at en arbeidsflyt utløses uten å måtte slette filen fra repositoriet, enten på GitHub eller gjennom GitHub REST-API-en. Når du vil aktivere arbeidsflyten på nytt, kan du enkelt gjøre det ved hjelp av de samme metodene.

Skjermbilde av deaktivering av en arbeidsflyt på GitHub.

Deaktivering av en arbeidsflyt kan være nyttig i noen av følgende situasjoner:

En feil i en arbeidsflyt produserer for mange eller feil forespørsler som påvirker eksterne tjenester negativt.
Du vil midlertidig stanse en arbeidsflyt midlertidig som ikke er kritisk, og som bruker for mange minutter på kontoen din.
Du vil stanse en arbeidsflyt midlertidig som sender forespørsler til en tjeneste som er nede.
Du arbeider på en forgrening, og du trenger ikke all funksjonaliteten til enkelte arbeidsflyter den inneholder (for eksempel planlagte arbeidsflyter).

Du kan også avbryte en arbeidsflytkjøring som pågår i GitHub-brukergrensesnittet fra fanen Handlinger, eller ved å bruke GitHub API-endepunktet DELETE /repos/{owner}/{repo}/actions/runs/{run_id}. Husk at når du avbryter en arbeidsflytkjøring, avbryter GitHub alle jobbene og trinnene i denne kjøringen.

Bruke en organisasjons malarbeidsflyt

Hvis du har en arbeidsflyt som flere team bruker i en organisasjon, trenger du ikke å opprette den samme arbeidsflyten på nytt for hvert repositorium. I stedet kan du fremme konsekvens på tvers av organisasjonen ved hjelp av en arbeidsflytmal som er definert i organisasjonens .github repositorium. Alle medlemmer i organisasjonen kan bruke en arbeidsflyt for organisasjonsmal, og alle repositorier i organisasjonen har tilgang til disse malarbeidsflytene.

Du kan finne disse arbeidsflytene ved å navigere til fanen Handlinger i et repositorium i organisasjonen, velge Ny arbeidsflyt, og deretter finne organisasjonens arbeidsflytmalinndeling med tittelen Arbeidsflyter opprettet av organisasjonsnavn". Organisasjonen kalt Mona har for eksempel en malarbeidsflyt som vist her.

Skjermbilde av en malorganisasjonsarbeidsflyt kalt Hils og triage av Mona.

Bruke bestemte versjoner av en handling

Når du refererer til handlinger i arbeidsflyten, anbefaler vi at du refererer til en bestemt versjon av denne handlingen i stedet for bare selve handlingen. Ved å referere til en bestemt versjon, setter du en beskyttelse mot uventede endringer som sendes til handlingen som potensielt kan bryte arbeidsflyten. Her er flere måter du kan referere til en bestemt versjon av en handling på:

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

Noen referanser er tryggere enn andre. Hvis du for eksempel refererer til en bestemt gren, kjøres denne handlingen av de siste endringene fra den grenen, som du kanskje eller kanskje ikke vil ha. Ved å referere til et bestemt versjonsnummer eller utføre SHA-hash-kode, er du mer spesifikk om hvilken versjon av handlingen du kjører. Hvis du vil ha mer stabilitet og sikkerhet, anbefaler vi at du bruker utførings-SHA for en utgitt handling i arbeidsflytene.

Tilbakemeldinger

Var denne siden nyttig?