Skip to main content

Команды рабочего процесса для GitHub Actions

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

Общие сведения о командах рабочего процесса

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

Большинство команд рабочего процесса используют команду echo в определенном формате, остальные вызываются путем записи в файл. Дополнительные сведения см. в разделе Файлы среды.

Пример

Shell
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
pwsh
Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"

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

Предупреждение. Если вы работаете с командной строкой, при использовании команд рабочего процесса не ставьте двойные кавычки (").

Использование команд рабочего процесса для доступа к возможностям набора средств

В actions/toolkit содержится ряд функций, которые можно выполнять как команды рабочего процесса. Используйте синтаксис ::, чтобы выполнить команды рабочего процесса в файле YAML. Затем они отправляются в средство выполнения через stdout. Например, вместо использования кода для задания выходных данных, как показано ниже:

JavaScript
core.setOutput('SELECTED_COLOR', 'green');

Пример: задание значения

Можно воспользоваться командой set-output в рабочем процессе, чтобы задать то же значение:

YAML
      - name: Set selected color
        run: echo '::set-output name=SELECTED_COLOR::green'
        id: random-color-generator
      - name: Get color
        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"
YAML
      - name: Set selected color
        run: Write-Output "::set-output name=SELECTED_COLOR::green"
        id: random-color-generator
      - name: Get color
        run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

В следующей таблице перечислены функции набора средств, которые доступны в рабочем процессе:

Функция набора средствАналогичная команда рабочего процесса
core.addPathДоступно с помощью файла среды GITHUB_PATH
core.debugdebug
core.noticenotice
core.errorerror
core.endGroupendgroup
core.exportVariableДоступно с помощью файла среды GITHUB_ENV
core.getInputДоступно с помощью переменной среды INPUT_{NAME}
core.getStateДоступно с помощью переменной среды STATE_{NAME}
core.isDebugДоступно с помощью переменной среды RUNNER_DEBUG

Задание параметра вывода

Задает параметр вывода действия.

Code
::set-output name={name}::{value}

При необходимости можно также объявить параметры вывода в файле метаданных действия. Дополнительные сведения см. в разделе Синтаксис метаданных для GitHub Actions.

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

Пример: задание параметра вывода

Shell
echo "::set-output name=action_fruit::strawberry"
pwsh
Write-Output "::set-output name=action_fruit::strawberry"

Задание сообщения отладки

Записывает сообщение отладки в журнал. Чтобы просмотреть в журнале сообщения отладки, заданные этой командой, необходимо создать секрет под названием ACTIONS_STEP_DEBUG со значением true. Дополнительные сведения см. в статье "Включение ведения журнала отладки".

Code
::debug::{message}

Пример: задание сообщения отладки

Shell
echo "::debug::Set the Octocat variable"
pwsh
Write-Output "::debug::Set the Octocat variable"

Задание сообщения уведомления

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

Code
::notice file={name},line={line},endLine={endLine},title={title}::{message}
ПараметрЗначение
titleНастраиваемый заголовок
fileимя_файла
colНомер столбца, начиная с 1
endColumnНомер конечного столбца
lineНомер строки, начиная с 1
endLineНомер конечной строки

Пример: задание сообщения уведомления

Shell
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Задание сообщения предупреждения

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

Code
::warning file={name},line={line},endLine={endLine},title={title}::{message}
ПараметрЗначение
titleНастраиваемый заголовок
fileимя_файла
colНомер столбца, начиная с 1
endColumnНомер конечного столбца
lineНомер строки, начиная с 1
endLineНомер конечной строки

Пример: задание сообщения предупреждения

Shell
echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Задание сообщения об ошибке

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

Code
::error file={name},line={line},endLine={endLine},title={title}::{message}
ПараметрЗначение
titleНастраиваемый заголовок
fileимя_файла
colНомер столбца, начиная с 1
endColumnНомер конечного столбца
lineНомер строки, начиная с 1
endLineНомер конечной строки

Пример: задание сообщения об ошибке

Shell
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Группировка строк журнала

Создает группу с возможностью развертывания в журнале. Чтобы создать группу, воспользуйтесь командой group и укажите title. Любые данные, которые вы введете между командами group и endgroup, будут вложены в расширяемую запись журнала.

Code
::group::{title}
::endgroup::

Пример: группировка строк журнала

YAML
jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"
YAML
jobs:
  powershell-example:
    runs-on: windows-latest
    steps:
      - name: Group of log lines
        run: |
            Write-Output "::group::My title"
            Write-Output "Inside group"
            Write-Output "::endgroup::"

Свертываемая группа в журнале выполнения рабочего процесса

Маскирование значения в журнале

Code
::add-mask::{value}

Маскирование значения предотвращает запись строки или переменной в журнал. Каждое замаскированное слово, отделенное пробелом, заменяется символом *. Для value маски можно использовать переменную среды или строку. Когда вы маскируете значение, оно обрабатывается как секрет и будет скрыто в средстве выполнения. Например, после маскирования значения вы не сможете задать его в качестве выходных данных.

Пример: маскирование строки

Если вы введете в журнале "Mona The Octocat", вы увидите "***".

Shell
echo "::add-mask::Mona The Octocat"
pwsh
Write-Output "::add-mask::Mona The Octocat"

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

Пример: маскирование переменной среды

Если вы введете в журнале переменную MY_NAME или значение "Mona The Octocat", вы увидите "***" вместо "Mona The Octocat".

YAML
jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"
YAML
jobs:
  powershell-example:
    runs-on: windows-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: powershell-version
        run: Write-Output "::add-mask::$env:MY_NAME"

Остановка и запуск команд рабочего процесса

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

Code
::stop-commands::{endtoken}

Чтобы остановить обработку команд рабочего процесса, передайте stop-commands уникальный маркер. Чтобы возобновить обработку команд рабочего процесса, передайте тот же маркер, с помощью которого вы остановили обработку.

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

Code
::{endtoken}::

Пример: остановка и запуск команд рабочего процесса

YAML
jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: Disable workflow commands
        run: |
          echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          stopMarker=$(uuidgen)
          echo "::stop-commands::$stopMarker"
          echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          echo "::$stopMarker::"
          echo '::warning:: This is a warning again, because stop-commands has been turned off.'
YAML
jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: Disable workflow commands
        run: |
          Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          $stopMarker = New-Guid
          Write-Output "::stop-commands::$stopMarker"
          Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          Write-Output "::$stopMarker::"
          Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'

Отображение выходных данных команд

Включает или отключает отображение команд рабочего процесса. Например, если вы используете в рабочем процессе команду set-output, она задаст параметр вывода, но сама команда не будет отображаться в журнале выполнения рабочего процесса. Если включить отображение команд, в журнале появятся команды, например ::set-output name={name}::{value}.

Code
::echo::on
::echo::off

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

Команды add-mask, debug, warning и error не поддерживают отображение, поскольку их выходные данные уже выводятся в журнале.

Также можно включить глобальное отображение команд, включив пошаговое ведение журнала отладки с помощью секрета ACTIONS_STEP_DEBUG. Дополнительные сведения см. в статье "Включение ведения журнала отладки". Напротив, команда рабочего процесса echo позволяет включить более детальное отображение команд вместо его включения для каждого рабочего процесса в репозитории.

Пример: переключение отображения команд

YAML
jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: toggle workflow command echoing
        run: |
          echo '::set-output name=action_echo::disabled'
          echo '::echo::on'
          echo '::set-output name=action_echo::enabled'
          echo '::echo::off'
          echo '::set-output name=action_echo::disabled'
YAML
jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: toggle workflow command echoing
        run: |
          write-output "::set-output name=action_echo::disabled"
          write-output "::echo::on"
          write-output "::set-output name=action_echo::enabled"
          write-output "::echo::off"
          write-output "::set-output name=action_echo::disabled"

В примере выше в журнал записываются следующие строки:

Code
::set-output name=action_echo::enabled
::echo::off

Только вторая команда set-output и команда echo записываются в журнал, потому что отображение команд было включено во время их выполнения. Параметр вывода задается во всех случаях, даже если он не всегда отображается.

Отправка значений в предварительные и завершающие действия

С помощью save-state команды можно создать переменные среды для совместного pre: использования с действиями или post: рабочими процессами. Например, можно создать файл действием pre:, передать расположение файла действию main:, а затем использовать действие post: для удаления файла. Также можно создать файл действием main:, передать его расположение действию post: и с помощью этого же действия post: удалить файл.

Если у вас несколько pre: действий или post: , доступ к сохраненному значению можно получить только в действии, где save-state было использовано. Дополнительные сведения о действиях типа post: см. в статье "Синтаксис метаданных для GitHub Actions".

Команда save-state может выполняться только в рамках действия и недоступна для файлов YAML. Сохраненное значение хранится в виде значения среды с префиксом STATE_.

В этом примере для выполнения save-state команды используется JavaScript. Итоговая переменная среды называется STATE_processID со значением 12345:

JavaScript
console.log('::save-state name=processID::12345')

Затем переменная STATE_processID становится доступной только скрипту очистки, который выполняется в рамках действия main. Этот пример выполняется в main и использует JavaScript для отображения значения, назначенного переменной среды STATE_processID:

JavaScript
console.log("The running PID from the main action is: " +  process.env.STATE_processID);

Файлы среды

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

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

Примечание. В PowerShell версии 5.1 и более ранних (shell: powershell) не используется UTF-8 по умолчанию, поэтому необходимо указать кодировку UTF-8. Пример:

YAML
jobs:
  legacy-powershell-example:
    runs-on: windows-latest
    steps:
      - shell: powershell
        run: |
          "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

В PowerShell Core версии 6 и более поздних (shell: pwsh) используется кодировка UTF-8 по умолчанию. Пример:

YAML
jobs:
  powershell-core-example:
    runs-on: windows-latest
    steps:
      - shell: pwsh
        run: |
          "mypath" >> $env:GITHUB_PATH

Указание переменной среды

Shell
echo "{environment_variable_name}={value}" >> $GITHUB_ENV
  • С PowerShell версии 6 и более поздних:

    pwsh
    "{environment_variable_name}={value}" >> $env:GITHUB_ENV
  • С PowerShell версии 5.1 и более ранних:

    powershell
    "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append

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

Пример

YAML
steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> $GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      echo "${{ env.action_state }}" # This will output 'yellow'
YAML
steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" >> $env:GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      Write-Output "${{ env.action_state }}" # This will output 'yellow'

Многострочные строки

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

Code
{name}<<{delimiter}
{value}
{delimiter}

Предупреждение. Убедитесь, что используемый разделитель создается случайным образом и является уникальным для каждого запуска. Дополнительные сведения см. в разделе "Основные сведения о риске вставки данных в скрипты".

Пример

В этом примере в качестве разделителя используется EOF, а переменной среды JSON_RESPONSE задается значение ответа curl.

YAML
steps:
  - name: Set the value in bash
    id: step_one
    run: |
      echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
      curl https://example.com >> $GITHUB_ENV
      echo 'EOF' >> $GITHUB_ENV
YAML
steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      "JSON_RESPONSE<<EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "EOF" >> $env:GITHUB_ENV
    shell: pwsh

Добавление системного пути

Добавляет каталог к системной переменной PATH и автоматически открывает к ней доступ всем последующим действиям в текущем задании, кроме выполняемого в настоящий момент действия. Чтобы просмотреть определенные на текущий момент пути для задания, можно использовать echo "$PATH" в шаге или действии.

Shell
echo "{path}" >> $GITHUB_PATH
pwsh
"{path}" >> $env:GITHUB_PATH

Пример

В этом примере показывается, как добавить пользовательский каталог $HOME/.local/bin в PATH:

Shell
echo "$HOME/.local/bin" >> $GITHUB_PATH

В этом примере показывается, как добавить пользовательский каталог $env:HOMEPATH/.local/bin в PATH:

pwsh
"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH