Tilpasse arbeidsflyten med miljøvariabler

  • 8 minutter

I denne enheten lærer du hvordan du konfigurerer og administrerer miljøspesifikk atferd ved hjelp av variabler, kontekster og egendefinerte skript i Arbeidsflyter for GitHub-handlinger.

Hvis du vil implementere denne prosessen, lærer du hvordan du gjør følgende:

  • Bruk standard og egendefinerte miljøvariabler.
  • Få tilgang til kontekstuell informasjon i arbeidsflyter.
  • Angi miljøvariabler i ulike arbeidsflytomfang.
  • Bruk egendefinerte skript med nøkkelordet kjør.
  • Bruk miljøbeskyttelse for distribusjoner.

Standard miljøvariabler og kontekster

I arbeidsflyten For GitHub-handlinger er flere standard miljøvariabler tilgjengelige for bruk, men bare innenfor løperen som utfører en jobb. Disse standardvariablene skiller mellom store og små bokstaver, og de refererer til konfigurasjonsverdier for systemet og for gjeldende bruker. Vi anbefaler at du bruker disse standard miljøvariablene til å referere til filsystemet i stedet for å bruke hardkodede filbaner. Hvis du vil bruke en standard miljøvariabel, angir du $ etterfulgt av navnet på miljøvariabelen.

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

I tillegg til standard miljøvariabler kan du bruke definerte variabler som kontekster. Kontekster og standardvariabler er like ved at begge gir tilgang til miljøinformasjon, men de har noen viktige forskjeller. Selv om standard miljøvariabler bare kan brukes i løperen, kan du bruke kontekstvariabler når som helst i arbeidsflyten. Kontekstvariabler lar deg for eksempel kjøre en if setning for å evaluere et uttrykk før løperen kjø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"

Dette eksemplet bruker github.ref kontekst til å kontrollere grenen som utløste arbeidsflyten. Hvis grenen er main, kjøres løperen og skriver ut «Distribuering til produksjonsserver på gren $GITHUB_REF». Standard miljøvariabel $GITHUB_REF brukes i løperen til å referere til grenen. Legg merke til at standard miljøvariabler er store bokstaver der kontekstvariabler er små bokstaver.

Kontekstavhengig informasjon som er tilgjengelig i en arbeidsflyt

Bruk kontekster for å få tilgang til informasjon om arbeidsflytkjøringer, variabler, løpermiljøer, jobber og trinn. Hver kontekst er et objekt som inneholder egenskaper som kan være andre objekter eller strenger. Tilgjengelige kontekster inkluderer github, , env, vars, jobjobs, steps, runner, secrets, strategy, matrix, needsog inputs.

Tabellen nedenfor viser arbeidsflytkontekster og beskrivelser:

Kontekst Beskrivelse
github Informasjon om arbeidsflytkjøringen. Hvis du vil ha mer informasjon, kan du se github kontekst.
env Inneholder variabler som du angir i en arbeidsflyt, jobb eller et trinn. Hvis du vil ha mer informasjon, kan du se env kontekst.
vars Inneholder variabler som du angir på repositorium, organisasjon eller miljønivå. Hvis du vil ha mer informasjon, kan du se vars kontekst.
job Informasjon om den gjeldende jobben. Hvis du vil ha mer informasjon, kan du se job kontekst.
jobs Bare for gjenbrukbare arbeidsflyter inneholder utdata for jobber fra arbeidsflyten som kan brukes på nytt. Hvis du vil ha mer informasjon, kan du se jobs kontekst.
steps Informasjon om trinnene som kjørte i gjeldende jobb. Hvis du vil ha mer informasjon, kan du se steps kontekst.
runner Informasjon om løperen som kjører den gjeldende jobben. Hvis du vil ha mer informasjon, kan du se runner kontekst.
secrets Inneholder navnene og verdiene til hemmeligheter som er tilgjengelige for en arbeidsflytkjøring. Hvis du vil ha mer informasjon, kan du se secrets kontekst.
strategy Informasjon om strategi for kjøring av matriser for den gjeldende jobben. Hvis du vil ha mer informasjon, kan du se strategy kontekst.
matrix Inneholder matriseegenskapene som er definert i arbeidsflyten som gjelder for gjeldende jobb. Hvis du vil ha mer informasjon, kan du se matrix kontekst.
needs Inneholder utdataene for alle jobber som er definert som en avhengighet av gjeldende jobb. Hvis du vil ha mer informasjon, kan du se needs kontekst.
inputs Inneholder inndataene for en gjenbrukbar eller manuelt utløst arbeidsflyt. Hvis du vil ha mer informasjon, kan du se inputs kontekst.

Ulike kontekster er tilgjengelige på forskjellige tidspunkt i en arbeidsflytkjøring. Du kan for eksempel bare bruke konteksten secrets på bestemte steder i en jobb. Du kan også bruke enkelte funksjoner, for hashFiles eksempel funksjonen, bare på bestemte steder.

Tabellen nedenfor viser begrensninger for hver kontekst og spesialfunksjon i en arbeidsflyt. De oppførte kontekstene er bare tilgjengelige for den angitte arbeidsflytnøkkelen. Du kan ikke bruke dem noe annet sted. Du kan bruke en funksjon hvor som helst med mindre den er oppført i tabellen nedenfor.

Arbeidsflytnøkkel Kontekst Spesielle funksjoner
run-name github, , inputsvars Ingen
concurrency github, , inputsvars Ingen
env github, , secrets, inputsvars Ingen
jobs.<job_id>.concurrency github, needs, , strategymatrix, inputs, ,vars Ingen
jobs.<job_id>.container github, needs, , strategymatrix, vars, ,inputs Ingen
jobs.<job_id>.container.credentials github, needs, , strategy, matrixenvvarssecretsinputs Ingen
jobs.<job_id>.container.env.<env_id> github, needs, strategy, matrix, job, runner, env, vars, , secretsinputs Ingen
jobs.<job_id>.container.image github, needs, , strategymatrix, vars, ,inputs Ingen
jobs.<job_id>.continue-on-error github, needs, , strategyvars, matrix, ,inputs 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, , strategymatrix, vars, ,inputs Ingen
jobs.<job_id>.environment.url github, needs, strategy, matrix, job, runner, env, vars, , stepsinputs Ingen
jobs.<job_id>.if github, , needs, varsinputs always, , canceled, successfailure
jobs.<job_id>.name github, needs, , strategymatrix, vars, ,inputs Ingen
jobs.<job_id>.outputs.<output_id> github, needs, strategy, matrix, job, runner, env, vars, , secrets, stepsinputs Ingen
jobs.<job_id>.runs-on github, needs, , strategymatrix, vars, ,inputs Ingen
jobs.<job_id>.secrets.<secrets_id> github, needs, strategy, matrix, secrets, inputsvars Ingen
jobs.<job_id>.services github, needs, , strategymatrix, vars, ,inputs Ingen
jobs.<job_id>.services.<service_id>.credentials github, needs, , strategy, matrixenvvarssecretsinputs Ingen
jobs.<job_id>.services.<service_id>.env.<env_id> github, needs, strategy, matrix, job, runner, env, vars, , secretsinputs Ingen
jobs.<job_id>.steps.continue-on-error github, needs, strategy, matrix, job, runner, env, vars, , secrets, stepsinputs hashFiles
jobs.<job_id>.steps.env github, needs, strategy, matrix, job, runner, env, vars, , secrets, stepsinputs hashFiles
jobs.<job_id>.steps.if github, needs, strategy, matrix, job, runner, env, vars, , stepsinputs always, canceled, success, , failurehashFiles
jobs.<job_id>.steps.name github, needs, strategy, matrix, job, runner, env, vars, , secrets, stepsinputs hashFiles
jobs.<job_id>.steps.run github, needs, strategy, matrix, job, runner, env, vars, , secrets, stepsinputs hashFiles
jobs.<job_id>.steps.timeout-minutes github, needs, strategy, matrix, job, runner, env, vars, , secrets, stepsinputs hashFiles
jobs.<job_id>.steps.with github, needs, strategy, matrix, job, runnerenv, vars, , secrets, stepsinputs hashFiles
jobs.<job_id>.steps.working-directory github, needs, strategy, matrix, job, runnerenv, vars, , secrets, stepsinputs hashFiles
jobs.<job_id>.strategy github, behov, vars, , inputs Ingen
jobs.<job_id>.timeout-minutes github, needs, , strategymatrix, vars, ,inputs Ingen
jobs.<job_id>.with.<with_id> github, needs, , strategymatrix, inputs, ,vars Ingen
on.workflow_call.inputs.<inputs_id>.default github, , inputsvars Ingen
on.workflow_call.outputs.<output_id>.value github, jobber, vars, inputs Ingen

Egendefinerte miljøvariabler

I likhet med bruk av standard miljøvariabler kan du bruke egendefinerte miljøvariabler i arbeidsflytfilen. Hvis du vil opprette en egendefinert variabel, må du definere den i arbeidsflytfilen ved hjelp av env kontekst. Hvis du vil bruke verdien til en miljøvariabel i en løper, kan du bruke det vanlige systemet for å lese 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

