Werkstromen beheren en fouten opsporen in GitHub Actions

10 minuten

Zoals u zich herinnert, is het uw doel om het proces voor het bouwen en publiceren van code te automatiseren, zodat functies telkens worden bijgewerkt wanneer een ontwikkelaar een wijziging aan de codebasis toevoegt.

Als u dit proces wilt implementeren, leert u het volgende:

Identificeer de gebeurtenis die een werkstroom heeft geactiveerd.
Werkstroomlogboeken van GitHub Actions gebruiken.
Sla buildartefacten op en verkrijg toegang tot deze.
Automatiseer het toevoegen van een label aan een pull-aanvraag na een beoordeling.

De gebeurtenis identificeren die een werkstroom heeft geactiveerd

Inzicht in wat een GitHub Actions-werkstroom heeft geactiveerd, is cruciaal voor foutopsporing, controle en verbetering van CI/CD-pijplijnen. Soorten triggers omvatten een push naar een branch, een pull request die is gemaakt of bijgewerkt, een geplande taak of handmatig versturen. U kunt de activerende gebeurtenis identificeren door de werkstroomuitvoering, de wijzigingen in de opslagplaats en het gerelateerde GitHub-probleem of de pull-aanvraag te bekijken.

Diagram met verschillende werkstroomtriggers in GitHub Actions, zoals push, pull-aanvraag, planning en handmatige verzending.

Wat is een werkstroomtrigger?

Een workflow-trigger is een gebeurtenis die ervoor zorgt dat een workflow wordt uitgevoerd. GitHub ondersteunt verschillende typen triggers, waaronder:

push of pull_request (op basis van codewijzigingen)
workflow_dispatch (een handmatige activatie)
schedule (cron-opdrachten)
repository_dispatch (externe systemen)
Probleem, discussie en pull request events (bijvoorbeeld issues.opened, pull_request.closed)

De trigger-gebeurtenis identificeren

U kunt een gebeurtenis voor een werkstroomtrigger op verschillende manieren identificeren:

Gebruik de gebruikersinterface van GitHub Actions:
1. Selecteer in uw opslagplaats het tabblad Acties .
2. Selecteer een workflow-uitvoering.
Een gebeurtenistype, zoals push, pull_requestof workflow_dispatch, wordt boven aan het uitvoeringsoverzicht van de werkstroom weergegeven.
Gebruiken github.event_name in de logboeken of in een werkstroom.
- GitHub maakt contextgegevens beschikbaar tijdens een werkstroomuitvoering. De github.event_name variabele geeft aan welke gebeurtenis de werkstroom heeft geactiveerd.
- U kunt de informatie in een stap afdrukken voor foutopsporing:
```
-name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"
```
Details van de workflow uitvoering gebruiken:
- Als u werkstroomprogrammatisch inspecteert, zoals met behulp van API, bevat het uitvoeringsobject een event eigenschap waarmee de trigger wordt opgegeven.
- U vindt de commit Secure Hash Algorithm (SHA), actor en tijdstempel om te traceren wat de trigger heeft veroorzaakt.

De trigger afleiden uit opslagplaatseffecten

Mogelijk hebt u geen directe toegang tot de werkstroomuitvoering, maar u wilt nog steeds afleiden wat de werkstroomuitvoering heeft geactiveerd op basis van de activiteit van de opslagplaats:

Waargenomen gedrag	Activerende gebeurtenis
Er is een nieuwe commit gepusht naar `main` en de workflow is uitgevoerd.	`push` gebeurtenis
Er is een pull-aanvraag geopend of bijgewerkt.	`pull_request` gebeurtenis
Een inzender heeft handmatig een werkstroom uitgevoerd.	`workflow_dispatch`
De werkstroom wordt dagelijks uitgevoerd op een bepaald tijdstip.	`schedule` (cron)
De werkstroom werd uitgevoerd na een externe serviceaanroep.	`repository_dispatch`
De workflow werd uitgevoerd toen een label of opmerking werd toegevoegd aan een probleem.	`issues.*` gebeurtenis

Door tijdstempels, activiteit van pull-aanvragen en doorvoergeschiedenis te bekijken, kunt u vaak vaststellen welke actie ervoor heeft gezorgd dat de werkstroom werd uitgevoerd.

Samenvatten hoe u identificeert wat een werkstroom heeft geactiveerd:

Controleer de samenvatting van de werkstroomuitvoering op het tabblad Acties .
Druk af of meld u github.event_name aan in de werkstroom voor zichtbaarheid.
Vergelijk tijdstempels en repositoryactiviteit (commitmenten, pull-aanvragen, problemen) om de trigger af te leiden.
Gebruik de volledige event context voor dieper onderzoek.

Deze procedures helpen u bij het opsporen, controleren en verbeteren van de betrouwbaarheid van werkstromen in uw ontwikkelings- en implementatiepijplijnen.

Inzicht in een werkstroomeffect door het configuratiebestand ervan te lezen

Als u de effecten van een werkstroom wilt begrijpen door het configuratiebestand te lezen, analyseert u de structuur en inhoud van het .yml bestand dat is opgeslagen in .github/workflows/.

Het configuratiebestand voor de werkstroom geeft de volgende informatie over de werkstroom op:

Wanneer deze wordt uitgevoerd (in de on sectie).
Wat het doet (in jobs en steps).
Waar deze wordt uitgevoerd (de runs-on sectie).
Waarom het wordt uitgevoerd (het doel, zoals testen, implementeren of linting).
Hoe het zich gedraagt in specifieke omstandigheden (omgeving, filters, logica).

Een werkstroomeffect interpreteren

Bepaal de oorzaak.

Zie de on sectie van de werkstroom om te bepalen welke actie de werkstroom heeft gestart.

Voorbeeld:
```
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:
```
Deze voorbeeldwerkstroom:
- Wordt automatisch uitgevoerd wanneer code naar de hoofdbranch (push) wordt gepusht.
- Wordt uitgevoerd wanneer een pull-aanvraag wordt gemaakt of bijgewerkt (pull_request).
- Kan handmatig worden geactiveerd door een gebruiker (workflow_dispatch).
Identificeer de werkstroomtaken en -stappen.

Als u wilt bepalen wat de werkstroom doet, raadpleegt u de jobs en steps secties van de werkstroom.

Voorbeeld:
```
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test
```
Deze voorbeeldwerkstroom:
- Maakt gebruik van een virtuele Linux-omgeving (runs-on).
- Controleert de code van de opslagplaats (steps>name).
- Hiermee worden projectafhankelijkheden (steps>name) geïnstalleerd.
- Voert geautomatiseerde tests (steps>name) uit.
Evalueer het doel en het resultaat van de werkstroom.

Door het configuratiebestand te lezen, kunt u het beoogde resultaat van de werkstroom beschrijven:

"Deze werkstroom is een CI-pijplijn (Continuous Integration). Het zorgt ervoor dat elke nieuwe code die naar de opslagplaats wordt gepusht of via een pull-aanvraag wordt verzonden, automatisch wordt getest. Als tests mislukken, wordt dit resultaat weergegeven in de gebruikersinterface van de GitHub-werkstroom om u te helpen codekwaliteit te handhaven.
Optionele functies identificeren of instellen die van invloed zijn op de uitvoering van de werkstroom:
- env stelt omgevingsvariabelen in.
- if voegt voorwaardelijke logica toe om alleen specifieke stappen uit te voeren wanneer aan criteria wordt voldaan.
- timeout-minutes of continue-on-error werkstroomuitvoering en foutafhandeling instellen.

Een mislukte werkstroomrun diagnosticeren

Ga in uw opslagplaats naar het tabblad Acties .
Zoek de mislukte uitvoering (meestal aangegeven door een rode X).
Selecteer de mislukte werkstroom om het uitvoeringsoverzicht te openen.
Controleer de fout in de werkstroomlogboeken.
1. Vouw in het uitvoeringsoverzicht elke taak en stap uit totdat u de taak hebt gevonden die een fout aangeeft.
2. Selecteer de taak of stap om de logboeken ervan weer te geven.
3. Zoek naar:
  - Foutberichten
  - Stacktraceringen
  - Afsluitcodes
Een mislukte test kan npm ERR! Test failed of exit code 1 weergeven.
Controleer het configuratiebestand van de werkstroom.

Gebruik het .yml bestand om het volgende te bepalen:
- Wat probeerde elke stap te doen?
- Als er omgevingsvariabelen (env) of conditionals (if) zijn die van invloed zijn op de uitvoering.
- Als de fout wordt veroorzaakt door een ontbrekende afhankelijkheid, syntaxisfout of onjuist geconfigureerde stap.
Als een stap mislukt, controleert u op de volgende oorzaken:
- Zijn afhankelijkheden succesvol geïnstalleerd in de vorige stap?
- Bestaan er testbestanden en geven ze lokaal door?

Veelvoorkomende foutscenario's

In de volgende tabel worden veelvoorkomende scenario's met werkstroomfouten beschreven:

Symptoom	Waarschijnlijke oorzaak
Een stap mislukt en retourneert `command not found`l	Ontbrekende afhankelijkheid of verkeerde installatie
`npm install` Mislukt.	Beschadigd `package-lock.json` bestand of netwerkprobleem
Een teststap mislukt	Problemen met eenheidstests, ontbrekend configuratiebestand of ongeldige testsyntaxis
`Permission denied` wordt weergegeven.	Onjuiste bestandsmachtigingen of ontbrekende geheimen

Bepalen hoe u toegang hebt tot werkstroomlogboeken in GitHub

Ga in uw opslagplaats naar het tabblad Acties .
Selecteer de relevante werkstroom in de lijst met werkstromen.

Als uw .yml bestand bijvoorbeeld de volgende code heeft, wordt een koppeling met de titel CI Workflow weergegeven in de lijst:
```
name: CI Workflow
```
Selecteer een specifieke sessie.

Selecteer in de lijst met uitvoeringen met de status de tijdstempel of het doorvoerbericht van de specifieke uitvoering die u wilt inspecteren.
Klap elke taak en stap uit.

