Skapa en anpassad GitHub-åtgärd

  • 8 minuter

GitHub Actions är en kraftfull funktion som hjälper dig att gå från kod till molnet, allt från bekvämlighet och bekvämlighet för din egen lagringsplats. Här får du lära dig mer om de olika typerna av GitHub-åtgärder och kommandona för metadata, syntax och arbetsflöde för att skapa anpassade GitHub-åtgärder.

Typer av GitHub-åtgärder

Diagram som visar de tre typerna av GitHub Actions; Åtgärder för Docker, JavaScript och sammansatta körningssteg.

Åtgärder är enskilda uppgifter som du kan använda för att anpassa dina utvecklingsarbetsflöden. Du kan skapa egna åtgärder genom att skriva anpassad kod som interagerar med lagringsplatsen för att utföra anpassade uppgifter eller genom att använda åtgärder som GitHub-communityresurserna utför. Om du går igenom olika åtgärder ser du att det finns tre olika typer av åtgärder: Docker-containeråtgärder, JavaScript-åtgärder och åtgärder för sammansatta körningssteg. Låt oss ta en närmare titt på varje åtgärdstyp.

Docker-containeråtgärder

Docker-containrar paketera miljön med GitHub Actions-koden. Det innebär att åtgärden körs i en konsekvent och tillförlitlig miljö eftersom alla dess beroenden finns i containern. Om åtgärden behöver köras i en specifik miljökonfiguration är Docker-containrar ett bra sätt att gå eftersom du kan anpassa operativsystemet och verktygen. Nackdelen är att eftersom jobbet måste skapa och hämta containern är Docker-containeråtgärder ofta långsammare än JavaScript-åtgärder.

Innan du skapar en Docker-containeråtgärd bör du ha viss grundläggande förståelse för hur du använder miljövariabler och Docker-containerfilsystemet. Stegen för att skapa en Docker-containeråtgärd är sedan minimala och enkla:

  1. Skapa en Dockerfile för att definiera kommandona för att montera Docker-avbildningen.
  2. Skapa en action.yml metadatafil för att definiera indata och utdata för åtgärden. Ange värdet runs: using: till docker och värdet runs: image: till Dockerfile i filen.
  3. Skapa en entrypoint.sh fil för att beskriva docker-avbildningen.
  4. Checka in och skicka åtgärden till GitHub med följande filer: action.yml, entrypoint.sh, Dockerfileoch README.md.

JavaScript-åtgärder

JavaScript-åtgärder kan köras direkt på löpardatorn och separera åtgärdskoden från miljön som används för att köra åtgärden. Därför förenklas åtgärdskoden och kan köras snabbare än åtgärder i en Docker-container.

Som en förutsättning för att skapa och använda paketerade JavaScript-åtgärder måste du ladda ned Node.js, som innehåller npm. Som ett valfritt steg (men ett som vi rekommenderar) är att använda GitHub Actions Toolkit Node.js, vilket är en samling Node.js paket som gör att du snabbt kan skapa JavaScript-åtgärder med mer konsekvens.

Stegen för att skapa en JavaScript-åtgärd är minimala och enkla:

  1. Skapa en action.yml metadatafil för att definiera indata och utdata för åtgärden, samt berätta för åtgärdslöparen hur du börjar köra den här JavaScript-åtgärden.
  2. Skapa en index.js fil med kontextinformation om Verktygspaket, routning och andra funktioner i åtgärden.
  3. Checka in och skicka åtgärden till GitHub med följande filer: action.yml, index.js, node_modules, package.json, package-lock.jsonoch README.md.

Åtgärder för sammansatta körningssteg

Med åtgärder för sammansatta körningssteg kan du återanvända åtgärder med hjälp av shell-skript. Du kan till och med blanda flera gränssnittsspråk i samma åtgärd. Om du har många shell-skript för att automatisera flera uppgifter kan du nu enkelt omvandla dem till en åtgärd och återanvända dem för olika arbetsflöden. Ibland är det enklare att bara skriva ett gränssnittsskript än att använda JavaScript eller omsluta koden i en Docker-container.

Metadata och syntax som behövs för att skapa en åtgärd

När du skapar eller granskar en GitHub-åtgärd är ett bra första steg att granska action.yml filen för att utvärdera vilka indata, utdata, beskrivning, körningar och annan konfigurationsinformation som åtgärden behöver. Vissa av dessa parametrar krävs, medan andra är valfria. Filen action.yml definierar följande information om din åtgärd:

Parameter Beskrivning Obligatoriskt
Name Namnet på din åtgärd. Hjälper till att visuellt identifiera åtgärden i ett jobb. ja
beskrivning En sammanfattning av vad din åtgärd gör. ja
Indata Med indataparametrar kan du ange data som åtgärden förväntar sig att använda under körningen. Dessa parametrar blir miljövariabler i löparen. nej
Utdata Med utdataparametrar kan du ange data som efterföljande åtgärder kan använda senare i arbetsflödet efter att åtgärden som definierar dessa utdata har körts. nej
Körningar Kommandot som ska köras när åtgärden körs. ja
Profilering Färg- och fjäderikonen som ska användas för att skapa ett märke för att anpassa och särskilja din åtgärd på GitHub Marketplace. nej