Angi egendefinerte miljøvariabler i en arbeidsflyt

Du kan definere miljøvariabler som er begrenset til hele arbeidsflyten, ved å bruke env på øverste nivå i arbeidsflytfilen. Omfang innholdet i en jobb i en arbeidsflyt ved hjelp jobs.<job_id>.envav . Du kan begrense en miljøvariabel på et bestemt trinn i en jobb ved hjelp jobs.<job_id>.steps[*].envav .

Her er et eksempel som viser alle tre scenariene i en arbeidsflytfil:

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

Bruke en standardkontekst i en arbeidsflyt

GitHub-plattformen angir standard miljøvariabler. De er ikke definert i en arbeidsflyt, men du kan bruke en standard miljøvariabel i en arbeidsflyt i riktig kontekst. De fleste av disse variablene, bortsett fra CI, begynner med GITHUB_* eller RUNNER_*. De to sistnevnte typene kan ikke overskrives. Disse standardvariablene har også en tilsvarende kontekstegenskap med tilsvarende navn. Serien med standardvariabler har for eksempel RUNNER_* en samsvarende kontekstegenskap for runner.*.

Her er et eksempel på hvordan du får tilgang til standardvariabler i en arbeidsflyt ved å bruke disse metodene:

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

Hvis du vil ha mer informasjon, kan du se Standard miljøvariabler.

Sende egendefinerte miljøvariabler til en arbeidsflyt

Du kan sende egendefinerte miljøvariabler fra ett trinn i en arbeidsflytjobb til påfølgende trinn i jobben. Generer en verdi i ett trinn i en jobb, og tilordne verdien til en eksisterende eller ny miljøvariabel. Deretter skriver du variabel-/verdiparet til miljøfilen GITHUB_ENV. Du kan bruke miljøfilen i en handling eller fra en skallkommando i arbeidsflytjobben run ved hjelp av nøkkelordet.

Trinnet som oppretter eller oppdaterer miljøvariabelen, har ikke tilgang til den nye verdien, men alle etterfølgende trinn i en jobb har tilgang.

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'

Legg til miljøbeskyttelse

Du kan legge til beskyttelsesregler for miljøer som er definert for GitHub-repositoriet.

Slik legger du til et miljø i repositoriet:

  1. Velg Innstillinger.

    Menylinjen i et nettgrensesnitt med faner som Kode, Problemer og Wiki. Innstillingene er uthevet.

  2. Velg Miljø i den venstre ruten.

    Skjermbilde av en Innstillinger-meny under Generelt med inndelinger for Access, Kode og automatisering, Sikkerhet og Integreringer. Miljøer-alternativet er uthevet.

  3. Velg Nytt miljø-knappen for å legge til og konfigurere et miljø og legge til beskyttelser.

    Skjermbilde av Siden Innstillinger for GitHub-repositorium som viser Miljøer-delen med en melding som angir at det ikke finnes noen miljøer og en Ny miljø-knapp uthevet.

Om miljøer

Bruk miljøer til å beskrive et generelt distribusjonsmål som produksjon, oppsamling eller utvikling. Når en Arbeidsflyt for GitHub-handlinger distribueres til et miljø, vises miljøet på hovedsiden i repositoriet. Du kan bruke miljøer til å kreve godkjenning for en jobb for å fortsette, begrense hvilke grener som kan utløse en arbeidsflyt, gatedistribusjoner ved hjelp av egendefinerte distribusjonsbeskyttelsesregler eller begrense tilgangen til hemmeligheter.

Hver jobb i en arbeidsflyt kan referere til ett miljø. Alle beskyttelsesregler som du angir for miljøet, må bestå før en jobb som refererer til miljøet, sendes til en løper. Jobben kan få tilgang til miljøets hemmeligheter først etter at jobben er sendt til en løper.

Når en arbeidsflyt refererer til et miljø, vises miljøet i repositoriets distribusjoner.

Regler for miljøvern

Beskyttelsesregler for miljødistribusjon krever bestemte betingelser før en jobb som refererer til miljøet, fortsetter. Du kan bruke regler for distribusjonsbeskyttelse til å kreve manuell godkjenning, forsinke en jobb eller begrense miljøet til bestemte grener. Du kan også opprette og implementere egendefinerte beskyttelsesregler drevet av GitHub Apps for å bruke partnersystemer til å kontrollere distribusjoner som refererer til miljøer som er konfigurert på GitHub.

