Dostosowywanie przepływu pracy za pomocą zmiennych środowiskowych

Ukończone

W tej lekcji dowiesz się, jak skonfigurować zachowanie specyficzne dla środowiska i zarządzać nim przy użyciu zmiennych, kontekstów i skryptów niestandardowych w przepływach pracy funkcji GitHub Actions.

Aby zaimplementować ten proces, dowiesz się, jak wykonywać następujące czynności:

• Użyj domyślnych i niestandardowych zmiennych środowiskowych.
• Uzyskaj dostęp do informacji kontekstowych w przepływach pracy.
• Ustaw zmienne środowiskowe w różnych zakresach przepływu pracy.
• Użyj skryptów niestandardowych ze słowem kluczowym run.
• Stosowanie ochrony środowiska dla wdrożeń.

Domyślne zmienne środowiskowe i konteksty

W przepływie pracy GitHub Actions dostępnych jest kilka domyślnych zmiennych środowiskowych, ale tylko w runnerze realizującym zadanie. Te zmienne domyślne są wrażliwe na wielkość liter i odnoszą się do wartości konfiguracji systemu i bieżącego użytkownika. Zalecamy używanie tych domyślnych zmiennych środowiskowych do odwoływania się do systemu plików, a nie używania zakodowanych na sztywno ścieżek plików. Aby użyć domyślnej zmiennej środowiskowej, określ $ nazwę zmiennej środowiskowej.

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

Oprócz domyślnych zmiennych środowiskowych można użyć zdefiniowanych zmiennych jako kontekstów. Konteksty i zmienne domyślne są podobne, ponieważ zapewniają dostęp do informacji o środowisku, ale mają pewne istotne różnice. Mimo że domyślne zmienne środowiskowe mogą być używane tylko w module uruchamiającym, można używać zmiennych kontekstowych w dowolnym momencie przepływu pracy. Na przykład zmienne kontekstowe umożliwiają uruchamianie if instrukcji w celu obliczenia wyrażenia przed wykonaniem modułu uruchamiającego.

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"

W tym przykładzie github.ref używany jest kontekst do sprawdzania gałęzi, która wyzwoliła przepływ pracy. Jeśli gałąź to main, moduł uruchamiający jest wykonywany i wyświetla komunikat "Deploying to production server on branch $GITHUB_REF" (Wdrażanie na serwerze produkcyjnym w gałęzi $GITHUB_REF). Domyślna zmienna środowiskowa $GITHUB_REF jest używana w module uruchamiającym odwołania do gałęzi. Zwróć uwagę, że domyślne zmienne środowiskowe są wielkimi literami, w których wszystkie zmienne kontekstowe są małymi literami.

Informacje kontekstowe dostępne w przepływie pracy

Użyj kontekstów, aby uzyskać dostęp do informacji o procesach pracy, zmiennych, środowiskach runnera, zadaniach i krokach. Każdy kontekst jest obiektem zawierającym właściwości, które mogą być innymi obiektami lub ciągami. Dostępne konteksty obejmują github, env, vars, job, jobs, steps, runner, secrets, strategy, matrix, needs i inputs.

W poniższej tabeli wymieniono konteksty i opisy przepływu pracy:

Kontekst	Opis
github	Informacje o przebiegu przepływu pracy. Aby uzyskać więcej informacji, zobacz github kontekst.
env	Zawiera zmienne ustawione w przepływie pracy, zadaniu lub kroku. Aby uzyskać więcej informacji, zobacz env kontekst.
vars	Zawiera zmienne ustawione na poziomie repozytorium, organizacji lub środowiska. Aby uzyskać więcej informacji, zobacz vars kontekst.
job	Informacje o aktualnie uruchomionym zadaniu. Aby uzyskać więcej informacji, zobacz job kontekst.
jobs	Tylko w przypadku przepływów pracy wielokrotnego użytku zawiera dane wyjściowe zadań z przepływu pracy wielokrotnego użytku. Aby uzyskać więcej informacji, zobacz jobs kontekst.
steps	Informacje o krokach uruchomionych w obecnym zadaniu. Aby uzyskać więcej informacji, zobacz steps kontekst.
runner	Informacje na temat wykonawcy uruchamiającego bieżące zadanie. Aby uzyskać więcej informacji, zobacz runner kontekst.
secrets	Zawiera nazwy i wartości sekretów, które są dostępne dla uruchomienia przepływu pracy. Aby uzyskać więcej informacji, zobacz secrets kontekst.
strategy	Informacje na temat strategii wykonywania macierzy dla obecnego zadania. Aby uzyskać więcej informacji, zobacz strategy kontekst.
matrix	Zawiera właściwości macierzy zdefiniowane w przepływie pracy, które mają zastosowanie do bieżącego zadania. Aby uzyskać więcej informacji, zobacz matrix kontekst.
needs	Zawiera dane wyjściowe wszystkich zadań zdefiniowanych jako zależność bieżącego zadania. Aby uzyskać więcej informacji, zobacz needs kontekst.
inputs	Zawiera dane wejściowe przepływu pracy wielokrotnego użytku lub wyzwalane ręcznie. Aby uzyskać więcej informacji, zobacz inputs kontekst.

Różne konteksty są dostępne w różnych momentach w przebiegu przepływu pracy. Można na przykład użyć secrets kontekstu tylko w określonych miejscach w zadaniu. Ponadto możesz użyć niektórych funkcji, takich jak hashFiles funkcja, tylko w określonych miejscach.

W poniższej tabeli wymieniono ograniczenia dotyczące każdego kontekstu i specjalnej funkcji w przepływie pracy. Wymienione konteksty są dostępne tylko dla wskazanego klucza przepływu pracy. Nie można ich używać nigdzie indziej. Możesz użyć funkcji w dowolnym miejscu, chyba że jest ona wymieniona w poniższej tabeli.

Klucz przepływu pracy	Kontekst	Funkcje specjalne
run-name	github, inputs, vars	Żaden
concurrency	github, inputs, vars	Żaden
env	github, , secrets, , inputsvars	Żaden
jobs.<job_id>.concurrency	github, , needs, strategy, matrix, , inputsvars	Żaden
jobs.<job_id>.container	github, , needs, strategy, matrix, , varsinputs	Żaden
jobs.<job_id>.container.credentials	github, needs, strategy, matrix, env, vars, secrets, inputs	Żaden
jobs.<job_id>.container.env.<env_id>	github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs	Żaden
jobs.<job_id>.container.image	github, , needs, strategy, matrix, , varsinputs	Żaden
jobs.<job_id>.continue-on-error	github, , needs, strategy, vars, , matrixinputs	Żaden
jobs.<job_id>.defaults.run	github, needs, , strategy, matrix, env, , varsinputs	Żaden
jobs.<job_id>.env	github, needs, , strategy, matrix, vars, , secretsinputs	Żaden
jobs.<job_id>.environment	github, , needs, strategy, matrix, , varsinputs	Żaden
jobs.<job_id>.environment.url	github, needs, strategy, matrix, job, runner, env, vars, steps, inputs	Żaden
jobs.<job_id>.if	github, , needs, , varsinputs	always, , canceled, , successfailure
jobs.<job_id>.name	github, , needs, strategy, matrix, , varsinputs	Żaden
jobs.<job_id>.outputs.<output_id>	github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	Żaden
jobs.<job_id>.runs-on	github, , needs, strategy, matrix, , varsinputs	Żaden
jobs.<job_id>.secrets.<secrets_id>	github, needs, , strategy, matrix, secrets, , inputsvars	Żaden
jobs.<job_id>.services	github, , needs, strategy, matrix, , varsinputs	Żaden
jobs.<job_id>.services.<service_id>.credentials	github, needs, strategy, matrix, env, vars, secrets, inputs	Żaden
jobs.<job_id>.services.<service_id>.env.<env_id>	github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs	Żaden
jobs.<job_id>.steps.continue-on-error	github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.env	github, needs, strategy, 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, , failurehashFiles
jobs.<job_id>.steps.name	github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.run	github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.timeout-minutes	github, needs, strategy, 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, wymaga, vars, inputs	Żaden
jobs.<job_id>.timeout-minutes	github, , needs, strategy, matrix, , varsinputs	Żaden
jobs.<job_id>.with.<with_id>	github, , needs, strategy, matrix, , inputsvars	Żaden
on.workflow_call.inputs.<inputs_id>.default	github, inputs, vars	Żaden
on.workflow_call.outputs.<output_id>.value	github, zadania, vars, inputs	Żaden

Niestandardowe zmienne środowiskowe

Podobnie jak w przypadku używania domyślnych zmiennych środowiskowych, możesz użyć niestandardowych zmiennych środowiskowych w pliku przepływu pracy. Aby utworzyć zmienną niestandardową, należy zdefiniować ją w pliku przepływu pracy przy użyciu env kontekstu. Jeśli chcesz użyć wartości zmiennej środowiskowej wewnątrz modułu uruchamiającego, możesz użyć normalnej metody systemu operacyjnego modułu uruchamiającego do odczytywania zmiennych środowiskowych.

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

Ustawianie niestandardowych zmiennych środowiskowych w przepływie pracy

Zmienne środowiskowe, które są ograniczone do całego przepływu pracy, można zdefiniować przy użyciu env na najwyższym poziomie pliku przepływu pracy. Określ zakres zawartości zadania w przepływie pracy za pomocą jobs.<job_id>.env. Można określić zakres zmiennej środowiskowej w określonym kroku zadania przy użyciu polecenia jobs.<job_id>.steps[*].env.

Oto przykład pokazujący wszystkie trzy scenariusze w pliku przepływu pracy:

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

Używanie kontekstu domyślnego w przepływie pracy

Platforma GitHub ustawia domyślne zmienne środowiskowe. Nie są one zdefiniowane w przepływie pracy, ale można użyć domyślnej zmiennej środowiskowej w przepływie pracy w odpowiednim kontekście. Większość tych zmiennych, innych niż CI, zaczyna się od GITHUB_* lub RUNNER_*. Nie można zastąpić dwóch ostatnich typów. Ponadto te zmienne domyślne mają odpowiadającą i podobnie nazwaną właściwość kontekstu. Na przykład seria RUNNER_* zmiennych domyślnych ma zgodną właściwość kontekstu runner.*.

Oto przykład sposobu uzyskiwania dostępu do zmiennych domyślnych w przepływie pracy przez zastosowanie następujących metod:

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

Aby uzyskać więcej informacji, zobacz Domyślne zmienne środowiskowe.

Przekazywanie niestandardowych zmiennych środowiskowych do przepływu pracy

Niestandardowe zmienne środowiskowe można przekazać z jednego kroku zadania przepływu pracy do kolejnych kroków w ramach zadania. Wygeneruj wartość w jednym kroku zadania i przypisz wartość do istniejącej lub nowej zmiennej środowiskowej. Następnie należy zapisać parę zmiennej/wartości w pliku środowiska GITHUB_ENV. Możesz użyć pliku środowiska w akcji lub w poleceniu powłoki w zadaniu przepływu pracy, używając słowa kluczowego run.

Krok, który tworzy lub aktualizuje zmienną środowiskową, nie ma dostępu do nowej wartości, ale wszystkie kolejne kroki w zadaniu mają dostęp.

Oto przykład:

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'

Dodawanie ochrony środowiska

Możesz dodać reguły ochrony dla środowisk zdefiniowanych dla repozytorium GitHub.

Aby dodać środowisko do swojego repozytorium:

1. Wybierz Ustawienia.

   

2. W okienku po lewej stronie wybierz pozycję Środowisko.

   

3. Wybierz przycisk Nowe środowisko , aby dodać i skonfigurować środowisko oraz dodać ochronę.

   

Informacje o środowiskach

Użyj środowisk, aby opisać ogólny cel wdrożenia, taki jak produkcja, etapowanie lub opracowywanie. Gdy przepływ pracy funkcji GitHub Actions zostanie wdrożony w środowisku, środowisko zostanie wyświetlone na stronie głównej repozytorium. Możesz używać środowisk, aby wymagać zatwierdzenia realizacji zadania, ograniczać, które gałęzie mogą uruchamiać przepływ pracy, kontrolować wdrożenia używając niestandardowych reguł zabezpieczających lub ograniczyć dostęp do tajemnic.

Każde zadanie w przepływie pracy może odwoływać się do jednego środowiska. Wszystkie reguły ochrony ustawione dla środowiska muszą zostać przekazane przed wysłaniem zadania odwołującego się do środowiska do modułu uruchamiającego. Zadanie może uzyskiwać dostęp do tajemnic środowiska dopiero po wysłaniu zadania do procesora.

Gdy przepływ pracy odwołuje się do środowiska, środowisko jest wyświetlane we wdrożeniach repozytorium.

Reguły ochrony środowiska

Reguły ochrony wdrożenia środowiska wymagają podania określonych warunków przed kontynuowaniem zadania, które odwołuje się do środowiska. Możesz użyć reguł ochrony wdrożenia, aby wymagać ręcznego zatwierdzania, opóźnić zadanie lub ograniczyć środowisko do określonych gałęzi. Można również tworzyć i implementować niestandardowe reguły ochrony obsługiwane przez usługę GitHub Apps, aby używać systemów partnerskich do kontrolowania wdrożeń, które odwołują się do środowisk skonfigurowanych w usłudze GitHub.

Oto wyjaśnienie tych reguł ochrony:

• Wymagane reguły ochrony recenzentów. Ta reguła umożliwia wymaganie od określonej osoby lub zespołu zatwierdzenia zadań przepływu pracy odwołujących się do środowiska. Możesz wyświetlić maksymalnie sześciu użytkowników lub zespołów jako recenzentów. Recenzenci muszą mieć co najmniej uprawnienia do odczytu do repozytorium. Aby kontynuować, zadanie musi zostać zatwierdzone przez jednego wymaganego recenzenta.

  Można również uniemożliwić samodzielne przeglądy wdrożeń w chronionym środowisku. Jeśli to ustawienie zostanie włączone, użytkownicy, którzy inicjują wdrożenie, nie będą mogli zatwierdzić zadania wdrożenia, nawet jeśli są wymaganymi recenzentami. Włączenie samodzielnych przeglądów zapewnia, że więcej niż jedna osoba przegląda wdrożenia w środowiskach chronionych.

  Aby uzyskać więcej informacji na temat przeglądania zadań odwołujących się do środowiska z wymaganymi recenzentami, zobacz Przeglądanie wdrożeń.

• Zasady projekcji timerów oczekiwania. Możesz użyć reguły ochrony czasomierza oczekiwania, aby opóźnić zadanie przez określony czas po początkowym wyzwoleniu zadania przed kontynuowaniem wdrażania środowiska. Czas (w minutach) musi być liczbą całkowitą z zakresu od 1 do 43 200 (30 dni). Czas oczekiwania nie liczy się w stosunku do rozliczanego czasu.

• Reguły ochrony gałęzi i tagów. Można użyć gałęzi wdrażania i reguł ochrony tagów, aby ograniczyć, które gałęzie i tagi są używane do wdrażania w środowisku. Istnieje kilka opcji dotyczących gałęzi wdrażania i reguł ochrony tagów dla środowiska.

  • Brak ograniczeń oznacza brak ograniczeń dotyczących tego, która gałąź lub tag mogą być wdrażane w środowisku.
  • Tylko chronione gałęzie pozwalają na wdrażanie do środowiska wyłącznie gałęzi z włączonymi regułami ochrony gałęzi. Jeśli żadne reguły ochrony gałęzi nie są zdefiniowane dla żadnej gałęzi w repozytorium, wszystkie gałęzie mogą zostać wdrożone. Ustawienie Wybrane gałęzie i tagi gwarantuje, że w środowisku mogą być wdrażane tylko gałęzie i tagi zgodne z określonymi wzorcami nazw.
  • Jeśli określisz releases/* jako gałąź wdrożenia lub regułę tagu, tylko gałąź lub tag o nazwie rozpoczynającej się od releases/ można wdrożyć w środowisku. (Symbole wieloznaczne nie pasują do /. Aby dopasować gałęzie lub tagi zaczynające się od release/ i zawierające kolejny pojedynczy ukośnik, użyj release/*/*.) Jeśli dodasz main jako regułę gałęzi, gałąź o nazwie main może również zostać wdrożona w środowisko.

• Niestandardowe reguły ochrony wdrożeń. Możesz utworzyć niestandardowe reguły ochrony, aby ograniczyć wdrożenia do korzystania z usług partnerskich. Można na przykład użyć systemów obserwacji, systemów zarządzania zmianami, systemów jakości kodu lub innych ręcznych konfiguracji używanych do oceny gotowości i zapewnienia zautomatyzowanych zatwierdzeń dla wdrożeń w usłudze GitHub.

  Po utworzeniu niestandardowych reguł ochrony wdrożenia i zainstalowaniu ich w repozytorium można włączyć niestandardową regułę ochrony wdrożenia dla dowolnego środowiska w repozytorium.

  

Uwaga / Notatka

Jeśli masz plan usługi GitHub Free, GitHub Pro lub GitHub Team, reguły projekcji wdrożenia środowiska są dostępne tylko dla repozytoriów publicznych; z wyjątkiem reguł ochrony gałęzi i tagów. W przypadku użytkowników, którzy mają plany usługi GitHub Pro lub GitHub Team, reguły ochrony gałęzi i tagów są również dostępne dla repozytoriów prywatnych.

Skrypty w przepływie pracy

W poprzednich przykładach run fragmentów kodu przepływu pracy słowo kluczowe jest używane do drukowania ciągu tekstu. run Ponieważ słowo kluczowe nakazuje zadaniu wykonanie polecenia w module uruchamiającym, słowo kluczowe służy run do uruchamiania akcji lub skryptów.

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

W tym przykładzie użyjesz narzędzia npm do zainstalowania bats pakietu testowania oprogramowania przy użyciu słowa kluczowego run . Możesz również uruchomić skrypt jako akcję. Skrypt można przechowywać w repozytorium, często wykonywany w .github/scripts/ katalogu, a następnie podać ścieżkę i typ powłoki przy użyciu słowa kluczowego run .

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