Настройка рабочего процесса с помощью переменных среды

8 мин

В этом уроке вы узнаете, как настроить и управлять поведением среды с помощью переменных, контекстов и пользовательских скриптов в рабочих процессах GitHub Actions.

Чтобы реализовать этот процесс, вы узнаете, как:

Используйте переменные среды по умолчанию и настраиваемые переменные среды.
Доступ к контекстной информации в рабочих процессах.
Задайте переменные среды в разных областях рабочего процесса.
Используйте пользовательские скрипты с ключевым словом run.
Применение защиты среды для развертываний.

Переменные среды по умолчанию и контексты

В рабочем процессе 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, агент выполняется и выводит сообщение "Развертывание на продуктовый сервер в ветви $GITHUB_REF". Переменная окружения по умолчанию $GITHUB_REF используется агентом для ссылки на ветвь. Обратите внимание, что все переменные среды по умолчанию пишутся прописными буквами, а переменные контекста — строчными.

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

Используйте контексты для доступа к сведениям о запусках рабочих процессов, переменных, средах выполнения, заданиях и шагах. Каждый контекст — это объект, содержащий свойства, которые могут быть другими объектами или строками. Доступные контексты включают github, env, vars, job, jobs, 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`, , `needsstrategymatrixinputs`,`vars`	Отсутствует
`jobs.<job_id>.container`	`github`, , `needsstrategymatrixvars`,`inputs`	Отсутствует
`jobs.<job_id>.container.credentials`	`github`, `needs`, `strategymatrixenvvarssecretsinputs`	Отсутствует
`jobs.<job_id>.container.env.<env_id>`	`github`, `needs`, `strategymatrixjobrunnerenvvarssecretsinputs`	Отсутствует
`jobs.<job_id>.container.image`	`github`, , `needsstrategymatrixvars`,`inputs`	Отсутствует
`jobs.<job_id>.continue-on-error`	`github`, , `needsstrategyvarsmatrix`,`inputs`	Отсутствует
`jobs.<job_id>.defaults.run`	`github`, `needs`, `strategymatrixenvvarsinputs`	Отсутствует
`jobs.<job_id>.env`	`github`, `needs`, `strategymatrixvarssecretsinputs`	Отсутствует
`jobs.<job_id>.environment`	`github`, , `needsstrategymatrixvars`,`inputs`	Отсутствует
`jobs.<job_id>.environment.url`	`github`, `needs`, `strategymatrixjobrunnerenvvarsstepsinputs`	Отсутствует
`jobs.<job_id>.if`	`github`, `needs`, , `varsinputs`	`always`, `canceled`, , `successfailure`
`jobs.<job_id>.name`	`github`, , `needsstrategymatrixvars`,`inputs`	Отсутствует
`jobs.<job_id>.outputs.<output_id>`	`github`, `needs`, `strategymatrixjobrunnerenvvarssecretsstepsinputs`	Отсутствует
`jobs.<job_id>.runs-on`	`github`, , `needsstrategymatrixvars`,`inputs`	Отсутствует
`jobs.<job_id>.secrets.<secrets_id>`	`github`, `needs`, `strategymatrixsecretsinputsvars`	Отсутствует
`jobs.<job_id>.services`	`github`, , `needsstrategymatrixvars`,`inputs`	Отсутствует
`jobs.<job_id>.services.<service_id>.credentials`	`github`, `needs`, `strategymatrixenvvarssecretsinputs`	Отсутствует
`jobs.<job_id>.services.<service_id>.env.<env_id>`	`github`, `needs`, `strategymatrixjobrunnerenvvarssecretsinputs`	Отсутствует
`jobs.<job_id>.steps.continue-on-error`	`github`, `needs`, `strategymatrixjobrunnerenvvarssecretsstepsinputs`	хэширование файлов
`jobs.<job_id>.steps.env`	`github`, `needs`, `strategymatrixjobrunnerenvvarssecretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.if`	`github`, `needs`, `strategymatrixjobrunnerenvvarsstepsinputs`	`always`, `canceled`, , `success`, `failurehashFiles`
`jobs.<job_id>.steps.name`	`github`, `needs`, `strategymatrixjobrunnerenvvarssecretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.run`	`github`, `needs`, `strategymatrixjobrunnerenvvarssecretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.timeout-minutes`	`github`, `needs`, `strategymatrixjobrunnerenvvarssecretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.with`	`github`, `needs`, `strategymatrixjobrunner`env, `vars`, , , `secretsstepsinputs`	`hashFiles`
`jobs.<job_id>.steps.working-directory`	`github`, `needs`, `strategymatrixjobrunner`env, `vars`, , , `secretsstepsinputs`	`hashFiles`
`jobs.<job_id>.strategy`	`github`, потребности, `vars`, `inputs`	Отсутствует
`jobs.<job_id>.timeout-minutes`	`github`, , `needsstrategymatrixvars`,`inputs`	Отсутствует
`jobs.<job_id>.with.<with_id>`	`github`, , `needsstrategymatrixinputs`,`vars`	Отсутствует
`on.workflow_call.inputs.<inputs_id>.default`	`github`, , `inputsvars`	Отсутствует
`on.workflow_call.outputs.<output_id>.value`	`github`, задания, `vars`, `inputs`	Отсутствует

Пользовательские переменные среды

Аналогично использованию переменных среды по умолчанию можно использовать и пользовательские переменные среды в файле рабочего процесса. Чтобы создать пользовательскую переменную, необходимо определить ее в файле рабочего процесса с помощью контекста env. Если вы хотите использовать значение переменной среды в средстве выполнения, то для чтения переменных среды можно использовать стандартный метод операционной системы средства выполнения.

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 Actions развертывается в среде, среда отображается на главной странице репозитория. Вы можете использовать среды для того, чтобы требовать утверждения для выполнения задания, ограничивать, какие ветви могут запускать рабочий процесс, управлять развертываниями с помощью пользовательских правил защиты развертывания или ограничивать доступ к конфиденциальной информации.

Каждое задание в рабочем процессе может ссылаться на одну среду. Все правила защиты, установленные для среды, должны быть соблюдены, прежде чем задание, ссылающееся на эту среду, будет отправлено исполнителю. Задание может получить доступ к секретам среды только после отправки задания в средство выполнения.

Когда рабочий процесс ссылается на среду, среда отображается в развертываниях репозитория.

Правила защиты среды

Правила защиты развертывания среды требуют, чтобы определенные условия были выполнены, прежде чем задание, ссылающееся на среду, начнет выполняться. Правила защиты развертывания можно использовать, чтобы требовать ручного утверждения, задерживать задачу или ограничивать среду для определённых веток. Вы также можете создавать и реализовывать пользовательские правила защиты с использованием приложений GitHub, чтобы управлять развертываниями, которые ссылаются на среды, настроенные в GitHub.

Ниже приведено описание этих правил защиты:

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

Кроме того, вы можете предотвратить самостоятельные проверки для развертываний в защищенной среде. Если этот параметр включен, пользователи, инициирующие развертывание, не могут утвердить задание развертывания, даже если они обязательный рецензент. Включив самостоятельные проверки, это гарантирует, что несколько пользователей проверяют развертывания в защищенных средах.

Дополнительные сведения о проверке заданий, ссылающихся на среду с необходимыми рецензентами, см. в разделе "Просмотр развертываний".
Правила проекции таймера ожидания. Правило защиты таймера ожидания можно использовать для задержки задания на определенное время после его первоначального запуска, прежде чем начнется развертывание среды. Время (в минутах) должно быть целым числом от 1 до 43 200 (30 дней). Время ожидания не учитывается в счете.
Правила защиты ветвей и тегов. Вы можете использовать правила защиты ветви развертывания и тегов, чтобы ограничить, какие ветви и теги используются для развертывания в среде. Существует несколько вариантов использования ветвей развертывания и правил защиты тегов для среды.
- Без ограничений на какие ветви или теги можно развернуть в среде.
- Только защищенные ветки позволяют развертывать в среде исключительно ветки с включенными правилами защиты веток. Если правила защиты ветви не определены ни для одной ветви в репозитории, то могут развертываться все ветви. Выбранные ветви и теги обеспечивают развертывание в среде только ветвей и тегов, которые соответствуют заданным шаблонам имен.
- Если вы указываете 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

Обратная связь

Были ли сведения на этой странице полезными?