Een aangepaste GitHub-actie maken

  • 8 minuten

GitHub Actions is een krachtige functie waarmee u van code naar de cloud kunt gaan, allemaal vanuit het comfort en gemak van uw eigen opslagplaats. Hier vindt u informatie over de verschillende typen GitHub-acties en de metagegevens, syntaxis en werkstroomopdrachten voor het maken van aangepaste GitHub-acties.

Typen GitHub-acties

Diagram met de drie typen GitHub Actions; Acties voor docker-, JavaScript- en samengestelde uitvoeringsstappen.

Acties zijn afzonderlijke taken die u kunt gebruiken om uw ontwikkelwerkstromen aan te passen. U kunt uw eigen acties maken door aangepaste code te schrijven die communiceert met uw opslagplaats om aangepaste taken uit te voeren of door acties te gebruiken die door de GitHub-communityshares worden gedeeld. Als u door verschillende acties navigeert, ziet u dat er drie verschillende soorten acties zijn: Docker-containeracties, JavaScript-acties en acties voor samengestelde uitvoeringsstappen. Laten we elk actietype nader bekijken.

Docker-containeracties

Docker-containers verpakken de omgeving met de GitHub Actions-code. Dit betekent dat de actie wordt uitgevoerd in een consistente en betrouwbare omgeving, omdat alle afhankelijkheden zich binnen die container bevinden. Als de actie moet worden uitgevoerd in een specifieke omgevingsconfiguratie, zijn Docker-containers een goede manier om te gaan, omdat u het besturingssysteem en hulpprogramma's kunt aanpassen. Het nadeel is dat omdat de taak de container moet bouwen en ophalen, Docker-containeracties vaak trager zijn dan JavaScript-acties.

Voordat u een Docker-containeractie bouwt, moet u enige basiskennis hebben van het gebruik van omgevingsvariabelen en het Docker-containerbestandssysteem. De stappen die u moet uitvoeren om een Docker-containeractie te bouwen, zijn vervolgens minimaal en eenvoudig:

  1. Maak een Dockerfile opdracht om de opdrachten te definiëren voor het samenstellen van de Docker-installatiekopieën.
  2. Maak een action.yml metagegevensbestand om de invoer en uitvoer van de actie te definiëren. Stel de runs: using: waarde docker in op en de runs: image: waarde Dockerfile in het bestand.
  3. Maak een entrypoint.sh bestand om de docker-installatiekopieën te beschrijven.
  4. Voer uw actie door naar GitHub en push deze met de volgende bestanden: action.yml, entrypoint.sh, Dockerfileen README.md.

JavaScript-acties

JavaScript-acties kunnen rechtstreeks op de runner-machine worden uitgevoerd en de actiecode scheiden van de omgeving die wordt gebruikt om de actie uit te voeren. Hierdoor wordt de actiecode vereenvoudigd en kan deze sneller worden uitgevoerd dan acties binnen een Docker-container.

Als vereiste voor het maken en gebruiken van verpakte JavaScript-acties moet u Node.js downloaden, waaronder npm. Als een optionele stap (maar een die we aanbevelen) is om GitHub Actions Toolkit Node.js te gebruiken. Dit is een verzameling Node.js pakketten waarmee u snel JavaScript-acties kunt bouwen met meer consistentie.

De stappen voor het bouwen van een JavaScript-actie zijn minimaal en eenvoudig:

  1. Maak een action.yml metagegevensbestand om de invoer en uitvoer van de actie te definiëren en laat de actieloper weten hoe deze JavaScript-actie moet worden uitgevoerd.
  2. Maak een index.js bestand met contextinformatie over de Toolkit-pakketten, routering en andere functies van de actie.
  3. Voer uw actie door en push deze naar GitHub met de volgende bestanden: action.yml, , index.jsnode_modules, package.json, , package-lock.jsonen README.md.

Acties voor stappen voor samengestelde uitvoering

