Синтаксис метаданных для GitHub Actions

Сведения о синтаксисе YAML для GitHub Actions

Для всех действий требуется файл метаданных. Файл метаданных должен иметь имя action.yml либо action.yaml. Данные в файле метаданных определяют вводы, выводы и конфигурацию запуска для вашего действия.

Файлы метаданных действий используют синтаксис YAML. Если вы еще не работали с YAML, прочитайте статью Изучение YAML за пять минут.

`name`

Обязательно Имя вашего действия. GitHub отображает name на вкладке Действия для визуальной идентификации действия в каждом задании.

`author`

Необязательно Имя автора действия.

`description`

Обязательно Краткое описание действия.

`inputs`

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

Пример. Указание вводов

В этом примере настраивается два входных данных: num-octocats и octocat-eye-color. Входные num-octocats данные не требуются и по умолчанию будут иметь значение 1. octocat-eye-color является обязательным и не имеет значения по умолчанию.

Note

Действия, использующиеся required: true , не будут автоматически возвращать ошибку, если входные данные не указаны.

Файлы рабочего процесса, использующие это действие, могут использовать ключевое with слово для задания входного значения octocat-eye-color. Дополнительные сведения о синтаксисе см. в with разделе "Синтаксис рабочего процесса для GitHub Actions".

inputs:
  num-octocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocat-eye-color:
    description: 'Eye color of the Octocats'
    required: true

При указании входных данных GitHub создает переменную среды для входных данных с именем INPUT_<VARIABLE_NAME>. Созданная переменная среды преобразует входные имена в прописные буквы и заменяет пробелы символами _.

Если действие написано с использованием composite, оно не получит автоматически INPUT_<VARIABLE_NAME>. С помощью составных действий можно использовать inputs Доступ к контекстной информации о запусках рабочих процессов для доступа к входным данным действия.

Чтобы получить доступ к переменной среды в действии контейнера Docker, необходимо передать ввод с помощью ключевого слова args в файл метаданных действия. Дополнительные сведения о файле метаданных действия для действий контейнера Docker см. в разделе "Создание действия контейнера Docker".

Например, если рабочий процесс определяет вводы num-octocats и octocat-eye-color, код действия может считывать значения вводов, используя переменные среды INPUT_NUM-OCTOCATS и INPUT_OCTOCAT-EYE-COLOR.

`inputs.<input_id>`

Обязательно Идентификатор string для связи с вводом. Значение <input_id> представляет собой карту метаданных вводов. <input_id> должен быть уникальным идентификатором в пределах объекта inputs. <input_id> должен начинаться с буквы или _ и может включать только буквенно-цифровые символы - или _.

`inputs.<input_id>.description`

Обязательно Описание string параметра ввода.

`inputs.<input_id>.required`

Необязательно Объект boolean, указывающий, требуется ли для действия параметр ввода. Установите значение true, если параметр является обязательным.

`inputs.<input_id>.default`

Необязательно Объект string, представляющий значение по умолчанию. Значение по умолчанию используется, если параметр ввода не указан в файле рабочего процесса.

`inputs.<input_id>.deprecationMessage`

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

`outputs` для контейнера Docker и действий JavaScript

Необязательно Параметры вывода позволяют объявлять данные, устанавливаемые действием. Действия, которые выполняются позже в рабочем процессе, могут использовать набор выходных данных в ранее запущенных действиях. Например, если у вас есть действие, выполняющее сложение двух вводов (x + y = z), это действие может вывести сумму (z) для использования другими действиями в качестве ввода.

Выходные данные представляют собой строки Юникода длиной не более 1 МБ. Общий объем выходных данных в выполнении рабочего процесса не может превышать 50 МБ.

Если вы не объявили вывод в файле метаданных действия, вы все равно можете установить выводы и использовать их в рабочем процессе. Дополнительные сведения о настройке выходных данных в действии см. в разделе "Команды рабочего процесса для GitHub Actions".

Пример. Объявление выводов для контейнера Docker и действий JavaScript

outputs:
  sum: # id of the output
    description: 'The sum of the inputs'

`outputs.<output_id>`

Обязательно Идентификатор string для связи с выводом. Значение <output_id> — это карта метаданных выводов. <output_id> должен быть уникальным идентификатором в пределах объекта outputs. <output_id> должен начинаться с буквы или _ и может включать только буквенно-цифровые символы - или _.

`outputs.<output_id>.description`

Обязательно Описание string параметра вывода.

`outputs` для составных действий

Необязательно outputs использует те же параметры, что outputs.<output_id> и outputs.<output_id>.description (см. outputs для контейнера Docker и действий JavaScript), но также включает маркер value.

Пример. Объявление выводов для составных действий

outputs:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
  using: "composite"
  steps:
    - id: random-number-generator
      run: echo "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      shell: bash

`outputs.<output_id>.value`

Обязательно Значение, с которым будет сопоставлен параметр вывода. Вы можете указать string или выражение с контекстом. Например, вы можете использовать контекст steps, чтобы установить value вывода равным выходному значению шага.

Дополнительные сведения об использовании синтаксиса контекста см. в разделе "Доступ к контекстной информации о запусках рабочих процессов".

`runs`

Обязательно Указывает на тип (действие JavaScript, составное действие или действие контейнера Docker), а также способ выполнения действия.

`runs` для действий JavaScript

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

Пример: использование Node.js v20

runs:
  using: 'node20'
  main: 'main.js'

`runs.using` для действий JavaScript

Обязательно Среда выполнения, используемая для выполнения кода, указанного в main.

Используйте node20 для Node.js версии 20.

`runs.main`

Обязательно Файл, содержащий код действия. Среда выполнения, указанная в using, выполняет этот файл.

`runs.pre`

Необязательно. Позволяет выполнять сценарий при запуске задания до начала действия main:. Например, вы можете использовать pre: для запуска необходимого сценария установки. Среда выполнения, указанная с синтаксисом using, выполнит этот файл. Действие pre: всегда выполняется по умолчанию, но вы можете переопределить его с помощью runs.pre-if.

В этом примере действие pre: запускает сценарий setup.js:

runs:
  using: 'node20'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

`runs.pre-if`

Необязательно Позволяет определить условия для выполнения действия pre:. Действие pre: будет выполняться только при выполнении условий в pre-if. Если значение не задано, то pre-if по умолчанию равно always(). В pre-if функции проверки состояния оценивают состояние задания, а не собственное состояние действия.

Обратите внимание, что контекст step недоступен, так как еще не выполнено ни одного шага.

В этом примере cleanup.js выполняется только в средствах выполнения на базе Linux:

  pre: 'cleanup.js'
  pre-if: runner.os == 'linux'

`runs.post`

Необязательно Позволяет запускать сценарий в конце задания после завершения действия main:. Например, вы можете использовать post: для завершения определенных процессов или удаления ненужных файлов. Среда выполнения, указанная с синтаксисом using, выполнит этот файл.

В этом примере действие post: запускает сценарий cleanup.js:

runs:
  using: 'node20'
  main: 'index.js'
  post: 'cleanup.js'

Действие post: всегда выполняется по умолчанию, но вы можете переопределить его с помощью post-if.

`runs.post-if`

Необязательно Позволяет определить условия для выполнения действия post:. Действие post: будет выполняться только при выполнении условий в post-if. Если значение не задано, то post-if по умолчанию равно always(). В post-if функции проверки состояния оценивают состояние задания, а не собственное состояние действия.

Например, этот cleanup.js будет выполняться только в средствах выполнения на базе Linux:

  post: 'cleanup.js'
  post-if: runner.os == 'linux'

`runs` для составных действий

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

`runs.using` для составных действий

Обязательно Укажите для этого значения 'composite'.

`runs.steps`

Обязательные действия, которые планируется выполнить в этом действии. Это могут быть шаги run или шаги uses.

`runs.steps[*].run`

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

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

В качестве альтернативы вы можете использовать $GITHUB_ACTION_PATH:

runs:
  using: "composite"
  steps:
    - run: $GITHUB_ACTION_PATH/script.sh
      shell: bash

Дополнительные сведения см. в разделе "Доступ к контекстной информации о запусках рабочих процессов".

`runs.steps[*].shell`

Необязательный элемент оболочки, в которой требуется выполнить команду. Вы можете использовать любую оболочку, указанную в разделеСинтаксис рабочего процесса для GitHub Actions. Обязательно, если задано run.

`runs.steps[*].if`

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

При использовании выражений в условном if режиме можно, при необходимости, опустить синтаксис выражения ${{ }}, так как GitHub Actions автоматически вычисляет условное if выражение как выражение. Однако это исключение не применяется везде.

Всегда следует использовать синтаксис выражения ${{ }}{% концевого выражения %} или экранировать с '', ""либо () когда выражение начинается с !, так как ! зарезервировано нотация в формате YAML. Например:

{% raw %}

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

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

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

Этот шаг выполняется, только если типом события является pull_request, а действием — unassigned.

steps:
  - run: echo This event is a pull request that had an assignee removed.
    if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}

Пример. Использование функций проверки состояния

my backup step запускается только в случае сбоя предыдущего шага составного действия. Дополнительные сведения см. в разделе Оценка выражений в рабочих процессах и действиях.

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

`runs.steps[*].name`

Необязательно Имя составного шага.

`runs.steps[*].id`

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

`runs.steps[*].env`

Необязательно Задает map переменных среды только для этого шага. Если вы хотите изменить переменную среды, хранящуюся в рабочем процессе, используйте echo "{name}={value}" >> $GITHUB_ENV в составном шаге.

`runs.steps[*].working-directory`

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

`runs.steps[*].uses`

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

Мы настоятельно рекомендуем вам включить версию используемого вами действия, указав номер ссылки на Git, SHA или тега Docker. Если вы не укажете версию, это может нарушить ваши рабочие процессы или вызвать непредвиденное поведение, когда владелец действия будет публиковать обновление.

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

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

runs:
  using: "composite"
  steps:
    # Reference a specific commit
    - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
    # Reference the major version of a release
    - uses: actions/checkout@v4
    # Reference a specific version
    - uses: actions/checkout@v4.2.0
    # Reference a branch
    - uses: actions/checkout@main
    # References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
    - uses: actions/aws/ec2@main
    # References a local action
    - uses: ./.github/actions/my-action
    # References a docker public registry action
    - uses: docker://gcr.io/cloud-builders/gradle
    # Reference a docker image published on docker hub
    - uses: docker://alpine:3.8

`runs.steps[*].with`

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

runs:
  using: "composite"
  steps:
    - name: My first step
      uses: actions/hello_world@main
      with:
        first_name: Mona
        middle_name: The
        last_name: Octocat

`runs` для действий контейнера Docker

Обязательно Настраивает образ, используемый для действия контейнера Docker.

Пример. Использование Dockerfile в репозитории

runs:
  using: 'docker'
  image: 'Dockerfile'

Пример. Использование общедоступного контейнера реестра Docker

runs:
  using: 'docker'
  image: 'docker://debian:stretch-slim'

`runs.using` для действий контейнера Docker

Обязательно Укажите для этого значения 'docker'.

`runs.pre-entrypoint`

Необязательно. Позволяет запустить сценарий до начала действия entrypoint. Например, вы можете использовать pre-entrypoint: для запуска необходимого сценария установки. GitHub Actions использует docker run для запуска этого действия и запускает сценарий в новом контейнере, использующем тот же базовый образ. Это означает, что состояние среды выполнения отличается от основного контейнера entrypoint и любые требуемые состояния должны быть доступны либо в рабочей области, либо в HOME, либо в виде переменной STATE_. Действие pre-entrypoint: всегда выполняется по умолчанию, но вы можете переопределить его с помощью runs.pre-if.

Среда выполнения, указанная с синтаксисом using, выполнит этот файл.

В этом примере действие pre-entrypoint: запускает сценарий setup.sh:

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  pre-entrypoint: 'setup.sh'
  entrypoint: 'main.sh'

`runs.image`

Обязательно. Образ Docker для использования в качестве контейнера для выполнения действия. Значение может быть именем базового образа Docker, локальным Dockerfile в вашем репозитории или общедоступным образом в Docker Hub или другом реестре. Чтобы добавить ссылку на Dockerfile, локальный для вашего репозитория, присвойте файлу имя Dockerfile и используйте путь, относительный для вашего файла метаданных действия. Приложение docker выполнит этот файл.

`runs.env`

Необязательно. Указывает сопоставление "ключ-значение" переменных среды для установки в среде контейнера.

`runs.entrypoint`

Необязательно Переопределяет параметр ENTRYPOINT Docker в Dockerfile или задает его, если он еще не был указан. Используйте entrypoint, если Dockerfile не указывает ENTRYPOINT или если необходимо переопределить инструкцию ENTRYPOINT. Если вы опустите entrypoint, команды, указанные в инструкции ENTRYPOINT Docker, будут выполняться. Инструкция Docker ENTRYPOINT имеет форму оболочки и форму exec. В документации по ENTRYPOINT Docker рекомендуется использовать форму exec инструкции ENTRYPOINT.

Дополнительные сведения о выполнении entrypoint см. в разделе "Поддержка Dockerfile для GitHub Actions".

`runs.post-entrypoint`

Необязательно Позволяет запустить сценарий очистки после завершения действия runs.entrypoint. GitHub Actions использует docker run для запуска этого действия. Поскольку GitHub Actions запускает сценарий внутри нового контейнера с использованием того же базового образа, состояние выполнения отличается от основного контейнера entrypoint. Вы можете получить доступ к любому нужному состоянию либо в рабочей области, либо в HOME, либо в виде переменной STATE_. Действие post-entrypoint: всегда выполняется по умолчанию, но вы можете переопределить его с помощью runs.post-if.

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  entrypoint: 'main.sh'
  post-entrypoint: 'cleanup.sh'

`runs.args`

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

args используются вместо инструкции CMD в Dockerfile. Если вы используете CMD в Dockerfile, следуйте этим рекомендациям, упорядоченным по предпочтительности:

Задокументируйте обязательные аргументы в README действия и опустите их из инструкции CMD.
Используйте значения по умолчанию, позволяющие использовать действие без указания args.
Если действие предоставляет флаг --help или что-то подобное, используйте его, чтобы действие документировало само себя.

Если вам нужно передать переменные среды в действие, убедитесь, что ваше действие запускает командную оболочку для выполнения подстановки переменных. Например, если для атрибута entrypoint задано значение "sh -c", args будет выполняться в командной оболочке. Или же, если ваш Dockerfile использует ENTRYPOINT для запуска той же команды ("sh -c"), args будет выполняться в командной оболочке.

Дополнительные сведения об использовании инструкции CMD с GitHub Actionsсм. в разделе "Поддержка Dockerfile для GitHub Actions".

Пример. Определение аргументов для контейнера Docker

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.greeting }}
    - 'foo'
    - 'bar'

`branding`

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

Пример. Настройка фирменной символики для действия

branding:
  icon: 'award'
  color: 'green'

кофе;
столбцы
divide-circle
divide-square
divide
frown
hexagon
key
meh
mouse-pointer
smile
планирования
x-octagon

Полный список всех поддерживаемых в настоящее время значков

действия
airplay
alert-circle
alert-octagon
alert-triangle
align-center
align-justify
align-left
align-right
привязка
aperture
archive
arrow-down-circle
arrow-down-left
arrow-down-right
arrow-down
arrow-left-circle
arrow-left
arrow-right-circle
arrow-right
arrow-up-circle
arrow-up-left
arrow-up-right
arrow-up
at-sign
award
bar-chart-2
bar-chart
battery-charging
батарея
bell-off
колокол
Bluetooth
bold
book-open
book
закладка
поле
briefcase
calendar
camera-off
camera
cast
check-circle
check-square
галочка
chevron-down
chevron-left
chevron-right
chevron-up
chevrons-down
chevrons-left
chevrons-right
chevrons-up
круг
буфер обмена
clock
cloud-drizzle
cloud-lightning
cloud-off
cloud-rain
cloud-snow
cloud
кодом
Команда
compass
copy
corner-down-left
corner-down-right
corner-left-down
corner-left-up
corner-right-down
corner-right-up
corner-up-left
corner-up-right
ЦП
credit-card
урожай
crosshair
database
удалить
disc
dollar-sign
download-cloud
загрузить
droplet
edit-2
edit-3
изменить
external-link
eye-off
eye
быстрое перемещение вперед
feather
file-minus
file-plus
file-text
файл
film
Фильтр
flag
folder-minus
folder-plus
папку
пожертвование
git-branch
git-commit
git-merge
git-pull-request
globe
grid
hard-drive
hash
headphones
heart
help-circle
home
Изображение
inbox
info
курсив
Слои
мобильных приложений
life-buoy
link-2
link
список
loader
lock
log-in
log-out
mail
map-pin
map
maximize-2
maximize
menu
message-circle
message-square
mic-off
микрофон
minimize-2
минимизировать
minus-circle
minus-square
minus
monitor
moon
more-horizontal
more-vertical
перенос
music
navigation-2
навигация
octagon
package
paperclip
pause-circle
pause
percent
phone-call
phone-forwarded
phone-incoming
phone-missed
phone-off
phone-outgoing
phone
pie-chart
play-circle
воспроизвести
plus-circle
plus-square
плюс
pocket
питание
принтер
radio
refresh-ccw
refresh-cw
repeat
откат назад
rotate-ccw
rotate-cw
rss
сохранение
scissors
search
отправить
server
параметры
share-2
общая папка
shield-off
shield
shopping-bag
shopping-cart
shuffle
sidebar
skip-back
skip-forward
slash
Ползунки
смартфон
спикер
square
звездочка
stop-circle
sun
sunrise
заход солнца
table
Android
тег
целевой объект
terminal
thermometer
thumbs-down
thumbs-up
toggle-left
toggle-right
trash-2
trash
trending-down
trending-up
треугольник
truck
телевидение
type
umbrella
подчеркнутый
разблокировано
upload-cloud
отправить
user-check
user-minus
user-plus
user-x
Пользователь
пользователей
video-off
видео
voicemail
volume-1
volume-2
volume-x
том
watch
wifi-off
wifi
wind
x-circle
x-square
x
zap-off
zap
zoom-in
zoom-out

Синтаксис метаданных для GitHub Actions

В этой статье