Tilpas din arbejdsproces med miljøvariabler

  • 8 minutter

I dette undermodul lærer du, hvordan du konfigurerer og administrerer miljøspecifik funktionsmåde ved hjælp af variabler, kontekster og brugerdefinerede scripts i arbejdsprocesser for GitHub-handlinger.

Hvis du vil implementere denne proces, får du mere at vide om, hvordan du:

  • Brug standardvariabler og brugerdefinerede miljøvariabler.
  • Få adgang til kontekstafhængige oplysninger i arbejdsprocesser.
  • Angiv miljøvariabler i forskellige arbejdsprocesområder.
  • Brug brugerdefinerede scripts sammen med kørselsnøgleordet.
  • Anvend miljøbeskyttelse for udrulninger.

Standardmiljøvariabler og -kontekster

I arbejdsprocessen For GitHub-handlinger er flere standardmiljøvariabler tilgængelige, som du kan bruge, men kun i den løber, der udfører et job. Der er forskel på store og små bogstaver i disse standardvariabler, og de refererer til konfigurationsværdier for systemet og for den aktuelle bruger. Vi anbefaler, at du bruger disse standardmiljøvariabler til at referere til filsystemet i stedet for at bruge hard-coded filstier. Hvis du vil bruge en standardmiljøvariabel, skal du angive $ efterfulgt af miljøvariablens navn.

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

Ud over standardmiljøvariabler kan du bruge definerede variabler som kontekster. Kontekster og standardvariabler ligner hinanden, fordi de begge giver adgang til miljøoplysninger, men de har nogle vigtige forskelle. Selvom standardmiljøvariabler kun kan bruges i løberen, kan du bruge kontekstvariabler når som helst i arbejdsprocessen. Kontekstvariabler giver dig f.eks. mulighed for at køre en if sætning for at evaluere et udtryk, før løberen udføres.

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"

I dette eksempel bruges konteksten github.ref til at kontrollere den forgrening, der udløste arbejdsprocessen. Hvis forgreningen er main, udføres løberen og udskriver "Udrulning på produktionsserver på forgrenings $GITHUB_REF". Standardmiljøvariablen $GITHUB_REF bruges i løberen til at referere til forgreningen. Bemærk, at standardmiljøvariabler alle er store, hvor kontekstvariabler alle er små.

Kontekstafhængige oplysninger, der er tilgængelige i en arbejdsproces

Brug kontekster til at få adgang til oplysninger om arbejdsproceskørsler, variabler, løbermiljøer, job og trin. Hver kontekst er et objekt, der indeholder egenskaber, der kan være andre objekter eller strenge. Tilgængelige kontekster omfatter github, env, vars, job, jobssteps, runner, secretsstrategy, matrix, needsog inputs.

I følgende tabel vises arbejdsproceskontekster og -beskrivelser:

Kontekst Beskrivelse
github Oplysninger om kørsel af arbejdsprocessen. Du kan få flere oplysninger i github kontekst.
env Indeholder variabler, som du angiver i en arbejdsproces, et job eller et trin. Du kan få flere oplysninger i env kontekst.
vars Indeholder variabler, som du angiver på lager-, organisations- eller miljøniveau. Du kan få flere oplysninger i vars kontekst.
job Oplysninger om det job, der kører i øjeblikket. Du kan få flere oplysninger i job kontekst.
jobs For arbejdsprocesser, der kun kan genbruges, indeholder output af job fra den arbejdsproces, der kan genbruges. Du kan få flere oplysninger i jobs kontekst.
steps Oplysninger om de trin, der kørte i det aktuelle job. Du kan få flere oplysninger i steps kontekst.
runner Oplysninger om den løber, der kører det aktuelle job. Du kan få flere oplysninger i runner kontekst.
secrets Indeholder navne og værdier på hemmeligheder, der er tilgængelige for kørsel af en arbejdsproces. Du kan få flere oplysninger i secrets kontekst.
strategy Oplysninger om matrixudførelsesstrategien for det aktuelle job. Du kan få flere oplysninger i strategy kontekst.
matrix Indeholder de matrixegenskaber, der er defineret i arbejdsprocessen, og som gælder for det aktuelle job. Du kan få flere oplysninger i matrix kontekst.
needs Indeholder output fra alle job, der er defineret som en afhængighed af det aktuelle job. Du kan få flere oplysninger i needs kontekst.
inputs Indeholder input fra en arbejdsproces, der kan genbruges eller udløses manuelt. Du kan få flere oplysninger i inputs kontekst.

Forskellige kontekster er tilgængelige på forskellige tidspunkter i en arbejdsproceskørsel. Du kan f.eks. kun bruge konteksten secrets på bestemte steder i et job. Du kan også kun bruge nogle funktioner, f.eks. funktionen hashFiles , på bestemte steder.

I følgende tabel vises begrænsninger for hver kontekst og særlige funktion i en arbejdsproces. De angivne kontekster er kun tilgængelige for den angivne arbejdsprocesnøgle. Du kan ikke bruge dem andre steder. Du kan bruge en funktion overalt, medmindre den er angivet i følgende tabel.

Arbejdsprocesnøgle Kontekst Særlige funktioner
run-name github, , , inputsvars Ingen
concurrency github, , , inputsvars Ingen
env github, secrets, inputsvars Ingen
jobs.<job_id>.concurrency github, needs, strategy, matrixinputsvars Ingen
jobs.<job_id>.container github, needs, strategy, matrixvarsinputs Ingen
jobs.<job_id>.container.credentials github, needs, , strategymatrixenvvarssecretsinputs Ingen
jobs.<job_id>.container.env.<env_id> github, , needsstrategy, matrix, job, runner, env, vars, secrets,inputs Ingen
jobs.<job_id>.container.image github, needs, strategy, matrixvarsinputs Ingen
jobs.<job_id>.continue-on-error github, needs, strategy, varsmatrixinputs Ingen
jobs.<job_id>.defaults.run github, needs, strategy, matrix, env, varsinputs Ingen
jobs.<job_id>.env github, needs, strategy, matrix, vars, secretsinputs Ingen
jobs.<job_id>.environment github, needs, strategy, matrixvarsinputs Ingen
jobs.<job_id>.environment.url github, , needsstrategy, matrix, job, runner, env, vars, steps,inputs Ingen
jobs.<job_id>.if github, needs, varsinputs always, canceled, successfailure
jobs.<job_id>.name github, needs, strategy, matrixvarsinputs Ingen
jobs.<job_id>.outputs.<output_id> github, , needsstrategy, matrix, job, runner, env, vars, secrets, steps,inputs Ingen
jobs.<job_id>.runs-on github, needs, strategy, matrixvarsinputs Ingen
jobs.<job_id>.secrets.<secrets_id> github, needs, strategy, matrix, secrets, inputsvars Ingen
jobs.<job_id>.services github, needs, strategy, matrixvarsinputs Ingen
jobs.<job_id>.services.<service_id>.credentials github, needs, , strategymatrixenvvarssecretsinputs Ingen
jobs.<job_id>.services.<service_id>.env.<env_id> github, , needsstrategy, matrix, job, runner, env, vars, secrets,inputs Ingen
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, , needsstrategy, matrix, job, runner, env, vars, steps,inputs always, canceled, success, failurehashFiles
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, , stepsinputs hashFiles
jobs.<job_id>.steps.working-directory github, needs, strategy, matrix, job, runner, env, vars, secrets, , stepsinputs hashFiles
jobs.<job_id>.strategy github, behov, vars, , inputs Ingen
jobs.<job_id>.timeout-minutes github, needs, strategy, matrixvarsinputs Ingen
jobs.<job_id>.with.<with_id> github, needs, strategy, matrixinputsvars Ingen
on.workflow_call.inputs.<inputs_id>.default github, , , inputsvars Ingen
on.workflow_call.outputs.<output_id>.value github, job, vars, inputs Ingen

Brugerdefinerede miljøvariabler

På samme måde som med standardmiljøvariabler kan du bruge brugerdefinerede miljøvariabler i arbejdsprocesfilen. Hvis du vil oprette en brugerdefineret variabel, skal du definere den i din arbejdsprocesfil ved hjælp af konteksten env. Hvis du vil bruge værdien af en miljøvariabel i en løber, kan du bruge operativsystemets normale metode til at læse miljøvariabler.

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

Angiv brugerdefinerede miljøvariabler i en arbejdsproces

Du kan definere miljøvariabler, der er begrænset til hele arbejdsprocessen, ved hjælp env af på øverste niveau i arbejdsprocesfilen. Omfang indholdet af et job i en arbejdsproces ved hjælp jobs.<job_id>.envaf . Du kan områdeområde en miljøvariabel på et bestemt trin i et job ved hjælp jobs.<job_id>.steps[*].envaf .