Met acties voor samengestelde uitvoeringsstappen kunt u acties opnieuw gebruiken met behulp van shellscripts. U kunt zelfs meerdere shelltalen combineren binnen dezelfde actie. Als u veel shellscripts hebt om verschillende taken te automatiseren, kunt u deze nu eenvoudig omzetten in een actie en ze opnieuw gebruiken voor verschillende werkstromen. Soms is het eenvoudiger om alleen een shellscript te schrijven dan javaScript te gebruiken of uw code in een Docker-container te verpakken.

Metagegevens en syntaxis die nodig zijn om een actie te maken

Bij het maken of controleren van een GitHub-actie is een goede eerste stap het controleren van het action.yml bestand om te beoordelen welke invoer, uitvoer, beschrijving, uitvoeringen en andere configuratie-informatie de actie nodig heeft. Sommige van deze parameters zijn vereist, terwijl andere optioneel zijn. Het action.yml bestand definieert de volgende informatie over uw actie:

Parameter Omschrijving Vereist
Naam De naam van uw actie. Hiermee kunt u de actie in een taak visueel identificeren. ja
Beschrijving Een samenvatting van wat uw actie doet. ja
Invoerwaarden Met invoerparameters kunt u gegevens opgeven die de actie tijdens runtime verwacht te gebruiken. Deze parameters worden omgevingsvariabelen in de runner. nee
Uitvoerwaarden Met uitvoerparameters kunt u gegevens opgeven die volgende acties later in de werkstroom kunnen gebruiken nadat de actie die deze uitvoer definieert, is uitgevoerd. nee
Uitvoerbewerkingen De opdracht die moet worden uitgevoerd wanneer de actie wordt uitgevoerd. ja
Branding Het kleuren- en featherpictogram dat u kunt gebruiken om een badge te maken om uw actie aan te passen en te onderscheiden in GitHub Marketplace. nee

Invoerwaarden

Invoer zijn de parameters waarmee u gegevens kunt opgeven die de actie verwacht te gebruiken tijdens de runtime. GitHub slaat deze invoerparameters op als omgevingsvariabelen.

Hieronder volgt een voorbeeld van een lijst met invoer voor een actie. De firstNameStudent invoer is optioneel, terwijl de studentGrade invoer is vereist.

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

Uitvoerwaarden

Uitvoer zijn de parameters waarmee u gegevens kunt declareren. Houd er rekening mee dat acties die later in een werkstroom worden uitgevoerd, de uitvoergegevens kunnen gebruiken die zijn gedeclareerd in een eerder uitgevoerde actie.

Het volgende voorbeeld is een eenvoudige uitvoer om het gemiddelde cijfer van de leerlingen/studenten te declareren:

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

Uitvoerbewerkingen

Zoals u eerder hebt geleerd, moet uw actie een runs instructie hebben waarmee de opdracht wordt gedefinieerd die nodig is om uw actie uit te voeren. Afhankelijk van hoe u uw actie maakt, of u nu een Docker-container, JavaScript of samengestelde uitvoeringsstappen gebruikt, wordt de runs syntaxis anders gedefinieerd.

runs voor Docker-acties

Voor Docker-containeracties is de runs instructie vereist om de installatiekopie te configureren die door de Docker-actie wordt gebruikt met de volgende argumenten:

  • using: Moet worden ingesteld om een Docker-containeractie uit te docker voeren
  • image: Docker-installatiekopieën die worden gebruikt als container om de actie uit te voeren
runs:
  using: 'docker'
  image: 'Dockerfile'

runs voor JavaScript-acties

Voor JavaScript-acties moet de runs instructie de volgende twee argumenten hebben:

  • using: De toepassing die wordt gebruikt om de code uit te voeren zoals gedefinieerd in main
  • main: Bestand dat de actiecode bevat; de toepassing die is gedefinieerd in using het uitvoeren van dit bestand

Hier volgt bijvoorbeeld een runs instructie voor een JavaScript-actie met behulp van Node.js:

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

