GitHub Actions -työnkulun määrittäminen

10 minuuttia

Tässä on joitakin yleisiä määrityksiä työnkulkutiedostossa. Voit myös tarkastella tapahtumatyyppien luokkia, poistaa työnkulkuja käytöstä ja poistaa niitä sekä käyttää toiminnon tiettyjä versioita suojauksen parhaisiin käytäntöihin.

Määritä ajoitettuja tapahtumia varten suoritettavat työnkulut

Kuten aiemmin mainittiin, voit määrittää työnkulut suoritettavaksi, kun GitHubissa ilmenee tiettyä toimintaa, kun GitHubin ulkopuolella tapahtuu tapahtuma tai kun se on ajoitettuna ajankohtana. schedule -tapahtuman avulla voit käynnistää työnkulun suoritettavaksi tiettynä UTC-aikana käyttämällä POSIX-cron-syntaksin. Tässä cron-syntaksissa on viisi * kenttää, ja kukin kenttä edustaa aikayksikköä.

Kaavio viidestä aikayksikkökentästä tapahtuman ajoittamista varten työnkulkutiedostossa.

Jos esimerkiksi haluat suorittaa työnkulun 15 minuutin välein, schedule tapahtuma näyttää seuraavanlaiselta:

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

Jos haluat suorittaa työnkulun joka sunnuntai klo 3.00, schedule tapahtuma näyttäisi tältä:

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

Operaattoreiden avulla voit myös määrittää arvoalueen tai valita haluamasi ajoitetun työnkulun. Lyhin aikaväli, jonka voit suorittaa ajoitettujen työnkulkujen suorittamiseen, on viiden minuutin välein. Ne suoritetaan oletus- tai perushaaran uusimmassa vahvistussa.

Määritä työnkulut suoritettavaksi manuaalisia tapahtumia varten

Ajoitettujen tapahtumien lisäksi voit käynnistää työnkulun manuaalisesti käyttämällä workflow_dispatch-tapahtumaa. Tämän tapahtuman avulla voit suorittaa työnkulun GitHub REST -ohjelmointirajapinnan avulla tai valitsemalla Suorita työnkulku -painikkeen GitHubin säilön Toiminnot -välilehdessä. - workflow_dispatchtoiminnolla voit valita, minkä haaran haluat suorittaa työnkulun, ja määrittää valinnaisen inputs ominaisuuden, jonka GitHub esittää käyttöliittymän lomake-elementteinä.

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

workflow_dispatchlisäksi voit käyttää GitHub-ohjelmointirajapintaa käynnistääksesi webhook-tapahtuman nimeltä repository_dispatch. Tämän tapahtuman avulla voit käynnistää työnkulun aktiviteetille, joka tapahtuu GitHubin ulkopuolella. Se toimii periaatteessa HTTP-pyynnönä säilössäsi ja pyytää GitHubia käynnistämään toiminnon tai webhookin työnkulun. Tämän manuaalisen tapahtuman käyttäminen edellyttää kahta asiaa: POST pyynnön lähettämistä GitHub-päätepisteeseen /repos/{owner}/{repo}/dispatches niin, että webhook-tapahtumien nimet ovat pyynnön leipätekstissä, ja määrittämällä työnkulkusi käyttämään repository_dispatch-tapahtumaa.

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]

Määritä työnkulut suoritettavaksi webhook-tapahtumia varten

Lopuksi voit määrittää työnkulun suoritettavaksi, kun GitHubissa tapahtuu tiettyjä webhook-tapahtumia. Voit käynnistää useimmat webhook-tapahtumat useammasta kuin yhdestä webhook-aktiviteetista. Jos webhookille on olemassa useita toimintoja, voit määrittää toimintotyypin työnkulun käynnistämiseksi. Voit esimerkiksi suorittaa tapahtuman työnkuluncheck_run, mutta vain - tai rerequested -requested_actiontoimintotyypeille.

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch on GitHub Actionsin mukautettu tapahtuma, joka sallii ulkoisten järjestelmien (tai jopa muiden GitHub-työnkulkujen) käynnistää työnkulkuja manuaalisesti lähettämällä POST-pyynnön GitHub-ohjelmointirajapintaan. Se mahdollistaa joustavan automatisoinnin ja integroinnin ulkopuolisiin työkaluihin, komentosarkoihin tai järjestelmiin, joiden on aloitettava työnkulkuja säilössäsi.

Käyttötilanteet

Käynnistä työnkulkuja ulkoisista CI/CD-työkaluista.
Koordinoi usean säilön käyttöönottoja (esimerkiksi Säilö A viimeistelee koontiversiot, → käynnistää Säilön B).
Aloita automatisointi ulkoisten tapahtumien (webhookit, valvontailmoitukset, CRON-työt GitHubin ulkopuolella) perusteella.
Ketjutyönkulun suoritusten suorittaminen säilöjen välillä tai monosäilöjen sisällä.

Esimerkkityönkulku, joka kuuntelee 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 }}"

Keskeiset elementit:

types: Valinnainen. Määrittää mukautetut tapahtumatyypit, kuten run-tests, deploy-to-prodjne.
github.event.client_payload: Pääset käsiksi muihin lähetystapahtumassa välitettyihin mukautettuihin tietoihin.
github.event.action: Lähetetyn event_type nimi.

Tapahtuman käynnistäminen ohjelmointirajapinnan kautta

Sinun on lähetettävä POST-pyyntö GitHub REST -ohjelmointirajapinnan v3 -päätepisteeseen:

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

Valtuutus

Edellyttää henkilökohtaista käyttöoikeustietuetta (PAT), joka sisältää säilön laajuuden.
Varmista organisaatioissa, että tunnuksen käyttöoikeusasetukset ovat asianmukaiset.

Esimerkkikomentorakenteesta

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

Tietojen rakenne

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

Parametrit

Pelto	Kirjoita	Kuvaus	Pakollinen
`event_type`	merkkijono	Tapahtuman mukautettu nimi. Tämä nimi yhdistää työnkulun käynnistimen tyyppiarvoihin	Kyllä
`client_payload`	objekti	Satunnaiset JSON-tiedot mukautettujen tietojen lähettämiseksi työnkulkuun (github.event.client_payload)	Ei

Repository_dispatch parametrien erittely

Kun teet POST-pyynnön GitHub-ohjelmointirajapinnan päätepisteeseen, sinun on välitettävä JSON-runko, jossa on kaksi pääparametria:

event_type
client_payload

event_type

Pakollinen mukautettu merkkijono, jonka määrität. GitHub käsittelee tätä arvoa viestin "toimintona" tai "tyyppinä". Sen avulla määritetään, mikä käynnisti työnkulun, ja suodatetaan työnkulkuja, jotka kuuntelevat tiettyjä tyyppejä.

Formaatti:
- Tyyppi: merkkijono
- Esimerkki: "deploy", "run-tests", "sync-db", "build-docker"
Käytä työnkulussa: Käytetään kuuntelemaan tiettyjä tapahtumatyyppejä ja käyttämään arvoa työnkulun sisällä. Tämä auttaa yksittäisen työnkulun uudelleenkäytössä useisiin tarkoituksiin ja tekee automaatiosta järjestelmällisempää ja tapahtumapohjaisempaa.
Esimerkki:

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

client_payload

Vapaamuotoinen JSON-objekti, jonka avulla voit lähettää mukautettuja tietoja lähetyksen yhteydessä. Kun määrität rakenteen, se on käytettävissä työnkulussa.

Formaatti:
- Tyyppi: objekti
- Mukautetut avaimet ja arvot
Käytä työnkulussa: Objektia käytetään usean ympäristön käyttöönotoissa, versioiduissa versioissa tai kontekstin välittämiseen toisesta järjestelmästä tai putkesta, ja se mahdollistaa parametrisoidut työnkulut, jotka muistuttavat syöteargumentteja.
Esimerkki:

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

Esimerkin tietojen erittely

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

Ehdollisten avainsanojen käyttäminen

Työnkulkutiedostossa voit käyttää kontekstitietoja ja arvioida lausekkeita. Vaikka lausekkeita käytetään yleensä työnkulkutiedoston ehdollisen if avainsanan kanssa sen määrittämiseksi, suoritetaanko vaihe vai ei, voit luoda ehdollisen ehdon minkä tahansa tuetun kontekstin ja lausekkeen avulla. On tärkeää tietää, että kun käytät työnkulussa ehdollisia ehtoja, sinun on käytettävä tiettyä syntaksia ${{ <expression> }}. Tämä syntaksi kertoo GitHubille, että se arvioi lausekkeen sen sijaan, että sitä kohdeltaisi merkkijonona.

Esimerkiksi työnkulku, joka tarkistaa ehdon if avulla, vastaako github.refrefs/heads/maintyönkulkusuorituksen käynnistänyt (haara tai tunnisteen viittaus). Jotta voit jatkaa, työnkulku näyttää suunnilleen tältä:

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