Indata

Indata är de parametrar som gör att du kan ange data som åtgärden förväntar sig att använda under körningen. GitHub lagrar dessa indataparametrar som miljövariabler.

Följande är ett exempel på en lista över indata för en åtgärd. Indata firstNameStudent är valfria, medan indata studentGrade krävs.

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

Utdata

Utdata är de parametrar som gör att du kan deklarera data. Tänk på att åtgärder som körs senare i ett arbetsflöde kan använda utdata som deklarerades i en tidigare körningsåtgärd.

Följande exempel är ett enkelt utdata för att deklarera elevernas genomsnittliga betyg:

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

Körningar

Som du lärde dig tidigare måste åtgärden ha en runs instruktion som definierar det kommando som krävs för att utföra åtgärden. Beroende på hur du skapar din åtgärd – oavsett om du använder en Docker-container, JavaScript eller sammansatta körningssteg – definieras syntaxen runs på olika sätt.

runs för Docker-åtgärder

Docker-containeråtgärder kräver instruktionen runs för att konfigurera avbildningen som Docker-åtgärden använder med följande argument:

  • using: Måste anges till för att docker köra en Docker-containeråtgärd
  • image: Docker-avbildning som används som container för att köra åtgärden
runs:
  using: 'docker'
  image: 'Dockerfile'

runs för JavaScript-åtgärder

JavaScript-åtgärder kräver att instruktionen runs använder följande två argument:

  • using: Program som används för att köra koden enligt definitionen i main
  • main: Fil som innehåller åtgärdskoden; programmet som definierats i using kör den här filen

Här är till exempel en runs instruktion för en JavaScript-åtgärd med hjälp av Node.js:

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

runs för åtgärder för sammansatta körningssteg

Åtgärder för sammansatta körningssteg kräver att instruktionen runs använder följande tre argument:

  • using: Måste anges till för att "composite" köra ett sammansatt körningssteg
  • steps: Kör stegen för att köra åtgärden
  • steps[*].run: Kommando som du vill köra (kan vara infogat eller ett skript i din åtgärdslagringsplats)

Här är till exempel en runs instruktion för en åtgärd för sammansatta körningssteg som kör skriptet på filepath /test/script/sh:

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

Profilering

En valfri men rolig funktion är möjligheten att anpassa märket för din åtgärd. Märket visas bredvid åtgärdsnamnet på GitHub Marketplace. Du kan använda en färg- och fjäderikon för att skapa märket. För varumärkesanpassning måste du ange den ikon och färg som du vill använda.

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

Här är ett exempel på ett checkout-åtgärdsmärke på GitHub Marketplace:

Skärmbild som visar en åtgärds varumärkesanpassning på GitHub Marketplace.

Arbetsflödeskommandon

Det är ganska enkelt att skapa ett arbetsflöde så länge du kan hitta rätt åtgärder för dina steg. I vissa fall kan du behöva skapa egna åtgärder för att uppnå önskade resultat, men du kan använda arbetsflödeskommandon för att lägga till ytterligare en anpassningsnivå i dina arbetsflöden.

Med arbetsflödeskommandon kan du kommunicera med GitHub Actions-löpardatorn genom att skriva ut formaterade textrader till konsolen. Du kan använda dessa arbetsflödeskommandon med gränssnittskommandon eller i dina anpassade åtgärder. Arbetsflödeskommandon är användbara eftersom du kan dela information mellan arbetsflödessteg, skriva ut felsökningsmeddelanden eller felmeddelanden till konsolen, ange miljövariabler, ange utdataparametrar eller lägga till i systemsökvägen.

De flesta arbetsflödeskommandon echo använder kommandot i följande specifika format, medan andra kan anropas genom att skriva till en fil:

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

Här följer några grundläggande exempel på meddelandeloggning för att skriva ut ett felsökningsmeddelande, informationsmeddelande, felmeddelande eller varningsmeddelande till konsolen:

- 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 också skapa ett meddelande för att skriva ut till loggen med ett filnamn (fil), radnummer (rad) och kolumnnummer (kol) där felet inträffade. Varningsmeddelanden visas i en gul markering med texten "varning" och felmeddelanden visas i en röd markering med texten "fel".

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

Observera att dessa arbetsflödeskommandon måste finnas på en enda rad. Tecken som stör parsning, till exempel kommatecken och radbrytningar, måste vara URL-kodade.

Följande text är till exempel ett flerradsmeddelande:

This text spans
across multiple lines

Det här meddelandet ska kodas enligt följande:

This text spans%0Aacross multiple lines

Förutom arbetsflödeskommandon kan du ange slutkoder för att ange status för en åtgärd. Det här är viktigt eftersom när du arbetar med jobb i ett arbetsflöde stoppar en misslyckad slutkod alla samtidiga åtgärder och avbryter eventuella framtida åtgärder. Om du skapar en JavaScript-åtgärd kan du använda åtgärdsverktygspaketet @actions/core för att logga ett meddelande och ange en felslutskod. Om du skapar en Docker-containeråtgärd kan du ange en slutkod för fel i entrypoint.sh skriptet.