Her er en forklaring av disse beskyttelsesreglene:

  • Obligatoriske beskyttelsesregler for korrekturlesere. Bruk denne regelen til å kreve at en bestemt person eller gruppe godkjenner arbeidsflytjobber som refererer til miljøet. Du kan liste opp opptil seks brukere eller team som korrekturlesere. Korrekturleserne må minst ha lesetillatelser til repositoriet. Bare én nødvendig korrekturleser må godkjenne jobben for at den skal fortsette.

    Du kan også forhindre selvvurderinger for distribusjoner til et beskyttet miljø. Hvis du aktiverer denne innstillingen, kan ikke brukere som starter en distribusjon godkjenne distribusjonsjobben, selv om de er en nødvendig korrekturleser. Ved å aktivere selvvurderinger sikrer den at mer enn én person gjennomgår distribusjoner til beskyttede miljøer.

    Hvis du vil ha mer informasjon om gjennomgang av jobber som refererer til et miljø med nødvendige korrekturlesere, kan du se Se gjennom distribusjoner.

  • Vent tidtakerprojeksjonsregler. Du kan bruke en regel for ventetidstidtakerbeskyttelse til å utsette en jobb i en bestemt tidsperiode etter at jobben først utløses før miljødistribusjonen fortsetter. Klokkeslettet (i minutter) må være et heltall mellom 1 og 43 200 (30 dager). Ventetiden teller ikke mot fakturerbar tid.

  • Beskyttelsesregler for gren og kode. Du kan bruke regler for distribusjonsgren og kodebeskyttelse til å begrense hvilke grener og merker som brukes til å distribuere til miljøet. Du har flere alternativer for distribusjonsgren og kodebeskyttelsesregler for et miljø.

    • Ingen begrensninger angir ingen begrensning for hvilken gren eller kode som kan distribueres til miljøet.
    • Beskyttede grener tillater bare grener med regler for grenbeskyttelse aktivert for distribusjon til miljøet. Hvis ingen regler for grenbeskyttelse er definert for noen gren i repositoriet, kan alle grener distribueres. Innstillingen for valgte grener og koder sikrer at bare grener og merker som samsvarer med de angitte navnemønstrene, kan distribueres til miljøet.
    • Hvis du angir releases/* som en distribusjonsgren eller koderegel, kan bare en gren eller kode med et navn som begynner med releases/ distribueres til miljøet. (Jokertegn samsvarer /ikke . Hvis du vil sammenligne grener eller merker som begynner med release/ og inneholder en annen enkelt skråstrek, bruker release/*/*du .) Hvis du legger til main som en grenregel, kan en gren kalt main også distribuere til miljøet.

  • Egendefinerte beskyttelsesregler for distribusjon. Du kan opprette egendefinerte beskyttelsesregler for gatedistribusjoner for å bruke partnertjenester. Du kan for eksempel bruke observerbarhetssystemer, endre administrasjonssystemer, kodekvalitetssystemer eller andre manuelle konfigurasjoner som du bruker til å vurdere beredskap og gi automatiserte godkjenninger for distribusjoner til GitHub.

    Når du har opprettet egendefinerte beskyttelsesregler for distribusjon og installert dem på et repositorium, kan du aktivere den egendefinerte distribusjonsbeskyttelsesregelen for alle miljøer i repositoriet.

    Skjermbilde som viser Innstillinger-siden for konfigurasjon av Miljø1 med alternativer for korrekturlesere, ventetid, egendefinerte regler og grenbegrensninger.

Merk deg

Hvis du har en GitHub Free-, GitHub Pro- eller GitHub-teamplan, er projeksjonsreglene for miljødistribusjon bare tilgjengelige for offentlige repositorier. bortsett fra regler for gren- og kodebeskyttelse. For brukere som har GitHub Pro- eller GitHub-teamplaner, er avdelings- og merkebeskyttelsesregler også tilgjengelige for private repositorier.

Skript i arbeidsflyten

I eksemplene på den foregående arbeidsflytsnutten brukes nøkkelordet run til å skrive ut en tekststreng. Fordi nøkkelordet run forteller jobben å utføre en kommando på løperen, bruker du nøkkelordet run til å kjøre handlinger eller skript.

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

I dette eksemplet bruker du npm til å installere bats programvaretestpakken ved hjelp run av nøkkelordet. Du kan også kjøre et skript som en handling. Du kan lagre skriptet i repositoriet, ofte gjort i en .github/scripts/ katalog, og deretter angi banen og skalltypen ved hjelp av nøkkelordet run.

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