Переменные

Сведения о переменных

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

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

Пользовательскую переменную можно задать двумя способами.

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

Определение переменных среды для одного рабочего процесса

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

• Весь рабочий процесс с использованием 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

Доступ к значениям переменных можно получить env с помощью переменных среды средства выполнения или контекстов. В приведенном выше примере показаны три пользовательские переменные, используемые в качестве переменных среды в команде echo : $DAY_OF_WEEK, $Greetingи $First_Name. Значения для этих переменных задаются на уровне рабочего процесса, задания и шага соответственно. Дополнительные сведения о доступе к значениям переменных с помощью контекстов см. в разделе Использование контекстов для доступа к значениям переменных.

Так как интерполяция переменных среды средства выполнения выполняется после отправки задания рабочего процесса на компьютер средства выполнения, необходимо использовать соответствующий синтаксис для оболочки, используемой в средстве выполнения. В этом примере рабочим процессом указано ubuntu-latest. По умолчанию средства выполнения Linux используют оболочку Bash, поэтому необходимо использовать синтаксис $NAME. Если рабочим процессом указано средство выполнения Windows, используется синтаксис PowerShell, $env:NAME. Дополнительные сведения о оболочках см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Соглашения об именовании для переменных среды

При установке переменной среды нельзя использовать имена переменных среды по умолчанию. Полный список переменных среды по умолчанию см. в разделе Переменные среды по умолчанию ниже. При попытке переопределить значение одной из этих переменных по умолчанию назначение игнорируется.

Все новые переменные, которые указывают на расположение в файловой системе, должны иметь суффикс _PATH . Переменные GITHUB_ENV и GITHUB_WORKSPACE по умолчанию являются исключениями из этого соглашения.

Определение переменных конфигурации для нескольких рабочих процессов

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

Например, можно использовать переменные конфигурации, чтобы задать значения по умолчанию для параметров, передаваемых в средства сборки на уровне организации, но затем разрешить владельцам репозитория переопределять эти параметры в индивидуальном порядке.

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

Приоритет переменных конфигурации

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

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

Соглашения об именовании для переменных конфигурации

К именам переменных конфигурации применяются следующие правила:

• Имена могут содержать только буквенно-цифровые символы ([a-z], [A-Z], [0-9]) или символы подчеркивания (_). Пробелы недопустимы.
• Имена не должны начинаться GITHUB_ с префикса.
• Имена не должны начинаться с числа.
• В именах не учитывается регистр символов.
• Имена должны быть уникальными на уровне, на который они создаются.

Создание переменных конфигурации для репозитория

Чтобы создать секреты или переменные для репозитория личной учетной записи, необходимо быть владельцем репозитория. Чтобы создать секреты или переменные для репозитория организации, необходимо иметь admin доступ.

1. На GitHub.com перейдите на главную страницу репозитория. 1. Под именем репозитория щелкните Параметры. Если вкладка "Параметры" не отображается, выберите раскрывающееся меню и нажмите кнопку Параметры.

   1. В разделе "Безопасность" боковой панели выберите Секреты и переменные, , а затем щелкните Действия. 1. Перейдите на вкладку Переменные .

2. Щелкните Новая переменная репозитория.

3. В поле Имя введите имя переменной.

4. В поле Значение введите значение переменной.

5. Щелкните Добавить переменную.

Создание переменных конфигурации для среды

Чтобы создать секреты или переменные для среды в репозитории личная учетная запись, необходимо быть владельцем репозитория. Чтобы создать секреты или переменные для среды в репозитории организации, необходимо иметь admin доступ. Дополнительные сведения о средах см. в разделе Использование сред для развертывания.

1. На GitHub.com перейдите на главную страницу репозитория. 1. Под именем репозитория щелкните Параметры. Если вкладка "Параметры" не отображается, выберите раскрывающееся меню и нажмите кнопку Параметры.

   1. На левой боковой панели щелкните Среды.

2. Щелкните среду, в которую нужно добавить переменную.

3. В разделе Переменные среды щелкните Добавить переменную.

4. В поле Имя введите имя переменной.

5. В поле Значение введите значение переменной.

6. Щелкните Добавить переменную.

Создание переменных конфигурации для организации

При создании секрета или переменной в организации можно использовать политику для ограничения доступа по репозиторию. Например, можно предоставить доступ ко всем репозиториям или ограничить доступ только частными репозиториями или указанным списком репозиториев.

Чтобы создать секреты или переменные на уровне организации, у вас должен быть admin доступ.

1. На GitHub.com перейдите на главную страницу организации. 1. Под названием организации щелкните Параметры. Если вкладка "Параметры" не отображается, выберите раскрывающееся меню и щелкните Параметры.

   1. В разделе "Безопасность" боковой панели выберите Секреты и переменные, , а затем щелкните Действия. 1. Перейдите на вкладку Переменные .

   

2. Щелкните Новая переменная организации.

3. В поле Имя введите имя переменной.

4. В поле Значение введите значение переменной.

