Opret en brugerdefineret GitHub-handling

Fuldført

GitHub Actions er en effektiv funktion, der hjælper dig med at gå fra kode til cloud– alt sammen fra komfort og bekvemmelighed i dit eget lager. Her får du mere at vide om de forskellige typer GitHub-handlinger og metadata, syntaks og arbejdsproceskommandoer til oprettelse af brugerdefinerede GitHub-handlinger.

Typer af GitHub-handlinger

Handlinger er individuelle opgaver, som du kan bruge til at tilpasse dine udviklingsarbejdsprocesser. Du kan oprette dine egne handlinger ved at skrive brugerdefineret kode, der interagerer med dit lager for at udføre brugerdefinerede opgaver, eller ved hjælp af handlinger, som GitHub-communityshares. Når du navigerer gennem forskellige handlinger, kan du se, at der er tre forskellige typer handlinger: handlinger Docker-objektbeholderhandlinger, JavaScript-handlingerog handlinger for sammensatte kørselstrin. Lad os se nærmere på hver handlingstype.

Handlinger for dockerobjektbeholder

Docker-objektbeholdere pakker miljøet med GitHub-handlingskoden. Det betyder, at handlingen kører i et konsistent og pålideligt miljø, fordi alle dens afhængigheder er i den pågældende objektbeholder. Hvis handlingen skal køre i en bestemt miljøkonfiguration, er Docker-objektbeholdere en god måde at gøre det på, fordi du kan tilpasse operativsystemet og værktøjerne. Ulempen er, at fordi jobbet skal bygge og hente objektbeholderen, er Docker-objektbeholderhandlinger ofte langsommere end JavaScript-handlinger.

Før du bygger en Docker-objektbeholderhandling, skal du have en grundlæggende forståelse af, hvordan du bruger miljøvariabler og Docker-objektbeholderfilsystemet. De trin, du skal udføre for at bygge en Docker-objektbeholderhandling, er derefter minimale og ligetil:

1. Opret en Dockerfile for at definere kommandoerne til at samle Docker-billedet.
2. Opret en action.yml metadatafil for at definere input og output for handlingen. Angiv den runs: using: værdi til docker og den runs: image: værdi, der skal Dockerfile i filen.
3. Opret en entrypoint.sh fil for at beskrive dockerbilledet.
4. Bekræft og send din handling til GitHub med følgende filer: action.yml, entrypoint.sh, Dockerfileog README.md.

JavaScript-handlinger

JavaScript-handlinger kan køre direkte på løbercomputeren og adskille handlingskoden fra det miljø, der bruges til at køre handlingen. Derfor forenkles handlingskoden, og den kan udføres hurtigere end handlinger i en Docker-objektbeholder.

Som en forudsætning for at oprette og bruge pakkede JavaScript-handlinger skal du downloade Node.js, som omfatter npm. Som et valgfrit trin (men et, vi anbefaler) er at bruge GitHub Actions Toolkit Node.js, som er en samling af Node.js pakker, der giver dig mulighed for hurtigt at bygge JavaScript-handlinger med mere ensartethed.

Trinnene til oprettelse af en JavaScript-handling er minimale og ligetil:

1. Opret en action.yml metadatafil for at definere input og output for handlingen, og fortæl handlingsløberen, hvordan denne JavaScript-handling skal starte.
2. Opret en index.js fil med kontekstoplysninger om Toolkit-pakker, routing og andre funktioner i handlingen.
3. Send din handling til GitHub med følgende filer: action.yml, index.js, node_modules, package.json, package-lock.jsonog README.md.

Handlinger for sammensatte kørselstrin

Handlinger for sammensatte kørselstrin giver dig mulighed for at genbruge handlinger ved hjælp af shellscripts. Du kan endda blande flere shellsprog i den samme handling. Hvis du har mange shellscripts til at automatisere flere opgaver, kan du nu nemt omdanne dem til en handling og genbruge dem til forskellige arbejdsprocesser. Nogle gange er det nemmere blot at skrive et shellscript end at bruge JavaScript eller ombryde din kode i en Docker-objektbeholder.

Metadata og syntaks, der er nødvendige for at oprette en handling

Når du opretter eller gennemser en GitHub-handling, er et godt første skridt at gennemse action.yml-filen for at vurdere, hvilke input, output, beskrivelse, kørsler og andre konfigurationsoplysninger handlingen har brug for. Nogle af disse parametre er påkrævet, mens andre er valgfrie. Filen action.yml definerer følgende oplysninger om handlingen:

Parameter	Beskrivelse	Kræves
Navn	Navnet på din handling. Hjælper med visuelt at identificere handlingen i et job.	Ja
Beskrivelse	En oversigt over, hvad din handling gør.	Ja
Indgange	Inputparametre gør det muligt for dig at angive data, som handlingen forventer at bruge under kørsel. Disse parametre bliver miljøvariabler i løberen.	Nej
Udgange	Outputparametre giver dig mulighed for at angive data, som efterfølgende handlinger kan bruge senere i arbejdsprocessen, når den handling, der definerer disse output, er kørt.	Nej
Kører	Den kommando, der skal køres, når handlingen udføres.	Ja
Branding	Farve- og fjerikon, der skal bruges til at oprette et badge for at tilpasse og skelne mellem din handling på GitHub Marketplace.	Nej

Indgange

Input er de parametre, der giver dig mulighed for at angive data, som handlingen forventer at bruge under kørslen. GitHub gemmer disse inputparametre som miljøvariabler.

Følgende er et eksempel på en liste over input for en handling. Det firstNameStudent input er valgfrit, mens det studentGrade input er påkrævet.

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

Udgange

Output er de parametre, der giver dig mulighed for at deklarere data. Vær opmærksom på, at handlinger, der kører senere i en arbejdsproces, kan bruge de outputdata, der blev erklæret i en tidligere kørselshandling.

Følgende eksempel er et simpelt output til at deklarere den gennemsnitlige karakter for de studerende:

outputs:
  average:
    description: 'The average grade of the students'

Kører

Som du har lært tidligere, skal din handling have en runs sætning, der definerer den kommando, der er nødvendig for at udføre handlingen. Afhængigt af hvordan du opretter din handling – uanset om du bruger en Docker-objektbeholder, JavaScript eller sammensatte kørselstrin – defineres runs-syntaksen forskelligt.

runs til Docker-handlinger

Handlinger i Docker-objektbeholdere kræver runs-sætningen for at konfigurere det billede, som Docker-handlingen bruger med følgende argumenter:

• using: Skal angives til docker for at køre en Docker-objektbeholderhandling.
• image: Docker-billede, der bruges som objektbeholder til at køre handlingen.

runs:
  using: 'docker'
  image: 'Dockerfile'

runs til JavaScript-handlinger

JavaScript-handlinger kræver, at runs-sætningen tager følgende to argumenter:

• using: Program, der bruges til at udføre koden som defineret i main.
• main: Fil, der indeholder handlingskoden. programmet, der er defineret i using, udfører denne fil.

Her er f.eks. en runs sætning for en JavaScript-handling ved hjælp af Node.js:

runs:
  using: 'node12'
  main: 'main.js'

runs handlinger for sammensatte kørselstrin

Handlinger for sammensatte kørselstrin kræver, at runs-sætningen har følgende tre argumenter:

• using: Skal angives til "composite" for at køre et sammensat kørselstrin.
• steps: Kør trin for at køre handlingen.
• steps[*].run: Den kommando, du vil køre (kan være indbygget eller et script i dit handlingslager).

Her er f.eks. en runs sætning for en handling for sammensatte kørselstrin, der kører scriptet på filepath /test/script/sh:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Branding

En valgfri, men sjov funktion er muligheden for at tilpasse badget for din handling. Badget vises ud for handlingsnavnet i GitHub Marketplace. Du kan bruge en farve og ikonet Fjer til at oprette badgen. I forbindelse med branding skal du angive det ikon og den farve, du vil bruge.

branding:
  icon: 'shield'  
  color: 'blue'

Her er et eksempel på et badge for handlingen Udtjekning på GitHub Marketplace:

Arbejdsproceskommandoer

Det er ret ligetil at oprette en arbejdsproces, så længe du kan finde de rette handlinger til dine trin. I nogle tilfælde skal du muligvis oprette dine egne handlinger for at opnå de ønskede resultater, men du kan bruge arbejdsproceskommandoer til at føje endnu et tilpasningsniveau til dine arbejdsprocesser.

Med arbejdsproceskommandoer kan du kommunikere med gitHub-handlingsløbercomputeren ved at udskrive formaterede tekstlinjer i konsollen. Du kan bruge disse arbejdsproceskommandoer med shellkommandoer eller i dine brugerdefinerede handlinger. Arbejdsproceskommandoer er nyttige, fordi de giver dig mulighed for at dele oplysninger mellem arbejdsprocestrin, udskrive fejlfinding eller fejlmeddelelser i konsollen, angive miljøvariabler, angive outputparametre eller føje til systemstien.

De fleste arbejdsproceskommandoer bruger kommandoen echo i følgende specifikke format, mens andre kan aktiveres ved at skrive til en fil:

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Følgende er nogle grundlæggende eksempler på logføring af meddelelser i forbindelse med udskrivning af en fejlfindingsmeddelelse, en oplysningsmeddelelse, en fejlmeddelelse eller en advarselsmeddelelse til konsollen:

- name: workflow commands logging messages
  run: |
    echo "::debug::This is a debug message"
    echo "This is an info message"
    echo "::error::This is an error message"
    echo "::warning::This is a warning message"

Du kan også oprette en meddelelse, der skal udskrives i logfilen med et filnavn (fil), linjenummer (linje) og kolonnenummer (col), hvor fejlen opstod. Advarselsmeddelelser vises i en gul fremhævning med teksten "advarsel", og fejlmeddelelser vises i en rød fremhævning med teksten "fejl".

echo "::error file=app.js,line=10,col=15::Something went wrong"

Det er vigtigt at bemærke, at disse arbejdsproceskommandoer skal være på en enkelt linje. Tegn, der forstyrrer fortolkning, f.eks. kommaer og linjeskift, skal være URL-kodet.

Følgende tekst er f.eks. en meddelelse med flere linjer:

This text spans
across multiple lines

Denne meddelelse skal kodes som vist her:

This text spans%0Aacross multiple lines

Ud over arbejdsproceskommandoer kan du angive afslutningskoder for at angive status for en handling. Dette er vigtigt, fordi når du arbejder med job i en arbejdsproces, stopper en mislykket afslutningskode alle samtidige handlinger og annullerer eventuelle fremtidige handlinger. Hvis du opretter en JavaScript-handling, kan du bruge handlingsværktøjspakken @actions/core pakke til at logge en meddelelse og angive en fejlafslutningskode. Hvis du opretter en Docker-objektbeholderhandling, kan du angive en fejlafslutningskode i dit entrypoint.sh script.