Uw werkstroom aanpassen met omgevingsvariabelen

  • 8 minuten

In deze les leert u hoe u omgevingsspecifiek gedrag configureert en beheert met behulp van variabelen, contexten en aangepaste scripts in GitHub Actions-werkstromen.

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

  • Gebruik standaard- en aangepaste omgevingsvariabelen.
  • Toegang tot contextuele informatie in werkstromen.
  • Stel omgevingsvariabelen in op verschillende werkstroombereiken.
  • Gebruik aangepaste scripts met het trefwoord Uitvoeren.
  • Omgevingsbeveiligingen toepassen voor implementaties.

Standaardomgevingsvariabelen en contexten

In de GitHub Actions-werkstroom zijn verschillende standaardomgevingsvariabelen beschikbaar die u kunt gebruiken, maar alleen binnen de runner die een taak uitvoert. Deze standaardvariabelen zijn hoofdlettergevoelig en ze verwijzen naar configuratiewaarden voor het systeem en voor de huidige gebruiker. U wordt aangeraden deze standaardomgevingsvariabelen te gebruiken om naar het bestandssysteem te verwijzen in plaats van naar vaste bestandspaden te gebruiken. Als u een standaardomgevingsvariabele wilt gebruiken, geeft u $ de naam van de omgevingsvariabele op gevolgd door de naam van de omgevingsvariabele.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Naast de standaardomgevingsvariabelen kunt u gedefinieerde variabelen als contexten gebruiken. Contexten en standaardvariabelen zijn vergelijkbaar omdat ze beide toegang bieden tot omgevingsgegevens, maar ze hebben enkele belangrijke verschillen. Hoewel standaardomgevingsvariabelen alleen binnen de runner kunnen worden gebruikt, kunt u contextvariabelen op elk gewenst moment in de werkstroom gebruiken. Met contextvariabelen kunt u bijvoorbeeld een if instructie uitvoeren om een expressie te evalueren voordat de runner wordt uitgevoerd.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

In dit voorbeeld wordt de context gebruikt om de github.ref vertakking te controleren die de werkstroom heeft geactiveerd. Als de vertakking is main, wordt de runner uitgevoerd en wordt 'Implementeren naar productieserver op vertakking $GITHUB_REF' afgedrukt. De standaardomgevingsvariabele $GITHUB_REF wordt gebruikt in de runner om naar de vertakking te verwijzen. U ziet dat standaardomgevingsvariabelen allemaal hoofdletters zijn waarbij contextvariabelen allemaal kleine letters bevatten.

Contextuele informatie die beschikbaar is in een werkstroom

Gebruik contexten voor toegang tot informatie over werkstroomuitvoeringen, variabelen, runner-omgevingen, taken en stappen. Elke context is een object dat eigenschappen bevat die andere objecten of tekenreeksen kunnen zijn. Beschikbare contexten zijn onder andere github, env, vars, job, jobs, steps, runner, secrets, strategy, matrix, needs en inputs.

De volgende tabel bevat werkstroomcontexten en beschrijvingen:

Context Beschrijving
github Informatie over de uitvoering van de werkstroom. Zie github context voor meer informatie.
env Bevat variabelen die u hebt ingesteld in een werkstroom, taak of stap. Zie env context voor meer informatie.
vars Bevat variabelen die u instelt op het niveau van de opslagplaats, organisatie of omgeving. Zie vars context voor meer informatie.
job Informatie over de huidige taak. Zie job context voor meer informatie.
jobs Alleen voor herbruikbare werkstromen bevat het uitvoer van taken uit de herbruikbare werkstromen. Zie jobs context voor meer informatie.
steps Informatie over de stappen die in de huidige taak zijn uitgevoerd. Zie steps context voor meer informatie.
runner Informatie over de runner die de huidige taak uitvoert. Zie runner context voor meer informatie.
secrets Bevat de namen en waarden van geheimen die beschikbaar zijn voor een workflow-uitvoering. Zie secrets context voor meer informatie.
strategy Informatie over de matrixuitvoeringsstrategie voor de huidige taak. Zie strategy context voor meer informatie.
matrix Bevat de matrixeigenschappen die zijn gedefinieerd in de werkstroom die van toepassing zijn op de huidige taak. Zie matrix context voor meer informatie.
needs Bevat de uitvoer van alle taken die zijn gedefinieerd als een afhankelijkheid van de huidige taak. Zie needs context voor meer informatie.
inputs Bevat de invoer van een herbruikbare of handmatig geactiveerde werkstroom. Zie inputs context voor meer informatie.

Er zijn verschillende contexten beschikbaar op verschillende tijdstippen in een werkstroomuitvoering. U kunt bijvoorbeeld de secrets context alleen op specifieke plaatsen in een taak gebruiken. U kunt ook bepaalde functies, zoals de hashFiles functie, alleen op specifieke plaatsen gebruiken.

De volgende tabel bevat beperkingen voor elke context en speciale functie in een werkstroom. De vermelde contexten zijn alleen beschikbaar voor de aangegeven werkstroomsleutel. U kunt ze nergens anders gebruiken. U kunt een functie overal gebruiken, tenzij deze wordt vermeld in de volgende tabel.

Werkstroomsleutel Context Speciale functies
run-name github, inputs, vars Geen
concurrency github, inputs, vars Geen
env github,secrets,inputs,vars Geen
jobs.<job_id>.concurrency github, needs, strategy, matrix, inputs, vars Geen
jobs.<job_id>.container github, needs, strategy, matrix, vars, inputs Geen
jobs.<job_id>.container.credentials github, , needsstrategy, matrix, , env, , varssecretsinputs Geen
jobs.<job_id>.container.env.<env_id> github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs Geen
jobs.<job_id>.container.image github, needs, strategy, matrix, vars, inputs Geen
jobs.<job_id>.continue-on-error github, needs, strategy, vars, matrix, inputs Geen
jobs.<job_id>.defaults.run github, , needsstrategy, matrix, , env, , varsinputs Geen
jobs.<job_id>.env github, , needsstrategy, matrix, , vars, , secretsinputs Geen
jobs.<job_id>.environment github, needs, strategy, matrix, vars, inputs Geen
jobs.<job_id>.environment.url github, needs, strategy, matrix, job, runner, env, vars, steps, inputs Geen
jobs.<job_id>.if github,needs,vars,inputs always,canceled,success,failure
jobs.<job_id>.name github, needs, strategy, matrix, vars, inputs Geen
jobs.<job_id>.outputs.<output_id> github, needsstrategy, matrix, job, runner, env, vars, secrets, steps, inputs Geen
jobs.<job_id>.runs-on github, needs, strategy, matrix, vars, inputs Geen
jobs.<job_id>.secrets.<secrets_id> github, , needsstrategy, matrix, , secrets, , inputsvars Geen
jobs.<job_id>.services github, needs, strategy, matrix, vars, inputs Geen
jobs.<job_id>.services.<service_id>.credentials github, , needsstrategy, matrix, , env, , varssecretsinputs Geen
jobs.<job_id>.services.<service_id>.env.<env_id> github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs Geen
jobs.<job_id>.steps.continue-on-error github, needsstrategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.env github, needsstrategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.if github, needs, strategy, matrix, job, runner, env, vars, steps, inputs always, canceled, success, failure, hashFiles
jobs.<job_id>.steps.name github, needsstrategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.run github, needsstrategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.timeout-minutes github, needsstrategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.with github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.working-directory github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.strategy github, behoeften, vars, , inputs Geen
jobs.<job_id>.timeout-minutes github, needs, strategy, matrix, vars, inputs Geen
jobs.<job_id>.with.<with_id> github, needs, strategy, matrix, inputs, vars Geen
on.workflow_call.inputs.<inputs_id>.default github, inputs, vars Geen
on.workflow_call.outputs.<output_id>.value github, banen, vars, inputs Geen

Aangepaste omgevingsvariabelen

Net als bij het gebruik van standaardomgevingsvariabelen kunt u aangepaste omgevingsvariabelen gebruiken in uw werkstroombestand. Als u een aangepaste variabele wilt maken, moet u deze definiëren in uw werkstroombestand met behulp van de env context. Als u de waarde van een omgevingsvariabele in een runner wilt gebruiken, kunt u de normale methode van het runner-besturingssysteem gebruiken voor het lezen van omgevingsvariabelen.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

Aangepaste omgevingsvariabelen instellen in een werkstroom

U kunt omgevingsvariabelen definiëren die zijn afgestemd op de hele werkstroom met behulp env van het hoogste niveau van het werkstroombestand. Beperk de inhoud van een taak binnen een werkstroom met behulp van jobs.<job_id>.env. U kunt de reikwijdte van een omgevingsvariabele bepalen op een specifieke stap binnen een taak met behulp van jobs.<job_id>.steps[*].env.

Hier volgt een voorbeeld waarin alle drie de scenario's in een werkstroombestand worden weergegeven:

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Een standaardcontext gebruiken in een werkstroom

Het GitHub-platform stelt standaardomgevingsvariabelen in. Ze zijn niet gedefinieerd in een werkstroom, maar u kunt een standaardomgevingsvariabele in een werkstroom gebruiken in de juiste context. De meeste van deze variabelen, anders dan CI, beginnen met GITHUB_* of RUNNER_*. De laatste twee typen kunnen niet worden overschreven. Deze standaardvariabelen hebben ook een overeenkomstige en vergelijkbare benoemde contexteigenschap. De reeks standaardvariabelen heeft bijvoorbeeld RUNNER_* een overeenkomende contexteigenschap van runner.*.

Hier volgt een voorbeeld van hoe u toegang krijgt tot standaardvariabelen in een werkstroom door deze methoden toe te passen:

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

Zie Standaardomgevingsvariabelen voor meer informatie.

Aangepaste omgevingsvariabelen doorgeven aan een werkstroom

U kunt aangepaste omgevingsvariabelen van één stap van een werkstroomtaak doorgeven aan de volgende stappen binnen de taak. Genereer een waarde in één stap van een taak en wijs de waarde toe aan een bestaande of nieuwe omgevingsvariabele. Vervolgens schrijft u het variabele/waardepaar naar het GITHUB_ENV omgevingsbestand. U kunt het omgevingsbestand in een actie of vanuit een shellopdracht in de werkstroomtaak gebruiken met behulp van het run trefwoord.

De stap waarmee de omgevingsvariabele wordt gemaakt of bijgewerkt, heeft geen toegang tot de nieuwe waarde, maar alle volgende stappen in een taak hebben toegang.

Hier is een voorbeeld:

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

Omgevingsbeveiligingen toevoegen

U kunt beveiligingsregels toevoegen voor omgevingen die zijn gedefinieerd voor uw GitHub-opslagplaats.

Ga als volgende te werk om een omgeving toe te voegen in uw opslagplaats:

  1. Selecteer Instellingen.

    Menubalk van een webinterface met tabbladen zoals Code, Problemen en Wiki; Instellingen zijn gemarkeerd.

  2. Selecteer Omgeving in het linkerdeelvenster.

    Schermopname van een menu Instellingen onder Algemeen met secties voor toegang, code en automatisering, beveiliging en integraties. De optie Omgevingen is gemarkeerd.

  3. Selecteer de knop Nieuwe omgeving om een omgeving toe te voegen en te configureren en beveiligingen toe te voegen.

    Schermopname van de pagina Instellingen voor GitHub-opslagplaats met de sectie Omgevingen met een bericht waarin wordt aangegeven dat er geen omgevingen bestaan en dat er een knop Nieuwe omgeving is gemarkeerd.

Over omgevingen

Gebruik omgevingen om een algemeen implementatiedoel te beschrijven, zoals productie, fasering of ontwikkeling. Wanneer een GitHub Actions-werkstroom in een omgeving wordt geïmplementeerd, wordt de omgeving weergegeven op de hoofdpagina van de opslagplaats. U kunt omgevingen gebruiken om goedkeuring te vereisen voor een taak om door te gaan, beperken welke vertakkingen een werkstroom kunnen activeren, implementaties controleren met behulp van aangepaste implementatiebeschermingsregels, of de toegang tot geheimen beperken.

Elke taak in een werkstroom kan verwijzen naar één omgeving. Alle beveiligingsregels die u voor de omgeving instelt, moeten worden voldaan voordat een taak die naar de omgeving verwijst, naar een runner wordt verzonden. De taak heeft pas toegang tot de geheimen van de omgeving nadat de taak naar een runner is verzonden.

Wanneer een werkstroom verwijst naar een omgeving, wordt de omgeving weergegeven in de implementaties van de opslagplaats.

Omgevingsbeveiligingsregels

Implementatiebeschermingsregels voor de omgeving vereisen specifieke voorwaarden waaraan moet worden voldaan voordat taken voor de omgeving worden uitgevoerd. U kunt beveiligingsregels voor implementatie gebruiken om handmatige goedkeuring te vereisen, een taak uit te stellen of de omgeving te beperken tot specifieke vertakkingen. U kunt ook aangepaste beveiligingsregels maken en implementeren die worden mogelijk gemaakt door GitHub-apps om partnersystemen te gebruiken om implementaties te beheren die verwijzen naar omgevingen die zijn geconfigureerd op GitHub.

