Hantera och felsöka arbetsflöden i GitHub Actions

10 minuter

Kom ihåg att målet är att automatisera kodgenererings- och publiceringsprocessen så att funktionerna uppdateras varje gång en utvecklare lägger till en ändring i kodbasen.

Om du vill implementera den här processen lär du dig att:

Identifiera händelsen som utlöste ett arbetsflöde.
Använd GitHub Actions-arbetsflödesloggar.
Spara och få åtkomst till byggartefakter.
Automatisera att lägga till etikett på en pull request efter granskning.

Identifiera händelsen som utlöste ett arbetsflöde

Att förstå vad som utlöste ett GitHub Actions-arbetsflöde är avgörande för felsökning, granskning och förbättring av CI/CD-pipelines. Typ av utlösare omfattar en push-överföring till en gren, en pull-begäran som skapats eller uppdaterats, ett schemalagt jobb eller en manuell sändning. Du kan identifiera utlösarhändelsen genom att undersöka arbetsflödeskörningen, lagringsplatsens ändringar och det relaterade GitHub-problemet eller pull-begäran.

Diagram som visar olika arbetsflödesutlösare i GitHub Actions, till exempel push-överföring, pull-begäran, schema och manuell sändning.

Vad är en arbetsflödesutlösare?

En arbetsflödesutlösare är en händelse som gör att ett arbetsflöde körs. GitHub stöder olika typer av utlösare, bland annat:

push eller pull_request (baserat på kodändringar)
workflow_dispatch (en manuell utlösare)
schedule (cron-jobb)
repository_dispatch (externa system)
Händelser för ärende-, diskussions- och pull-begäranden (till exempel issues.opened, pull_request.closed)

Identifiera utlösarhändelsen

Du kan identifiera en arbetsflödesutlösarhändelse på flera sätt:

Använd GitHub Actions-användargränssnittet:
1. Välj fliken Åtgärder på lagringsplatsen.
2. Välj en arbetsflödeskörning.
En händelsetyp, till exempel push, pull_requesteller workflow_dispatch, visas överst i sammanfattningen av arbetsflödeskörningen.
Använd github.event_name i loggarna eller i ett arbetsflöde.
- GitHub exponerar kontextdata under en arbetsflödeskörning. Variabeln github.event_name anger vilken händelse som utlöste arbetsflödet.
- Du kan skriva ut informationen i ett steg för felsökning:
```
-name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"
```
Använd detaljer om körning av arbetsflöde:
- Om du inspekterar arbetsflödeskörningar programmatiskt, till exempel med hjälp av ett API, innehåller körningsobjektet en egenskap event som anger utlösaren.
- Du kan hitta SHA-säker hash-algoritm, aktör och tidsstämpel för att spåra vad som föranledde utlösningen.

Härled utlösaren från lagringsplatsens effekter

Du kanske inte har direkt åtkomst till arbetsflödeskörningen, men du vill ändå härleda vad som utlöste arbetsflödeskörningen baserat på lagringsplatsens aktivitet:

Observerat beteende	Utlösarhändelse
En ny commit trycktes till `main` och arbetsflödet kördes.	`push` evenemang
En pull request öppnades eller uppdaterades.	`pull_request` evenemang
En deltagare körde ett arbetsflöde manuellt.	`workflow_dispatch`
Arbetsflödet körs dagligen vid en viss tidpunkt.	`schedule` (cron)
Arbetsflödet kördes efter ett externt tjänsteanrop.	`repository_dispatch`
Arbetsflödet kördes när en etikett eller kommentar lades till i ett problem.	`issues.*` evenemang

Genom att granska tidsstämplar, pull-begäran och commit-historik kan du ofta fastställa vilken åtgärd som fick arbetsflödet att köras.

Sammanfatta hur du identifierar vad som utlöste ett arbetsflöde:

Kontrollera sammanfattningen för arbetsflödet under fliken Åtgärder.
Skriv ut eller logga github.event_name in i arbetsflödet för synlighet.
Jämför tidsstämplar och lagringsplatsaktivitet (incheckningar, pull-begäranden, problem) för att härleda utlösaren.
Använd den fullständiga event kontexten för djupare undersökning.

Dessa metoder hjälper dig att felsöka, granska och förbättra arbetsflödets tillförlitlighet i dina utvecklings- och distributionspipelines.

Förstå en arbetsflödeseffekt genom att läsa dess konfigurationsfil