runs voor acties voor stappen voor samengestelde uitvoeringen

Voor acties voor samengestelde uitvoeringsstappen is vereist dat de runs instructie de volgende drie argumenten uitvoert:

  • using: moet worden ingesteld om een samengestelde uitvoeringsstap uit te "composite" voeren
  • steps: Stappen uitvoeren om de actie uit te voeren
  • steps[*].run: Opdracht die u wilt uitvoeren (kan inline of een script in uw actieopslagplaats zijn)

Hier volgt bijvoorbeeld een runs instructie voor een actie voor samengestelde uitvoeringsstappen waarmee het script wordt uitgevoerd op filepath /test/script/sh:

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

Branding

Een optionele maar leuke functie is de mogelijkheid om de badge van uw actie aan te passen. De badge wordt weergegeven naast de actienaam in GitHub Marketplace. U kunt een kleuren- en featherpictogram gebruiken om de badge te maken. Voor huisstijl moet u het pictogram en de kleur opgeven die u wilt gebruiken.

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

Hier volgt een voorbeeld van een actiebadge uitchecken op de GitHub Marketplace:

Schermopname van de huisstijl van een actie op de GitHub Marketplace.

Werkstroomopdrachten

Het maken van een werkstroom is vrij eenvoudig zolang u de juiste acties voor uw stappen kunt vinden. In sommige gevallen moet u mogelijk uw eigen acties maken om uw gewenste resultaten te bereiken, maar u kunt werkstroomopdrachten gebruiken om een ander aanpassingsniveau aan uw werkstromen toe te voegen.

Met werkstroomopdrachten kunt u communiceren met de GitHub Actions runner-machine door opgemaakte tekstregels naar de console af te drukken. U kunt deze werkstroomopdrachten gebruiken met shellopdrachten of binnen uw aangepaste acties. Werkstroomopdrachten zijn handig omdat u hiermee informatie kunt delen tussen werkstroomstappen, foutopsporing of foutberichten kunt afdrukken naar de console, omgevingsvariabelen kunt instellen, uitvoerparameters kunt instellen of aan het systeempad kunt toevoegen.

De meeste werkstroomopdrachten gebruiken de echo opdracht in de volgende specifieke indeling, terwijl anderen kunnen worden aangeroepen door naar een bestand te schrijven:

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

Hieronder volgen enkele eenvoudige voorbeelden van berichtenlogboekregistratie voor het afdrukken van een foutopsporingsbericht, informatiebericht, foutbericht of waarschuwingsbericht naar de console:

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

U kunt ook een bericht maken om af te drukken naar het logboek met een bestandsnaam (bestand), regelnummer (lijn) en kolomnummer (kolom) waar de fout is opgetreden. Waarschuwingsberichten worden weergegeven in een gele markering met de tekst 'waarschuwing' en foutberichten worden in een rode markering weergegeven met de tekst 'fout'.

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

Het is belangrijk om te weten dat deze werkstroomopdrachten op één regel moeten staan. Tekens die interfereren met parseren, zoals komma's en regeleinden, moeten url-gecodeerd zijn.

De volgende tekst is bijvoorbeeld een bericht met meerdere regels:

This text spans
across multiple lines

Dit bericht moet worden gecodeerd zoals hier wordt weergegeven:

This text spans%0Aacross multiple lines

Naast werkstroomopdrachten kunt u afsluitcodes instellen om de status van een actie in te stellen. Dit is belangrijk omdat wanneer u met taken in een werkstroom werkt, een mislukte afsluitcode alle gelijktijdige acties stopt en toekomstige acties annuleert. Als u een JavaScript-actie maakt, kunt u het pakket acties-toolkit @actions/core gebruiken om een bericht te registreren en een afsluitcode voor fouten in te stellen. Als u een Docker-containeractie maakt, kunt u een afsluitcode voor fouten instellen in uw entrypoint.sh script.