5. В раскрывающемся списке Доступ к репозиторию выберите политику доступа.

6. Щелкните Добавить переменную.

Ограничения для переменных конфигурации

Размер отдельных переменных ограничен 48 КБ.

Вы можете хранить до 1000 переменных организации, 500 переменных в репозитории и 100 переменных на среду. Общий совокупный размер переменных организации и репозитория составляет 256 КБ на выполнение рабочего процесса.

Рабочий процесс, созданный в репозитории, может получить доступ к следующему количеству переменных:

• До 500 переменных репозитория, если общий размер переменных репозитория меньше 256 КБ. Если общий размер переменных репозитория превышает 256 КБ, будут доступны только переменные репозитория, которые не превышают ограничение (как отсортированные в алфавитном порядке по имени переменной).
• До 1000 переменных организации, если общий размер переменных репозитория и организации меньше 256 КБ. Если общий размер переменных организации и репозитория превышает 256 КБ, будут доступны только переменные организации, которые не превышают это ограничение (после учета переменных репозитория и отсортированных в алфавитном порядке по имени переменной).
• До 100 переменных уровня среды.

Использование контекстов для доступа к значениям переменных

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

Получить доступ к значениям переменных среды можно с помощью контекста env и значений переменных конфигурации с помощью контекста vars .

Использование контекста env для доступа к значениям переменных среды

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

Переменные среды средства выполнения всегда интерполируются на компьютере средства выполнения. Однако части рабочего процесса обрабатываются с помощью GitHub Actions и не отправляются средству выполнения. Переменные среды нельзя использовать в этих частях файла рабочего процесса. Вместо этого можно использовать контексты. Например, условный объект if, определяющий, отправляется ли задание или шаг средству выполнения, всегда обрабатывается с помощью GitHub Actions. Контекст в условной if инструкции можно использовать для доступа к значению переменной.

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

В этом изменении предыдущего примера мы ввели условное if . Теперь шаг рабочего процесса выполняется только в том случае, если для DAY_OF_WEEK задано значение "Понедельник". Доступ к этому значению выполняется от условного оператора if с помощью env контекста.

Обычно используется env контекст или github для доступа к значениям переменных в частях рабочего процесса, которые обрабатываются перед отправкой заданий в средства выполнения.

Использование контекста vars для доступа к значениям переменных конфигурации

Доступ к переменным конфигурации можно получить в рабочем процессе с помощью vars контекста. Дополнительные сведения см. в разделе Контексты.

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

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

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : ${{ vars.REPOSITORY_VAR }}"
        echo "organization variable : ${{ vars.ORGANIZATION_VAR }}"
        echo "overridden variable : ${{ vars.OVERRIDE_VAR }}"
        echo "variable from shell environment : $env_var"

    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

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

Переменные среды по умолчанию, которые устанавливает GitHub, доступны для каждого шага в рабочем процессе.

Мы настоятельно рекомендуем использовать переменные для доступа к файловой системе, а не использовать жестко заданные пути к файлам. GitHub задает переменные для действий, которые будут использоваться во всех средах средств выполнения.

Обнаружение операционной системы

Вы можете написать один файл рабочего процесса, который можно использовать для разных операционных систем, используя переменную среды по умолчанию RUNNER_OS и соответствующее свойство контекста ${{ runner.os }}. Например, следующий рабочий процесс может быть успешно запущен, если вы изменили операционную систему с macos-latest на windows-latest без необходимости изменять синтаксис переменных среды, который различается в зависимости от оболочки, используемой средством выполнения.

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

В этом примере два оператора if проверяют свойство os контекста runner, чтобы определить операционную систему средства выполнения. Условные объекты if обрабатываются с помощью GitHub Actions, и средству выполнения отправляются только те шаги, для которых проверка разрешается в виде true. Здесь одна из проверок всегда будет иметь значение true, а другая — false, поэтому только один из этих шагов отправляется в средство выполнения. После отправки задания средству выполнения шаг выполняется и переменная среды в команде echo интерполируется с использованием соответствующего синтаксиса ($env:NAME для PowerShell в Windows и $NAME для bash и sh в Linux и MacOS). В этом примере оператор runs-on: macos-latest означает, что будет выполняться второй шаг.

Передача значений между шагами и заданиями в рабочем процессе

Если вы создаете значение в одном шаге задания, его можно использовать в последующих шагах того же задания, назначив значение существующей или новой переменной среды, а затем записав это значение в файл среды GITHUB_ENV. Файл среды может использоваться непосредственно действием или командой оболочкой в файле рабочего процесса с помощью ключевого слова run. Дополнительные сведения см. в разделе Команды рабочего процесса для GitHub Actions.

Если вы хотите передать значение из шага одного задания в рабочем процессе в шаг другого задания в рабочем процессе, можно определить значение как вывод задания. Затем вы можете ссылаться на этот вывод задания из шага другого задания. Дополнительные сведения см. в разделе Синтаксис рабочего процесса для GitHub Actions.