Her er et eksempel, der viser alle tre scenarier i en arbejdsprocesfil:

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

Brug en standardkontekst i en arbejdsproces

GitHub-platformen angiver standardmiljøvariabler. De er ikke defineret i en arbejdsproces, men du kan bruge en standardmiljøvariabel i en arbejdsproces i den relevante kontekst. De fleste af disse variabler, bortset fra CI, begynder med GITHUB_* eller RUNNER_*. De sidste to typer kan ikke overskrives. Disse standardvariabler har også en tilsvarende kontekstegenskab med samme navn. Serien af standardvariabler har f.eks RUNNER_* . en tilsvarende kontekstegenskab for runner.*.

Her er et eksempel på, hvordan du får adgang til standardvariabler i en arbejdsproces ved at anvende disse metoder:

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

Du kan få flere oplysninger under Standardmiljøvariabler.

Overfør brugerdefinerede miljøvariabler til en arbejdsproces

Du kan overføre brugerdefinerede miljøvariabler fra ét trin i et arbejdsprocesjob til efterfølgende trin i jobbet. Opret en værdi i ét trin i et job, og tildel værdien til en eksisterende eller ny miljøvariabel. Derefter skal du skrive variablen/værdiparret til miljøfilen GITHUB_ENV. Du kan bruge miljøfilen i en handling eller fra en shellkommando i arbejdsprocesjobbet ved hjælp af nøgleordet run .

Det trin, der opretter eller opdaterer miljøvariablen, har ikke adgang til den nye værdi, men alle efterfølgende trin i et job har adgang.

Her er et eksempel:

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'

Tilføj miljøbeskyttelse

Du kan tilføje beskyttelsesregler for miljøer, der er defineret for dit GitHub-lager.

Hvis du vil tilføje et miljø, skal du i dit lager:

  1. Vælg Indstillinger.

    Menulinjen i en webgrænseflade med faner som Kode, Problemer og Wiki. Indstillinger er fremhævet.

  2. Vælg Miljø i ruden til venstre.

    Skærmbillede af menuen Indstillinger under Generelt med afsnit om adgang, kode og automatisering, sikkerhed og integrationer. Indstillingen Miljøer er fremhævet.

  3. Vælg knappen Nyt miljø for at tilføje og konfigurere et miljø og tilføje beskyttelse.

    Skærmbillede af siden Indstillinger for GitHub-lager, der viser sektionen Miljøer med en meddelelse, der angiver, at der ikke findes miljøer, og at knappen Nyt miljø er fremhævet.

Om miljøer

Brug miljøer til at beskrive et generelt udrulningsmål, f.eks. produktion, midlertidig lagring eller udvikling. Når en Arbejdsproces for GitHub-handlinger udrulles i et miljø, vises miljøet på hovedsiden i lageret. Du kan bruge miljøer til at kræve godkendelse af et job for at fortsætte, begrænse, hvilke forgreninger der kan udløse en arbejdsproces, portudrulninger ved hjælp af brugerdefinerede beskyttelsesregler for udrulning eller begrænse adgangen til hemmeligheder.

Hvert job i en arbejdsproces kan referere til ét miljø. Alle beskyttelsesregler, du angiver for miljøet, skal bestå, før et job, der refererer til miljøet, sendes til en løber. Jobbet kan først få adgang til miljøets hemmeligheder, når jobbet er sendt til en løber.

Når en arbejdsproces refererer til et miljø, vises miljøet i lagerets installationer.

Miljøbeskyttelsesregler

Regler for beskyttelse af miljøinstallation kræver specifikke betingelser, der skal overføres, før et job, der refererer til miljøet, fortsætter. Du kan bruge regler for udrulningsbeskyttelse til at kræve manuel godkendelse, forsinke et job eller begrænse miljøet til bestemte forgreninger. Du kan også oprette og implementere brugerdefinerede beskyttelsesregler, der er baseret på GitHub Apps, for at bruge partnersystemer til at styre udrulninger, der refererer til miljøer, der er konfigureret på GitHub.