Op de samenvattingspagina van uitvoering worden opdrachten weergegeven zoals ze zijn gedefinieerd in het werkstroombestand, zoals bouwen of testen.
1. Selecteer een taak om deze uit te vouwen.
2. Vouw in de taak afzonderlijke stappen uit, zoals 'Afhankelijkheden installeren' of 'Tests uitvoeren'.
Logboekuitvoer weergeven.

Als u de volledige logboekuitvoer wilt weergeven, inclusief consolelogboeken, foutberichten en foutopsporingsgegevens, selecteert u een werkstroomstap. U kunt de logboeken kopiëren, zoeken en downloaden.

De volgende tabel bevat een overzicht van de stappen die u uitvoert voor toegang tot werkstroomlogboeken:

Handeling	Doel
Tabblad Acties	Bekijk alle workflows.
Selecteer de naam van de werkstroom	Filter wordt uitgevoerd op werkstroom.
Selecteer een run	Bekijk specifieke taak- en stapresultaten.
Stappen uitvouwen	Gedetailleerde logboeken weergeven.
Logboeken downloaden	Download logboeken voor offline- of teamprobleemoplossing.

Actielogboeken voor de build

Wanneer een werkstroom wordt uitgevoerd, wordt er een logboek gegenereerd met de details van wat er is gebeurd en eventuele fouten of testfouten.

Als er een fout optreedt of als een test mislukt, wordt een rode X weergegeven in plaats van een groen vinkje in de logboeken. U kunt de details van de fout bekijken om te onderzoeken wat er is gebeurd.

Schermopname van het GitHub Actions-logboek met details over een mislukte test.

Werken met artefacten

Wanneer een werkstroom iets anders produceert dan een logboekvermelding, wordt het product een artefact genoemd. De Node.js build produceert bijvoorbeeld een Docker-container die kan worden geïmplementeerd. De container is een artefact dat u kunt uploaden naar de opslag met behulp van de "actions/upload-artifact"-actie. U kunt het artefact later downloaden uit de opslag met behulp van acties/download-artefacten.

Een artefact opslaan zorgt ervoor dat het behouden blijft tussen taken. Elke taak maakt gebruik van een nieuw exemplaar van een virtuele machine, zodat u het artefact niet opnieuw kunt gebruiken door het op de virtuele machine op te slaan. Als u uw artefact in een andere taak nodig hebt, kunt u het artefact uploaden naar de opslag in de ene taak en het voor de andere taak downloaden.

Artefactopslag

Artefacten worden opgeslagen in opslagruimte op GitHub. De ruimte is gratis voor openbare opslagplaatsen en sommige opslagruimte is gratis voor privéopslagplaatsen, afhankelijk van het account. GitHub slaat uw artefacten 90 dagen op.

In het volgende werkstroomfragment ziet u dat er in de actions/upload-artifact@main actie een path kenmerk is. De waarde van dit kenmerk is het pad voor het opslaan van het artefact. In dit voorbeeld geeft u openbaar/ om alles te uploaden naar een map. Als u maar één bestand wilt uploaden, gebruikt u iets als openbaar/mytext.txt.

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

Om het artefact te downloaden voor testen, moet de build succesvol worden voltooid en het artefact worden geüpload. In de volgende code geeft u op dat de testtaak afhankelijk is van de buildtaak.

test:
    needs: build
    runs-on: ubuntu-latest

In het volgende werkstroomfragment downloadt u het artefact. Nu kan de testtaak het artefact gebruiken om te testen.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

Zie Werkstroomgegevens opslaan als artefacten voor meer informatie over het gebruik van artefacten in werkstromen.

Beoordelingen automatiseren in GitHub met behulp van werkstromen

Naast het starten van een werkstroom via GitHub-gebeurtenissen zoals push en pull-request, kunt u een werkstroom uitvoeren volgens een planning of na een gebeurtenis buiten GitHub.

Mogelijk wilt u dat een werkstroom alleen wordt uitgevoerd nadat een gebruiker een specifieke actie heeft voltooid, bijvoorbeeld nadat een revisor een pull-aanvraag goedkeurt. Voor dit scenario kunt u activeren op pull-request-review.

Een andere actie die u kunt ondernemen, is het toevoegen van een label aan de pull-aanvraag. In dit geval gebruikt u de actie pullreminders/label-when-approved-action.

Voorbeeld:

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

In het env blok stelt u de omgevingsvariabelen voor de actie in. U kunt bijvoorbeeld het aantal goedkeurders instellen dat nodig is om de werkstroom uit te voeren. In dit voorbeeld is het er een. De secrets.GITHUB_TOKEN verificatievariabele is vereist omdat de actie wijzigingen moet aanbrengen in uw opslagplaats door een label toe te voegen. Ten slotte voert u de naam in van het label dat u wilt toevoegen.

Het toevoegen van een label kan een gebeurtenis zijn die een andere werkstroom start, zoals een samenvoeging. We behandelen deze gebeurtenis in de volgende module, waarin het gebruik van continue levering in GitHub Actions wordt beschreven.

Feedback

Is deze pagina nuttig?