Публикация пользовательского действия GitHub

Завершено

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

Выберите расположение действия

При создании действия важно сначала решить, где должно жить это действие, и видимость этого действия, будь то public или private. Видимость действия определяет, какие рекомендации и требования необходимы для выпуска этого действия. Давайте подробнее рассмотрим эти два варианта видимости.

Общедоступный

Рабочие процессы в любом репозитории могут использовать общедоступные действия. Если вы разрабатываете действие с намерением сделать его открытый код или сделать его общедоступным через GitHub Marketplace, мы рекомендуем (и в большинстве случаев это необходимо), чтобы действие было собственным репозиторием вместо того, чтобы обработать его с другим кодом приложения. Это позволяет выполнять версию, отслеживать и выпускать действие так же, как и любой другой фрагмент программного обеспечения. Это упрощает обнаружение действия в сообществе GitHub, ограничивает область базы кода для разработчиков, устраняющих проблемы и расширяющих действие, а также отделяет управление версиями от версий другого кода приложения.

Private

Если действие находится в частном репозитории, только рабочие процессы в одном репозитории могут использовать это действие. В случае частных действий можно хранить файлы действий в любом расположении в репозитории. Если вы планируете объединить действия, рабочий процесс и код приложения в одном репозитории, рекомендуется сохранить действие в каталоге .github . Например, .github/actions/action-a и .github/actions/action-b.

Документирование действия

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

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

• подробное описание того, что делает действие;
• обязательные входные и выходные аргументы;
• необязательные входные и выходные аргументы;
• секреты, используемые действием;
• переменные среды, используемые действием;
• пример использования действия в рабочем процессе.

Как правило, файл README.md должен содержать все, что пользователь должен знать для использования действия. Если вы считаете какую-то информацию полезной, включите ее в README.md.

Выпуск и управление версиями действия

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

Рекомендации по управлению выпусками и версиями

Хорошая стратегия управления выпусками должна включать рекомендации по управлению версиями. Пользователи не должны ссылаться на ветвь по умолчанию действия с действием. Это связано с тем, что ветвь по умолчанию, которая, скорее всего, содержит последний код (который может быть или не стабильным), может привести к нарушению рабочего процесса. Вместо этого рекомендуется, чтобы пользователи указывали основную версию при использовании действия с перенаправлением к более конкретной версии только при возникновении проблем. Это можно сделать, настроив рабочий процесс GitHub Actions для назначения тега, SHA фиксации или определенной ветви с именем выпуска. Рассмотрим эти варианты выпуска подробнее.

Теги

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

• Создайте и проверьте выпуск в ветви выпуска (например, release/v1) перед созданием тега выпуска (например, v1.0.2).
• Используйте семантическое управление версиями.
• Перемещайте тег основной версии (например v1, v2) чтобы указать ссылку на Git текущего выпуска.
• Вводите новый тег основной версии (v2) для изменений, которые будут нарушить существующие рабочие процессы.
• Выпуск основных версий с бета-тегом, чтобы указать их состояние; например, v2-beta. Вы можете удалить тег -beta, когда выпуск будет готов.

Вот несколько примеров каждого из вариантов.

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

Использование SHA фиксации

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

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Публикация действия в GitHub Marketplace

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

Ниже приведены требования к публикации действия в GitHub Marketplace. Они применяются как к действиям на основе контейнера Docker, так и к действиям на основе JavaScript:

• Действие должно находиться в общедоступном репозитории.
• Каждый репозиторий должен содержать одно действие.
• Файл метаданных действия (action.yml или action.yaml) должен находиться в корневом каталоге репозитория.
• name в файле метаданных действия в GitHub Marketplace должен быть уникален.
  • Имя не может совпадать с пользователем или организацией на GitHub, если пользователь или владелец организации не публикует действие. Например, только организация GitHub может опубликовать действие с именем github.
  • Не name удается сопоставить существующую категорию GitHub Marketplace.
  • Не name удается сопоставить существующую функцию GitHub.

Вы можете добавить созданное вами действие в GitHub Marketplace, разметив его как новый выпуск и опубликовав. В GitHub есть несколько действий, которые позволяют публиковать выпуск действия. Дополнительные сведения об этих шагах см. в разделе "Сводка" в конце этого модуля.