Выбор расположения для действия
Если вы разрабатываете действие для других пользователей, рекомендуется сохранить действие в собственном репозитории вместо объединения его с другим кодом приложения. Это позволяет осуществлять управление версиями, отслеживание и выпуск для действия точно так же, как и для любого другого программного обеспечения.
Хранение действия в собственном репозитории упрощает обнаружение действия в сообществе GitHub, ограничивает область базы кода для разработчиков, устраняющих проблемы и расширяющих действие, а также отделяет управление версиями от версий другого кода приложения.
Если вы создаете действие, которое не планируете делать доступным для других пользователей, вы можете хранить файлы этого действия в любом расположении своего репозитория. Если вы планируете объединить действие, рабочий процесс и код приложения в одном репозитории, рекомендуется хранить действия в каталоге .github. Например, .github/actions/action-a и .github/actions/action-b.
Обеспечение совместимости с другими платформами
Многие пользователи получают доступ к GitHub в домене, отличном от GitHub.com, например GHE.com или личного домена для GitHub Enterprise Server.
Чтобы убедиться, что действие совместимо с другими платформами, не используйте жестко закодированные ссылки на URL-адреса API, например https://api.github.com. Вместо этого можно:
-
Используйте переменные среды (см . AUTOTITLE):
- Для REST API используйте переменную среды
GITHUB_API_URL. - Для GraphQL используйте переменную среды
GITHUB_GRAPHQL_URL.
- Для REST API используйте переменную среды
-
Используйте набор средств, например
@actions/github, который может автоматически задать правильные URL-адреса.
Использование управления выпусками для действий
В этом разделе объясняется, как использовать управление выпусками, чтобы обеспечить предсказуемое распространение обновлений для действий.
Рекомендации по управлению выпусками
Если вы разрабатываете действие для других пользователей, мы рекомендуем использовать управление выпусками для управления распространением обновлений. Пользователи могут ожидать, что версия исправления действия включает в себя необходимые критические исправления и обновления системы безопасности, сохраняя при этом совместимость с существующими рабочими процессами. Рекомендуется выпускать новый основной номер версии всякий раз, когда изменения затрагивают совместимость.
В рамках этого подхода к управлению выпусками пользователи не должны ссылаться на ветвь по умолчанию действия, так как, скорее всего, содержит последний код и, следовательно, может быть неустойчивым. Вместо этого можно порекомендовать, чтобы пользователи указывали основной номер версии при использовании действия, и перенаправлять их к более конкретной версии только при возникновении проблем.
Чтобы использовать определенную версию действия, пользователи могут настроить рабочий процесс GitHub Actions для тега, SHA фиксации или ветви, названной по выпуску.
Использование тегов для управления выпусками
Мы рекомендуем использовать теги для управления выпусками действий. С помощью этого подхода пользователи могут легко различать основной и дополнительный номера версии:
- Создайте и проверьте выпуск в ветви выпуска (например,
release/v1) перед созданием тега выпуска (например,v1.0.2). - Создайте выпуск с помощью семантического версионирования. Дополнительные сведения см. в разделе Управление выпусками в репозитории.
- Перемещайте тег основной версии (например
v1,v2) чтобы указать ссылку на Git текущего выпуска. Дополнительные сведения см. в основах Git. - Вводите новый тег основной версии (
v2) для изменений, которые будут нарушить существующие рабочие процессы. Например, изменение входных данных действия будет критическим изменением. - Основные номера версии могут быть первоначально выпущены с тегом
beta, чтобы указать их состояние, например,v2-beta. Затем, когда все будет готово, тег-betaможно удалить.
В этом примере показано, как пользователь может ссылаться на тег основного выпуска:
steps:
- uses: actions/javascript-action@v1
В этом примере показано, как пользователь может ссылаться на тег определенного выпуска исправления:
steps:
- uses: actions/javascript-action@v1.0.1
Использование ветвей для управления выпусками
Если вы предпочитаете использовать имена ветвей для управления выпусками, в этом примере показано, как ссылаться на именованную ветвь:
steps:
- uses: actions/javascript-action@v1-beta
Использование SHA фиксации для управления выпусками
Каждая фиксация Git получает вычисляемое значение SHA, которое является уникальным и неизменяемым. Пользователи вашего действия могут предпочесть использование значения SHA фиксации, так как такой подход может оказаться более надежным, чем указание тега, который может быть удален или перемещен. Однако это означает, что пользователи не получат дальнейшие обновления для такого действия. Необходимо использовать полное значение SHA фиксации, а не сокращенное.
steps:
- uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f
Создание файла сведений для действия
Мы рекомендуем создать файл сведений, чтобы помочь людям понять, как следует использовать ваше действие. В файл README.md можно включить следующее:
- подробное описание того, что делает действие;
- обязательные входные и выходные аргументы;
- необязательные входные и выходные аргументы;
- секреты, используемые действием;
- переменные среды, используемые действием;
- пример использования действия в рабочем процессе.