Huomaa, että tässä esimerkissä ${{ }} puuttuvat syntaksista. Joillakin lausekkeilla, kuten ehdolla if , voit jättää lausekkeen syntaksin pois. GitHub arvioi automaattisesti joitakin näistä yleisistä lausekkeista, mutta voit aina sisällyttää ne siltä varalta, että unohdat, mitkä lausekkeet GitHub arvioi automaattisesti.

Lisätietoja työnkulun syntaksista ja lausekkeista on Workflow-syntaksi GitHub Actions.

Työnkulkujen poistaminen käytöstä ja poistaminen

Kun olet lisännyt työnkulun säilöösi, saatat haluta poistaa työnkulun tilapäisesti käytöstä. Voit estää työnkulun käynnistämisen poistamatta tiedostoa säilöstä GitHubissa tai GitHub REST -ohjelmointirajapinnan kautta. Kun haluat ottaa työnkulun käyttöön uudelleen, voit helposti tehdä sen käyttämällä samoja menetelmiä.

Näyttökuva työnkulun poistamisesta käytöstä GitHubissa.

Työnkulun poistamisesta käytöstä voi olla hyötyä seuraavissa tilanteissa:

Työnkulun virhe tuottaa liian monta tai väärää pyyntöä, mikä vaikuttaa kielteisesti ulkoisiin palveluihin.
Haluat keskeyttää tilapäisesti työnkulun, joka ei ole kriittinen ja joka käyttää liian monta minuuttia tililläsi.
Haluat keskeyttää työnkulun, joka lähettää pyyntöjä purettavaan palveluun.
Olet tekemässä haarautumia, etkä tarvitse kaikkia sen sisältämien työnkulkujen toimintoja (kuten ajoitettuja työnkulkuja).

Voit myös peruuttaa GitHub-käyttöliittymässä käynnissä olevan työnkulun suorituksen toiminnot -välilehdestä tai käyttämällä GitHub-ohjelmointirajapinnan päätepistettä DELETE /repos/{owner}/{repo}/actions/runs/{run_id}. Muista, että kun peruutat työnkulun suorituksen, GitHub peruuttaa kaikki työt ja vaiheet kyseisessä suorituksessa.

Organisaation mallityönkulun käyttäminen

Jos sinulla on työnkulku, jota useat tiimit käyttävät organisaatiossa, sinun ei tarvitse luoda samaa työnkulkua uudelleen jokaiselle säilölle. Sen sijaan voit edistää organisaatiosi johdonmukaisuutta käyttämällä työnkulkumallia, joka on .github määritetty organisaation säilössä. Kuka tahansa organisaation jäsen voi käyttää organisaation mallityönkulkua ja mitä tahansa kyseisen organisaation säilöä, jolla on käyttöoikeus näihin mallityönkulkuihin.

Löydät nämä työnkulut siirtymällä säilön Toiminnot välilehdelle organisaatiossa, valitsemalla Uusi työnkulkuja etsimällä sitten organisaation työnkulkumalli -osion nimeltä "työnkulut, jotka on luonut organisaation nimi". Esimerkiksi Mona-nimisessä organisaatiossa on mallityönkulku tässä esitetyllä tavalla.

Näyttökuva mona-nimisestä malliorganisaation työnkulusta.

Toiminnon tiettyjen versioiden käyttäminen

Kun viittaat työnkulun toimintoihin, suosittelemme, että viittaat toiminnon tiettyyn versioon pelkän toiminnon sijasta. Viittaamalla tiettyyn versioon asetat suojauksen odottamattomilta muutoksilta, jotka on lähetetty toimintoon, joka voi mahdollisesti rikkoa työnkulkusi. Voit viitata toiminnon tiettyyn versioon useilla eri tavoilla:

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

Jotkin viittaukset ovat turvallisempia kuin toiset. Esimerkiksi tiettyyn haaraan viittaaminen suorittaa toiminnon kyseisen haaran uusimmista muutoksista, joita ehkä haluat tai et halua. Kun viittaat tiettyyn versionumeroon tai vahvistat SHA-hajautuksen, olet tarkempi sen toiminnon versiosta, jota käytät. Jos haluat lisää vakautta ja suojausta, suosittelemme, että käytät julkaistun toiminnon vahvistamisen SHA-toimintoa työnkuluissasi.

Palaute

Onko tästä sivusta apua?