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

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

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

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

Пример команды рабочего процесса

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

echo "::set-output name=action_fruit::strawberry"

Write-Output "::set-output name=action_fruit::strawberry"

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

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

::debug::{message}

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

echo "::debug::Set the Octocat variable"

Write-Output "::debug::Set the Octocat variable"

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

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

::notice file={name},line={line},endLine={endLine},title={title}::{message}

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

echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

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

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

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

::warning file={name},line={line},endLine={endLine},title={title}::{message}

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

echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

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

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

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

::error file={name},line={line},endLine={endLine},title={title}::{message}

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

echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

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

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

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

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

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

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

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

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

::add-mask::{value}

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

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

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

echo "::add-mask::Mona The Octocat"

Write-Output "::add-mask::Mona The Octocat"

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

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

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

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"

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

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

::stop-commands::{endtoken}

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

::{endtoken}::

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

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

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

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

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

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

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

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

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'

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"

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

::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:

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

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

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

Файлы среды

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

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

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

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

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

echo "{environment_variable_name}={value}" >> $GITHUB_ENV

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

Пример записи переменной среды в GITHUB_ENV

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'

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'

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

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

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

Пример многостроковых строк

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

steps:
  - name: Set the value in bash
    id: step_one
    run: |
      EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
      echo "JSON_RESPONSE<<$EOF" >> $GITHUB_ENV
      curl https://example.com >> $GITHUB_ENV
      echo "$EOF" >> $GITHUB_ENV

steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      -join (1..15 | ForEach {[char]((48..57)+(65..90)+(97..122) | Get-Random)}) | set EOF
      "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" в шаге или действии.

echo "{path}" >> $GITHUB_PATH

"{path}" >> $env:GITHUB_PATH

Пример добавления системного пути

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

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