Her er en forklaring af disse beskyttelsesregler:

  • Påkrævede beskyttelsesregler for korrekturlæsere. Brug denne regel til at kræve, at en bestemt person eller et bestemt team godkender arbejdsprocesjob, der refererer til miljøet. Du kan angive op til seks brugere eller teams som korrekturlæsere. Korrekturlæserne skal som minimum have læserettigheder til lageret. Det er kun én påkrævet korrekturlæser, der skal godkende jobbet, for at det kan fortsætte.

    Du kan også forhindre selvgennemgang af installationer i et beskyttet miljø. Hvis du aktiverer denne indstilling, kan brugere, der starter en udrulning, ikke godkende installationsjobbet, selvom de er en påkrævet korrekturlæser. Ved at aktivere selvgennemgang sikrer det, at mere end én person gennemser udrulninger til beskyttede miljøer.

    Du kan få flere oplysninger om gennemsyn af job, der refererer til et miljø med påkrævede korrekturlæsere, under Gennemse udrulninger.

  • Regler for projektion af vent-timer. Du kan bruge en regel for beskyttelse af vent-timeren til at forsinke et job i et bestemt tidsrum, efter at jobbet startes, før installationen af miljøet fortsætter. Klokkeslættet (i minutter) skal være et heltal mellem 1 og 43.200 (30 dage). Ventetiden tæller ikke med i din fakturerbare tid.

  • Regler for beskyttelse af forgreninger og mærker. Du kan bruge regler for udrulningsforgrening og kodebeskyttelse til at begrænse, hvilke forgreninger og mærker der bruges til at udrulle til miljøet. Du har flere muligheder for udrulningsforgrening og kodebeskyttelsesregler for et miljø.

    • Ingen begrænsning angiver nogen begrænsning for, hvilken forgrening eller kode der kan installeres i miljøet.
    • Beskyttede forgreninger tillader kun , at forgreninger med regler for beskyttelse af forgreninger er aktiveret til installation i miljøet. Hvis der ikke er defineret nogen regler for beskyttelse af forgreninger for en forgrening i lageret, kan alle forgreninger installeres. Indstillingen Valgte forgreninger og mærker sikrer, at det kun er forgreninger og mærker, der svarer til dine angivne navnemønstre, der kan udrulles i miljøet.
    • Hvis du angiver releases/* som en udrulningsgren eller koderegel, er det kun en forgrening eller kode med et navn, der starter med releases/ , der kan installeres i miljøet. (Jokertegn svarer ikke til /. Hvis du vil matche forgreninger eller mærker, der starter med release/ og indeholder en anden enkelt skråstreg, skal du bruge release/*/*.) Hvis du tilføjer main en forgreningsregel, kan en forgrening med navnet main også installeres i miljøet.

  • Brugerdefinerede regler for udrulningsbeskyttelse. Du kan oprette brugerdefinerede beskyttelsesregler for at oprette udrulninger for at bruge partnertjenester. Du kan f.eks. bruge observability-systemer, systemer til ændringsstyring, kodekvalitetssystemer eller andre manuelle konfigurationer, som du bruger til at vurdere parathed og levere automatiserede godkendelser af udrulninger til GitHub.

    Når du har oprettet brugerdefinerede regler for udrulningsbeskyttelse og installeret dem på et lager, kan du aktivere reglen for brugerdefineret udrulningsbeskyttelse for alle miljøer i lageret.

    Skærmbillede, der viser siden Indstillinger til konfiguration af Miljø1 med indstillinger for korrekturlæsere, ventetid, brugerdefinerede regler og forgreningsbegrænsninger.

Notat

Hvis du har en GitHub Free-, GitHub Pro- eller GitHub-teamplan, er reglerne for projektion af miljøinstallation kun tilgængelige for offentlige lagre. undtagen forgrenings- og kodebeskyttelsesregler. For brugere, der har GitHub Pro- eller GitHub-teamplaner, er beskyttelsesregler for forgreninger og mærker også tilgængelige for private lagre.

Scripts i din arbejdsproces

I de foregående eksempler på arbejdsprocesstykker bruges nøgleordet run til at udskrive en tekststreng. Da nøgleordet run fortæller jobbet at udføre en kommando på løberen, skal du bruge nøgleordet run til at køre handlinger eller scripts.

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

I dette eksempel skal du bruge npm til at installere bats softwaretestpakken ved hjælp af nøgleordet run . Du kan også køre et script som en handling. Du kan gemme scriptet i dit lager, ofte i en .github/scripts/ mappe, og derefter angive stien og shelltypen ved hjælp af nøgleordet run.

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