Hier volgt een uitleg van deze beveiligingsregels:

  • Vereiste beveiligingsregels voor revisoren. Gebruik deze regel om een specifieke persoon of een specifiek team te verplichten werkstroomtaken goed te keuren die naar de omgeving verwijzen. U kunt maximaal zes gebruikers of teams weergeven als revisoren. De revisoren moeten ten minste leesmachtigingen hebben voor de opslagplaats. Slechts één vereiste revisor moet de taak goedkeuren om door te gaan.

    U kunt ook zelfbeoordelingen voor implementaties in een beveiligde omgeving voorkomen. Als u deze instelling inschakelt, kunnen gebruikers die een implementatie starten de implementatietaak niet goedkeuren, zelfs niet als ze een vereiste revisor zijn. Door zelfbeoordelingen in te schakelen, zorgt het ervoor dat meer dan één persoon implementaties beoordeelt in beveiligde omgevingen.

    Zie Implementaties beoordelen voor meer informatie over het beoordelen van taken die betrekking hebben op een omgeving met verplichte beoordelaars.

  • Regels voor timerprojecties. U kunt een wachttimerbeveiligingsregel gebruiken om een taak gedurende een bepaalde tijd uit te stellen nadat de taak in eerste instantie is geactiveerd voordat de implementatie van de omgeving wordt voortgezet. De tijd (in minuten) moet een geheel getal tussen 1 en 43.200 (30 dagen) zijn. De wachttijd telt niet mee voor uw factureerbare tijd.

  • Vertakkings- en tagbeveiligingsregels. U kunt regels voor implementatiebranch en tagbeveiliging gebruiken om te beperken welke vertakkingen en tags worden gebruikt om in de omgeving te implementeren. U hebt verschillende opties voor implementatiebranch- en tagbeveiligingsregels voor een omgeving.

    • Geen beperking stelt geen beperking in voor welke vertakking of tag in de omgeving kan worden geïmplementeerd.
    • Met beveiligde vertakkingen kunnen alleen vertakkingen met vertakkingsbeveiligingsregels worden geïmplementeerd in de omgeving. Als er geen vertakkingsbeveiligingsregels zijn gedefinieerd voor een vertakking in de opslagplaats, kunnen alle vertakkingen worden geïmplementeerd. De instelling Geselecteerde vertakkingen en tags zorgt ervoor dat alleen vertakkingen en tags die overeenkomen met uw opgegeven naampatronen, in de omgeving kunnen worden geïmplementeerd.
    • Als u releases/* specificeert als een implementatietak of tagregel, kan alleen een tak of tag waarvan de naam begint met releases/ worden geïmplementeerd in de omgeving. (Jokertekens komen niet overeen /. Als u vertakkingen of tags wilt vergelijken die beginnen met release/ en een andere slash bevatten, gebruikt u release/*/*.) Als u als vertakkingsregel toevoegt main , kan een vertakking met de naam main ook worden geïmplementeerd in de omgeving.

  • Aangepaste beveiligingsregels voor implementaties. U kunt aangepaste beveiligingsregels maken om implementaties te beheren en het gebruik van partnerservices te reguleren. U kunt bijvoorbeeld waarneembaarheidssystemen, wijzigingsbeheersystemen, codekwaliteitssystemen of andere handmatige configuraties gebruiken die u gebruikt om gereedheid te beoordelen en geautomatiseerde goedkeuringen te bieden voor implementaties naar GitHub.

    Nadat u aangepaste beveiligingsregels voor implementaties hebt gemaakt en deze in een opslagplaats hebt geïnstalleerd, kunt u de aangepaste beveiligingsregel voor implementaties inschakelen voor elke omgeving in de opslagplaats.

    Schermopname van de pagina Instellingen voor het configureren van Omgeving1 met opties voor revisoren, wachttijdtimer, aangepaste regels en vertakkingsbeperkingen.

Opmerking

Als u een GitHub Free-, GitHub Pro- of GitHub Team-plan hebt, zijn de projectieregels voor de omgevingsimplementatie alleen beschikbaar voor openbare opslagplaatsen; met uitzondering van regels voor vertakkings- en tagbeveiliging. Voor gebruikers met GitHub Pro- of GitHub Team-abonnementen zijn vertakkings- en tagbeveiligingsregels ook beschikbaar voor privéopslagplaatsen.

Scripts in uw werkstroom

In de voorgaande voorbeelden van werkstroomfragmenten wordt het run trefwoord gebruikt om een tekenreeks met tekst af te drukken. Omdat het run trefwoord aangeeft dat de taak een opdracht op de runner moet uitvoeren, gebruikt u het run trefwoord om acties of scripts uit te voeren.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

In dit voorbeeld gebruikt u npm om het bats softwaretestpakket te installeren met behulp van het run trefwoord. U kunt ook een script uitvoeren als een actie. U kunt het script opslaan in uw opslagplaats, vaak uitgevoerd in een .github/scripts/ map en vervolgens het pad en shelltype opgeven met behulp van het run trefwoord.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash