Примечание. В GitHub Enterprise Server в настоящее время не поддерживаются средства выполнения тестов, размещенные в GitHub. Дополнительные сведения о планируемой поддержке в будущем см. в GitHub public roadmap.
Общие сведения о командах рабочего процесса
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 }}"
В следующей таблице перечислены функции набора средств, которые доступны в рабочем процессе:
Функция набора средств | Аналогичная команда рабочего процесса |
---|---|
core.addPath | Доступно с помощью файла среды GITHUB_PATH |
core.debug | debug |
core.notice | notice |
core.error | error |
core.endGroup | endgroup |
core.exportVariable | Доступно с помощью файла среды GITHUB_ENV |
core.getInput | Доступно с помощью переменной среды INPUT_{NAME} |
core.getState | Доступно с помощью переменной среды STATE_{NAME} |
core.isDebug | Доступно с помощью переменной среды RUNNER_DEBUG |
Задание параметра вывода
Задает параметр вывода действия.
::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}
Параметр | Значение |
---|---|
title | Настраиваемый заголовок |
file | имя_файла |
col | Номер столбца, начиная с 1 |
endColumn | Номер конечного столбца |
line | Номер строки, начиная с 1 |
endLine | Номер конечной строки |
Пример: задание сообщения уведомления
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}
Параметр | Значение |
---|---|
title | Настраиваемый заголовок |
file | имя_файла |
col | Номер столбца, начиная с 1 |
endColumn | Номер конечного столбца |
line | Номер строки, начиная с 1 |
endLine | Номер конечной строки |
Пример: задание сообщения предупреждения
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}
Параметр | Значение |
---|---|
title | Настраиваемый заголовок |
file | имя_файла |
col | Номер столбца, начиная с 1 |
endColumn | Номер конечного столбца |
line | Номер строки, начиная с 1 |
endLine | Номер конечной строки |
Пример: задание сообщения об ошибке
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"
Предупреждение. Прежде чем выводить секрет в журналы сборки или использовать его в других командах рабочего процесса, необходимо зарегистрировать секрет с помощью add-mask.
Пример: маскирование переменной среды
Если вы введете в журнале переменную 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. В один файл можно записать несколько команд, разделенных новыми строками.
В большинстве команд в следующих примерах используются двойные кавычки для повторения строк, которые будут пытаться интерполировать символы, например $
для имен переменных оболочки. Чтобы всегда использовать литеральные значения в строках с кавычками, можно использовать одинарные кавычки.
Примечание. В PowerShell версии 5.1 и более ранних (shell: powershell
) не используется UTF-8 по умолчанию, поэтому необходимо указать кодировку UTF-8. Пример:
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 по умолчанию. Пример:
jobs:
powershell-core-example:
runs-on: windows-latest
steps:
- shell: pwsh
run: |
"mypath" >> $env:GITHUB_PATH
Указание переменной среды
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
. Шаг, на котором переменная среды создается или обновляется, не будет иметь доступа к новому значению, но доступ получат все последующие шаги в задании. Имена переменных среды задаются с учетом регистра и могут содержать знаки препинания. Дополнительные сведения см. в разделе Переменные среды.
Пример
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: |
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: |
"JSON_RESPONSE<<EOF" >> $env:GITHUB_ENV
(Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
"EOF" >> $env:GITHUB_ENV
shell: pwsh
Добавление сводки по заданию
echo "{markdown content}" >> $GITHUB_STEP_SUMMARY
"{markdown content}" >> $env:GITHUB_STEP_SUMMARY
Для каждого задания можно задать пользовательский Markdown, который будет отображаться на странице сводок о выполнении рабочего процесса. С помощью сводок по заданиям можно отображать и группировать уникальное содержимое, например сводки по результатам тестов, чтобы при просмотре результатов выполнения рабочего процесса пользователю не приходилось открывать журналы для получения важной информации, такой как сбои.
Сводки по заданиям поддерживают Markdown для GitHub, и содержимое Markdown можно добавить в файл среды GITHUB_STEP_SUMMARY
для каждого шага. GITHUB_STEP_SUMMARY
является уникальным для каждого шага задания. Дополнительные сведения о файлах для каждого шага, на которые ссылается GITHUB_STEP_SUMMARY
, см. в разделе "Файлы среды".
При завершении задания сводки по всем шагам группируются в единую сводку по заданию и отображаются на странице сводок о выполнении рабочего процесса. Если сводки создаются несколькими заданиями, они сортируются по времени завершения задания.
Пример
echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY
"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY
Многострочное содержимое Markdown
Для поддержки многострочного содержимого Markdown можно использовать >>
, чтобы непрерывно добавлять содержимое на текущем шаге. С каждой операцией добавления автоматически вставляется символ новой строки.
Пример
- name: Generate list using Markdown
run: |
echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY
- name: Generate list using Markdown
run: |
"This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY
"" >> $env:GITHUB_STEP_SUMMARY # this is a blank line
"- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY
"- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY
"- How about a third one?" >> $env:GITHUB_STEP_SUMMARY
Перезапись сводок по заданиям
Для очистки всего содержимого на текущем шаге можно использовать >
, чтобы перезаписать ранее добавленное содержимое.
Пример
- name: Overwrite Markdown
run: |
echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY
echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY
- name: Overwrite Markdown
run: |
"Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY
"There was an error, we need to clear the previous Markdown with some new content." > $env:GITHUB_STEP_SUMMARY
Удаление сводок по заданиям
Чтобы окончательно удалить сводку по текущему шагу, можно удалить файл, на который ссылается GITHUB_STEP_SUMMARY
.
Пример
- name: Delete all summary content
run: |
echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY
rm $GITHUB_STEP_SUMMARY
- name: Delete all summary content
run: |
"Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY
rm $env:GITHUB_STEP_SUMMARY
После завершения шага сводки по заданиям отправляются, и последующие шаги не могут изменить ранее отправленное содержимое Markdown. В сводках автоматически маскируются все секреты, которые могли в них случайно попасть. Если сводка по заданию содержит конфиденциальную информацию, которую необходимо удалить, можно удалить запуск рабочего процесса, чтобы удалить все его сводки. Дополнительные сведения см. в статье "Удаление запуска рабочего процесса".
Разделение и ограничения шагов
Сводки по заданиям разделяются между шагами, а размер каждого шага не может превышать 1 МиБ. Разделение между шагами применяется для того, чтобы потенциально поврежденный Markdown одного шага не мог прервать вывод Markdown последующих шагов. Если для шага добавлено более 1 МиБ содержимого, отправка завершится сбоем и будет создана заметка об ошибке. Сбои отправки для сводок по заданиям не влияют на общее состояние шага или задания. Для каждого задания отображается не более 20 пошаговых сводок.
Добавление системного пути
Добавляет каталог к системной переменной PATH
и автоматически открывает к ней доступ всем последующим действиям в текущем задании, кроме выполняемого в настоящий момент действия. Чтобы просмотреть определенные на текущий момент пути для задания, можно использовать echo "$PATH"
в шаге или действии.
echo "{path}" >> $GITHUB_PATH
"{path}" >> $env:GITHUB_PATH
Пример
В этом примере показывается, как добавить пользовательский каталог $HOME/.local/bin
в PATH
:
echo "$HOME/.local/bin" >> $GITHUB_PATH
В этом примере показывается, как добавить пользовательский каталог $env:HOMEPATH/.local/bin
в PATH
:
"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH