Skip to main content

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

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

Сведения о синтаксисе 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 является обязательным и не имеет значения по умолчанию.

Примечание. Рабочие процессы, использующие, required: true не будут автоматически возвращать ошибку, если входные данные не указаны для событий, которые автоматически активируют рабочий процесс. Если вы задаете required: true в файле рабочего процесса и используете workflow_dispatch для выполнения рабочего процесса вручную, вам потребуется указать входные данные для GitHub.com. Дополнительные сведения см. в разделе События, инициирующие рабочие процессы.

Файлы рабочего процесса, использующие это действие, могут использовать 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>. Если преобразование не происходит, вы можете изменить эти вводы вручную.

Чтобы получить доступ к переменной среды в действии контейнера 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.

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

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

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, следуйте этим рекомендациям, упорядоченным по предпочтительности:

  1. Задокументируйте обязательные аргументы в README действия и опустите их из инструкции CMD.
  2. Используйте значения по умолчанию, позволяющие использовать действие без указания args.
  3. Если действие предоставляет флаг --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'

branding.color

Цвет фона индикатора. Это может быть: white, yellow, blue, green, orange, red, purple или gray-dark.

branding.icon

Имя используемого значка Feather версии 4.28.0.

Пропущенные значки

Значки фирменной символики и все перечисленные ниже значки опущены.

  • кофе;
  • столбцы
  • 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
  • Закат
  • 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