Om du vill förstå ett arbetsflödes effekter av att läsa konfigurationsfilen analyserar du strukturen och innehållet i filen som .yml lagras i .github/workflows/.

Konfigurationsfilen för arbetsflödet anger följande information om arbetsflödet:

När det körs (i avsnittet on).
Vad den gör (i jobs och steps).
Var den körs (avsnittet runs-on ).
Varför den körs (dess syfte, till exempel testning, distribution eller linting).
Hur den beter sig under specifika förhållanden (miljö, filter, logik).

Tolka en arbetsflödeseffekt

Identifiera utlösaren.

Information om vilken åtgärd som initierade arbetsflödet finns i on avsnittet i arbetsflödet.

Till exempel:
```
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:
```
Det här exempelarbetsflödet:
- Körs automatiskt när kod skickas till huvudgrenen (push).
- Körs när en pull-begäran skapas eller uppdateras (pull_request).
- Kan utlösas manuellt av en användare (workflow_dispatch).
Identifiera arbetsflödesjobben och stegen.

Information om vad arbetsflödet gör finns i avsnitten jobs och steps i arbetsflödet.

Till exempel:
```
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
```
Det här exempelarbetsflödet:
- Använder en virtuell Linux-miljö (runs-on).
- Checkar ut lagringsplatsens kod (steps>name).
- Installerar projektberoenden (steps>name).
- Kör automatiserade tester (steps>name).
Utvärdera arbetsflödets syfte och resultat.

Genom att läsa konfigurationsfilen kan du beskriva det avsedda resultatet av arbetsflödet:

"Det här arbetsflödet är en CI-pipeline (Continuous Integration). Det säkerställer att all ny kod som skickas till lagringsplatsen eller skickas via pull-begäran testas automatiskt. Om testerna misslyckas visar användargränssnittet för GitHub-arbetsflödet det här resultatet för att hjälpa dig att upprätthålla kodkvaliteten."
Identifiera eller ange valfria funktioner som påverkar hur arbetsflödet körs:
- env anger miljövariabler.
- if lägger till villkorslogik för att endast köra specifika steg när kriterierna uppfylls.
- timeout-minutes eller continue-on-error ange arbetsflödeskörning och felhantering.

Diagnostisera ett misslyckat arbetsflöde

Gå till fliken Åtgärder på lagringsplatsen.
Hitta den misslyckade körningen (anges vanligtvis med ett rött X).
Välj det misslyckade arbetsflödet för att öppna körningssammanfattningen.
Granska felet i arbetsflödesloggarna.
1. I körningssammanfattningen expanderar du varje jobb och steg tills du hittar det som indikerar fel.
2. Välj jobbet eller steget för att visa loggarna.
3. Sök efter:
  - Felmeddelanden
  - Stackspårningar
  - Utgångskoder
Ett misslyckat test kan till exempel visa npm ERR! Test failed eller exit code 1.
Kontrollera konfigurationsfilen för arbetsflödet.

.yml Använd filen för att fastställa:
- Vad försökte varje steg göra?
- Om det finns miljövariabler (env) eller villkor (if) som påverkar exekveringen.
- Om felet beror på ett beroende som saknas, ett syntaxfel eller ett felkonfigurerat steg.
Om ett steg misslyckas kontrollerar du följande orsaker:
- Installerades beroenden i föregående steg?
- Finns testfiler och skickas lokalt?

Vanliga felscenarier

I följande tabell beskrivs vanliga scenarier med arbetsflödesfel:

Symtom	Sannolik orsak
Ett steg misslyckas och returnerar `command not found`l	Beroende saknas eller fel konfiguration
`npm install` Misslyckas.	Skadad `package-lock.json` fil eller ett nätverksproblem
Ett teststeg misslyckas	Problem med enhetstest, saknade konfigurationsfiler eller ogiltig testsyntax
`Permission denied` visas.	Felaktiga filbehörigheter eller hemligheter som saknas

Identifiera hur du kommer åt arbetsflödesloggar i GitHub

Gå till fliken Åtgärder på lagringsplatsen.
I listan över arbetsflöden väljer du det relevanta arbetsflödet.

Om .yml filen till exempel har följande kod visas en länk med namnet CI Workflow i listan:
```
name: CI Workflow
```
Välj ett specifikt lopp

I listan över körningar som visar status väljer du tidsstämpeln eller incheckningsmeddelandet för den specifika körning som du vill inspektera.
Expandera varje jobb och steg.

Körningssammanfattningssidan visar jobb som de definieras i arbetsflödesfilen, till exempel build eller test:
1. Välj ett jobb för att expandera det.
2. I jobbet expanderar du enskilda steg, till exempel "Installera beroenden" eller "Kör tester".
Visa loggutdata.

Om du vill visa fullständiga loggutdata, inklusive konsolloggar, felmeddelanden och felsökningsinformation, väljer du ett arbetsflödessteg. Du kan kopiera, söka efter och ladda ned loggarna.

I följande tabell sammanfattas de steg du vidtar för att komma åt arbetsflödesloggar:

Åtgärd	Avsikt
Fliken Åtgärder	Visa alla arbetsflödeskörningar.
Välj arbetsflödets namn	Filtrera körningar efter arbetsflöde.
Välj en körning	Se specifika jobb och stegresultat.
Expandera stegen	Visa detaljerade loggar.
Ladda ned loggar	Ladda ned loggar för offline- eller teamfelsökning.

Åtgärdsloggar för bygget

När ett arbetsflöde körs skapas en logg som innehåller information om vad som hände och eventuella fel eller testfel.

Om ett fel uppstår eller om ett test misslyckas visas ett rött X i stället för en grön bockmarkering i loggarna. Du kan granska detaljerna om felet eller misslyckandet för att undersöka vad som hände.

Skärmbild av GitHub Actions-loggen med information om ett misslyckat test.

Arbeta med artefakter

När ett arbetsflöde skapar något annat än en loggpost kallas produkten för en artefakt. Till exempel skapar Node.js-versionen en Docker-container som kan distribueras. Containern är en artefakt som du kan ladda upp till lagring med hjälp av åtgärden actions/upload-artifact . Du kan senare ladda ned artefakten från lagringen med hjälp av åtgärder/download-artifact.

Om du lagrar en artefakt bevaras den mellan jobb. Varje jobb använder en ny instans av en virtuell dator, så du kan inte återanvända artefakten genom att spara den på den virtuella datorn. Om du behöver artefakten i ett annat jobb kan du ladda upp artefakten till lagring i ett jobb och ladda ned den för det andra jobbet.

Artefaktförvaring

Artefakter lagras i lagringsutrymme på GitHub. Utrymmet är kostnadsfritt för offentliga lagringsplatser och en del lagringsutrymme är kostnadsfritt för privata lagringsplatser, beroende på kontot. GitHub lagrar dina artefakter i 90 dagar.

Observera i följande arbetsflödesfragment att det finns ett attribut actions/upload-artifact@main i path-åtgärden. Värdet för det här attributet är sökvägen för att lagra artefakten. I det här exemplet anger du public/ för att ladda upp allt till en katalog. Om du bara vill ladda upp en enda fil, använder du något som public/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 du vill ladda ned artefakten för testning måste bygget slutföras och ladda upp artefakten. I följande kod anger du att testjobbet är beroende av byggjobbet.

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

I följande arbetsflödesfragment laddar du ned artefakten. Nu kan testjobbet använda artefakten för testning.

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

Mer information om hur du använder artefakter i arbetsflöden finns i Lagra arbetsflödesdata som artefakter.

Automatisera granskningar i GitHub med hjälp av arbetsflöden

Förutom att starta ett arbetsflöde via GitHub-händelser som push och pull-requestkan du köra ett arbetsflöde enligt ett schema eller efter en händelse utanför GitHub.

Du kanske bara vill att ett arbetsflöde ska köras när en användare har slutfört en viss åtgärd, till exempel efter att en granskare har godkänt en pull-begäran. I det här scenariot kan du utlösa på pull-request-review.

En annan åtgärd du kan vidta är att lägga till en etikett i pull-begäran. I det här fallet använder du åtgärden pullreminders/label-when-approved-action.

Till exempel:

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

I blocket env anger du miljövariablerna för åtgärden. Du kan till exempel ange det antal godkännare som krävs för att köra arbetsflödet. I det här exemplet är det ett. Variabeln secrets.GITHUB_TOKEN autentisering krävs eftersom åtgärden måste göra ändringar i lagringsplatsen genom att lägga till en etikett. Slutligen anger du namnet på etiketten som ska läggas till.

Att lägga till en etikett kan vara en händelse som startar ett annat arbetsflöde, till exempel en sammanslagning. Vi går igenom den här händelsen i nästa modul, som beskriver hur du använder kontinuerlig leverans i GitHub Actions.

Feedback

Var den här sidan till hjälp?