Настроювання робочого циклу за допомогою змінних середовища

8 хв.

У цій одиниці ви дізнаєтеся, як настроювати поведінку, пов'язані з середовищем, і керувати нею за допомогою змінних, контекстів і настроюваних сценаріїв у робочих циклах Дій GitHub.

Щоб реалізувати цей процес, ви дізнаєтеся, як це зробити:

Використовуйте стандартні та настроювані змінні середовища.
Доступ до контекстних відомостей у робочих циклах.
Установлення змінних середовища в різних областях робочого циклу.
Використовуйте настроювані сценарії з ключовим словом запуску.
Застосування захисту навколишнього середовища для розгортання.

Змінні та контексти середовища за промовчанням

У робочому циклі GitHub Actions доступні кілька змінних середовища за замовчуванням, але лише в середовищі бігуна, який виконує завдання. Ці змінні за замовчуванням чутливі до регістра, і вони посилаються на значення конфігурації для системи та поточного користувача. Радимо використовувати ці змінні середовища за замовчуванням, щоб посилатися на файлову систему, а не використовувати жорстко закодовані шляхи до файлів. Щоб використовувати змінну середовища за промовчанням, укажіть $, а потім – ім'я змінної середовища.

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

Окрім змінних середовища за замовчуванням, можна використовувати визначені змінні як контексти. Контексти та змінні за замовчуванням схожі в тому, що вони обидва надають доступ до відомостей про середовище, але мають деякі важливі відмінності. Хоча стандартні змінні середовища можна використовувати лише в середовищі бігуна, ви можете використовувати змінні контексту в будь-який момент робочого циклу. Наприклад, контекстні змінні дають змогу виконати інструкцію if, щоб обчислити вираз перед виконанням бігуна.

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"

У цьому прикладі використовується контекст github.ref, щоб перевірити гілку, яка ініціює робочий цикл. Якщо це гілка main, виконується бігун і друкується фраза "Deploying to production server on branch $GITHUB_REF" (Розгортання на сервері виробництва на гілці $GITHUB_REF). Змінна $GITHUB_REF середовища за промовчанням використовується в бігуні для посилання на гілку. Зверніть увагу, що стандартні змінні середовища – це всі великі регістри, де контекстні змінні мають усі малі регістри.

Контекстна інформація, доступна в робочому циклі

Використовуйте контексти для доступу до відомостей про запуски робочих циклів, змінні, середовища бігунів, завдання та кроки. Кожен контекст – це об'єкт, який містить властивості, які можуть бути іншими об'єктами або рядками. Доступні контексти: github, env, vars, jobjobs, steps, runner, secrets, strategy, matrix, needsі inputs.

У таблиці нижче наведено контексти та описи робочих циклів:

Контекст	Опис
`github`	Відомості про запуск робочого циклу. Докладні відомості див `github` . в статті Контекст.
`env`	Містить змінні, установлені в робочому циклі, робочому циклі або на кроці. Докладні відомості див `env` . в статті Контекст.
`vars`	Містить змінні, установлені на рівні сховища, організації або середовища. Докладні відомості див `vars` . в статті Контекст.
`job`	Відомості про поточне поточне завдання. Докладні відомості див `job` . в статті Контекст.
`jobs`	Лише для робочих циклів для повторного використання містить результати завдань із робочого циклу для повторного використання. Докладні відомості див `jobs` . в статті Контекст.
`steps`	Відомості про кроки, які виконайте в поточному робочому місці. Докладні відомості див `steps` . в статті Контекст.
`runner`	Відомості про бігуна, який виконує поточне завдання. Докладні відомості див `runner` . в статті Контекст.
`secrets`	Містить імена та значення секретів, доступних для запуску робочого циклу. Докладні відомості див `secrets` . в статті Контекст.
`strategy`	Відомості про стратегію виконання матриці для поточного завдання. Докладні відомості див `strategy` . в статті Контекст.
`matrix`	Містить властивості матриці, визначені в робочому циклі, які застосовуються до поточного завдання. Докладні відомості див `matrix` . в статті Контекст.
`needs`	Містить результати всіх завдань, визначених як залежність поточного завдання. Докладні відомості див `needs` . в статті Контекст.
`inputs`	Містить входи робочого циклу, який можна використовувати повторно або вручну. Докладні відомості див `inputs` . в статті Контекст.

Різні контексти доступні в різний час під час запуску робочого циклу. Наприклад, контекст можна використовувати secrets лише в певних місцях завдання. Крім того, деякі функції, наприклад hashFiles функцію, можна використовувати лише в певних місцях.

У таблиці нижче наведено обмеження для кожного контексту та спеціальної функції в робочому циклі. Перелічені контексти доступні лише для вказаного ключа робочого циклу. Ви не можете використовувати їх деінде. Функцію можна використовувати будь-де, якщо вона не відображається в таблиці нижче.

Клавіша робочого циклу	Контекст	Спеціальні функції
`run-name`	`github`, , `inputsvars`	Ніхто
`concurrency`	`github`, , `inputsvars`	Ніхто
`env`	`github`, , `secrets`, `inputsvars`	Ніхто
`jobs.<job_id>.concurrency`	`github`, , `needs`, `strategymatrixinputs`,`vars`	Ніхто
`jobs.<job_id>.container`	`github`, , `needs`, `strategymatrixvars`,`inputs`	Ніхто
`jobs.<job_id>.container.credentials`	`github`, `needs`, `strategy`, `matrixenvvarssecretsinputs`	Ніхто
`jobs.<job_id>.container.env.<env_id>`	`github`, `needs`, `strategy`, `matrix`, `jobrunner`, , `env`, `varssecrets`,`inputs`	Ніхто
`jobs.<job_id>.container.image`	`github`, , `needs`, `strategymatrixvars`,`inputs`	Ніхто
`jobs.<job_id>.continue-on-error`	`github`, , `needs`, `strategyvarsmatrix`,`inputs`	Ніхто
`jobs.<job_id>.defaults.run`	`github`, `needs`, `strategy`, `matrix`, `env`, , `vars`, `inputs`	Ніхто
`jobs.<job_id>.env`	`github`, `needs`, `strategy`, `matrix`, `vars`, , `secrets`, `inputs`	Ніхто
`jobs.<job_id>.environment`	`github`, , `needs`, `strategymatrixvars`,`inputs`	Ніхто
`jobs.<job_id>.environment.url`	`github`, `needs`, `strategy`, `matrix`, `jobrunner`, , `env`, `varssteps`,`inputs`	Ніхто
`jobs.<job_id>.if`	`github`, , `needs`, `varsinputs`	`always`, , `canceled`, `successfailure`
`jobs.<job_id>.name`	`github`, , `needs`, `strategymatrixvars`,`inputs`	Ніхто
`jobs.<job_id>.outputs.<output_id>`	`github`, , , `needs`, , , , `strategy`, , `matrix`, `job`, `runnerenvvarssecretsstepsinputs`	Ніхто
`jobs.<job_id>.runs-on`	`github`, , `needs`, `strategymatrixvars`,`inputs`	Ніхто
`jobs.<job_id>.secrets.<secrets_id>`	`github`, `needs`, `strategy`, `matrix`, `secrets`, , `inputs`, `vars`	Ніхто
`jobs.<job_id>.services`	`github`, , `needs`, `strategymatrixvars`,`inputs`	Ніхто
`jobs.<job_id>.services.<service_id>.credentials`	`github`, `needs`, `strategy`, `matrixenvvarssecretsinputs`	Ніхто
`jobs.<job_id>.services.<service_id>.env.<env_id>`	`github`, `needs`, `strategy`, `matrix`, `jobrunner`, , `env`, `varssecrets`,`inputs`	Ніхто
`jobs.<job_id>.steps.continue-on-error`	`github`, , , `needs`, , , , `strategy`, , `matrix`, `job`, `runnerenvvarssecretsstepsinputs`	Геш-файли
`jobs.<job_id>.steps.env`	`github`, , , `needs`, , , , `strategy`, , `matrix`, `job`, `runnerenvvarssecretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.if`	`github`, `needs`, `strategy`, `matrix`, `jobrunner`, , `env`, `varssteps`,`inputs`	`always`, `canceled`, `success`, , `failure`, `hashFiles`
`jobs.<job_id>.steps.name`	`github`, , , `needs`, , , , `strategy`, , `matrix`, `job`, `runnerenvvarssecretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.run`	`github`, , , `needs`, , , , `strategy`, , `matrix`, `job`, `runnerenvvarssecretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.timeout-minutes`	`github`, , , `needs`, , , , `strategy`, , `matrix`, `job`, `runnerenvvarssecretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.with`	`github`, `needs`, `strategy`, `matrixjob`, , `runner`, env, `vars`, `secrets`, , `steps`,`inputs`	`hashFiles`
`jobs.<job_id>.steps.working-directory`	`github`, `needs`, `strategy`, `matrixjob`, , `runner`, env, `vars`, `secrets`, , `steps`,`inputs`	`hashFiles`
`jobs.<job_id>.strategy`	`github`, потребує, `vars`, , `inputs`,	Ніхто
`jobs.<job_id>.timeout-minutes`	`github`, , `needs`, `strategymatrixvars`,`inputs`	Ніхто
`jobs.<job_id>.with.<with_id>`	`github`, , `needs`, `strategymatrixinputs`,`vars`	Ніхто
`on.workflow_call.inputs.<inputs_id>.default`	`github`, , `inputsvars`	Ніхто
`on.workflow_call.outputs.<output_id>.value`	`github`, завдання, `vars`, `inputs`	Ніхто

Настроювані змінні середовища

Подібно до використання змінних середовища за замовчуванням, у файлі робочого циклу можна використовувати настроювані змінні середовища. Щоб створити настроювану змінну, потрібно визначити її у файлі робочого циклу за допомогою контексту env. Якщо потрібно використовувати значення змінної середовища в середовищі бігуна, можна використовувати звичайний метод операційної системи runner для читання змінних середовища.

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

Установлення настроюваних змінних середовища в робочому циклі

Ви можете визначити змінні середовища, які мають область для всього робочого циклу, використовуючи env файл робочого циклу на верхньому рівні. Область вмісту завдання в робочому циклі за допомогою jobs.<job_id>.env. Змінну середовища можна обмежити на певному кроці завдання за допомогою .jobs.<job_id>.steps[*].env

Ось приклад, який показує всі три сценарії у файлі робочого циклу:

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

Використання контексту за замовчуванням у робочому циклі

Платформа GitHub встановлює стандартні змінні середовища. Вони не визначаються в робочому циклі, але в робочому циклі можна використовувати змінну середовища за промовчанням у відповідному контексті. Більшість цих змінних, крім CI, починаються з GITHUB_* або RUNNER_*. Два останні типи не можна перезаписати. Крім того, ці змінні за промовчанням мають відповідну та аналогічно названу контекстну властивість. Наприклад, RUNNER_* ряд стандартних змінних має відповідну контекстну властивість runner.*.

Ось приклад того, як отримати доступ до змінних за замовчуванням у робочому циклі, застосувавши такі методи:

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

Докладні відомості див. в статті Змінні середовища за промовчанням.

Передавання настроюваних змінних середовища до робочого циклу

Ви можете передати настроювані змінні середовища від одного кроку завдання робочого циклу до подальших кроків у межах завдання. Створіть значення на одному кроці завдання та призначте значення наявній або новій змінні середовища. Потім запишіть пару змінних або значень до файлу середовища GITHUB_ENV. Файл середовища можна використовувати в дії або з команди оболонки в робочому циклі за допомогою ключового run слова.

Крок, на якому створюється або оновлюється змінна середовища, не має доступу до нового значення, але всі наступні кроки в роботі мають доступ.

Ось приклад:

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'

Додавання захисту навколишнього середовища

Ви можете додати правила захисту для середовищ, визначених для сховища GitHub.

Щоб додати середовище, у сховищі виконайте наведені нижче дії.

Виберіть Настройки.
В області ліворуч виберіть пункт Середовище.
Натисніть кнопку Створити середовище , щоб додати та настроїти середовище та додати захист.

Про середовища

Використовуйте середовища для опису загального цільового розгортання, наприклад виробництва, постановки або розробки. Коли робочий цикл Дій GitHub розгортається в середовищі, середовище з'являється на головній сторінці сховища. Ви можете використовувати середовища, щоб вимагати затвердження завдання, щоб продовжити, обмежити, які гілки можуть ініціювати робочий цикл, розгортання воріт за допомогою спеціальних правил захисту від розгортання або обмежити доступ до секретів.

Кожне завдання в робочому циклі може посилатися на одне середовище. Усі правила захисту, установлені для середовища, мають пройти, перш ніж завдання, яке посилається на середовище, надсилається бігуну. Завдання може отримати доступ до секретів середовища лише після того, як завдання буде надіслано бігуну.

Коли робочий цикл посилається на середовище, середовище з'являється в розгортаннях сховища.

Правила захисту навколишнього середовища

Правила захисту від розгортання середовища вимагають виконання певних умов, перш ніж завдання, яке посилається на середовище. За допомогою правил захисту від розгортання можна вимагати ручного затвердження, затримки завдання або обмеження середовища на певні гілки. Ви також можете створювати та впроваджувати спеціальні правила захисту на базі програм GitHub, щоб використовувати партнерські системи для керування розгортаннями, які посилаються на середовища, налаштовані на GitHub.

Ось пояснення цих правил захисту:

Обов'язкові правила захисту рецензентів. Використовуйте це правило, щоб вимагати від певного користувача або групи затверджувати завдання робочого циклу, які посилаються на середовище. Як рецензентів можна рахувати до шести користувачів або команд. Рецензенти мають мати принаймні дозволи на читання сховища. Щоб продовжити, потрібно затвердити завдання лише одного обов'язкового рецензента.

Крім того, ви можете заборонити самостійно переглядати розгортання в захищеному середовищі. Якщо ввімкнути цей параметр, користувачі, які ініціюють розгортання, не можуть затвердити завдання розгортання, навіть якщо вони є обов'язковим рецензентом. Увімкнувши самостійні огляди, це гарантує, що кілька користувачів переглядає розгортання в захищених середовищах.

Докладні відомості про перегляд завдань, які посилаються на середовище з потрібними рецензентами, див. в статті Перевірка розгортання.
Правила проекції таймера очікування. За допомогою правила захисту таймера очікування можна відкласти завдання на певний час після того, як завдання спочатку спрацьовує до завершення розгортання середовища. Час (у хвилинах) має бути цілим числом від 1 до 43 200 (30 днів). Час очікування не враховується до оплачуваного часу.
Правила захисту від гілок і тегів. Ви можете використовувати правила розгортання гілки та захисту тегів, щоб обмежити, які гілки та теги використовуються для розгортання в середовищі. У вас є кілька варіантів для розгортання гілки та правила захисту тегів для середовища.
- Жодне обмеження не встановлює жодних обмежень на розгортання гілки або тега в середовищі.
- Захищені гілки дають змогу розгортати лише гілки з увімкненими правилами захисту від гілок у середовищі. Якщо для будь-якої гілки в сховищі не визначено правила захисту від гілок, усі гілки можуть розгортатися. Параметр Selected branches and tags забезпечує розгортання в середовищі лише гілок і тегів, які відповідають указаним шаблонам імен.
- Якщо вказати releases/* як гілку розгортання або правило тега, лише гілку або тег з іменем, що починається з releases/ , можна розгорнути в середовищі. (Символи узагальнення не збігаються . / Щоб зіставити гілки або позначки, які починаються з release/ однієї скіски та містять іншу скісну риску, використовуйте release/*/*.) Якщо додати main як правило гілки, гілку main також можна розгорнути в середовищі.
Настроювані правила захисту від розгортання. Ви можете створити спеціальні правила захисту для розгортання воріт для використання партнерських служб. Наприклад, ви можете використовувати системи спостережуваності, системи керування змінами, системи якості коду або інші ручні конфігурації, які використовуються для оцінки готовності та надання автоматизованих затверджень для розгортання в GitHub.

Створивши спеціальні правила захисту від розгортання та інсталювавши їх у сховищі, ви можете ввімкнути спеціальне правило захисту розгортання для будь-якого середовища в сховищі.

Нотатка

Якщо у вас є план GitHub Free, GitHub Pro або GitHub Team, правила проектування розгортання середовища доступні лише для загальнодоступних сховищ; крім правил захисту від гілок і позначок. Для користувачів, які мають плани GitHub Pro або GitHub Team, правила захисту від гілок і тегів також доступні для приватних репозиторіїв.

Сценарії в робочому циклі

У попередніх прикладах фрагмента робочого циклу ключове слово run використовується для друку рядка тексту. Оскільки ключове слово run використовується для виконання команди на бігуні, для виконання дій або сценаріїв використовується ключове слово run.

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

У цьому прикладі npm використовується для інсталяції пакета тестування програмного bats забезпечення за допомогою ключового run слова. Ви також можете запустити сценарій як дію. Ви можете зберегти сценарій у сховищі, часто виконаному в каталозі .github/scripts/, а потім ввести шлях і тип оболонки за допомогою ключового слова run.

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

Зворотний зв’язок

Чи була ця сторінка корисна?