Сведения о манифестах приложений GitHub
Когда кто-то регистрирует приложение GitHub из манифеста, им нужно только следовать URL-адресу и имени приложения. Манифест содержит разрешения, события и URL-адрес веб-перехватчика, которые необходимы для автоматической регистрации приложения. Поток манифеста создает регистрацию приложения GitHub и создает секрет веб-перехватчика приложения, закрытый ключ (PEM-файл), секрет клиента и идентификатор приложения GitHub. Пользователь, создающий регистрацию GitHub App из манифеста, будет принадлежать регистрации GitHub App и может изменить параметры регистрации, удалить его или передать другому пользователю на сайте GitHub.
Чтобы начать работу с манифестами приложений GitHub или просмотреть пример реализации, можно использовать Probot. Дополнительные сведения см. в разделе Реализация потока манифеста приложения GitHub с помощью Probot.
Ниже приведены некоторые сценарии, в которых можно использовать манифесты приложений GitHub для регистрации предварительно настроенных приложений:
- Помощь новым участникам команды в скорейшем освоении разработки приложений GitHub.
- Предоставление другим пользователям возможности расширять приложение GitHub с помощью API GitHub без необходимости его настройки.
- Создание справочных проектов приложений GitHub для совместного использования сообществом GitHub.
- Необходимость обеспечить развертывание приложения GitHub в среде разработки и рабочей среде в одной и той же конфигурации.
- Отслеживание исправлений в конфигурации приложения GitHub.
Реализация потока манифеста приложения GitHub
Поток манифеста приложения GitHub использует процесс подтверждения, аналогичный потоку OAuth. Этот поток использует манифест для регистрации приложения GitHub и получает временный код (code
), который используется для получения закрытого ключа приложения, секрета веб-перехватчика и идентификатора.
Примечание. Все эти три шага необходимо выполнить в потоке манифеста приложения GitHub в течение одного часа.
Реализация потока приложения GitHub состоит из следующих этапов:
- Вы перенаправляете пользователей на GitHub, чтобы зарегистрировать новое приложение GitHub.
- GitHub перенаправляет пользователей обратно на ваш сайт.
- Вы обмениваете временный код для получения конфигурации приложения.
1. Вы перенаправляете пользователей на GitHub, чтобы зарегистрировать новое приложение GitHub
Чтобы перенаправить POST
https://github.com/settings/apps/new
пользователей для регистрации нового приложения GitHub, укажите ссылку для них, чтобы щелкнуть запрос на личная учетная запись или https://github.com/organizations/ORGANIZATION/settings/apps/new
учетную запись организации, заменив ORGANIZATION
имя учетной записи организации, в которой будет зарегистрировано приложение.
Параметры манифеста приложения GitHub необходимо включить в параметр с именем manifest
в виде строки с кодировкой JSON. Также для дополнительной безопасности вы можете включить параметр state
.
Пользователь, регистрирующий приложение, будет перенаправлен на страницу GitHub с полем ввода, где можно изменить имя приложения, которое вы включили в manifest
параметр. Если в параметре manifest
не задано name
, пользователь может указать в этом поле собственное имя приложения.
Параметры манифеста приложения GitHub
Имя. | Тип | Описание |
---|---|---|
name | string | Имя GitHub App. |
url | string | Необходимые. Домашняя страница GitHub App. |
hook_attributes | object | Конфигурация веб-перехватчика GitHub App. |
redirect_url | string | Полный URL-адрес для перенаправления после того, как пользователь инициирует регистрацию GitHub App из манифеста. |
callback_urls | array of strings | Полный URL-адрес для перенаправления после авторизации установки. Вы можете указать до 10 URL-адресов обратного вызова. |
setup_url | string | Полный URL-адрес для перенаправления пользователей после установки GitHub App, если требуется дополнительная настройка. |
description | string | Описание GitHub App. |
public | boolean | Задайте значение true , если приложение GitHub App доступно для всех пользователей, или false — если оно доступно только владельцу. |
default_events | array | Список событий , на которые подписывается GitHub App. |
default_permissions | object | Набор разрешений, необходимых приложению GitHub. Формат объекта использует имя разрешения в качестве ключа (например, issues ) и тип доступа в качестве значения (например, write ). Дополнительные сведения см. в разделе Выбор разрешений для приложения GitHub. |
request_oauth_on_install | boolean | Установите для true запроса пользователя авторизовать GitHub App, после установки GitHub App . |
setup_on_update | boolean | Установите для true перенаправления пользователей в setup_url после обновления данных GitHub App установки. |
Объект hook_attributes
имеет следующие ключи.
Имя. | Тип | Описание |
---|---|---|
url | string | Необходимые. URL-адрес сервера, который будет получать запросы POST веб-перехватчика. |
active | boolean | Доставка сведений о событии при активации этого перехватчика. По умолчанию используется значение true. |
Параметры
Имя (название) | Тип | Описание |
---|---|---|
state | string | Случайная строка, которую сложно угадать. Используется для защиты от атак в форме подделки межсайтовых запросов. |
Примеры
В этом примере на веб-странице размещается форма с кнопкой, которая активирует запрос POST
для получения личной учетной записи.
<form action="https://github.com/settings/apps/new?state=abc123" method="post">
Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
<input type="submit" value="Submit">
</form>
<script>
input = document.getElementById("manifest")
input.value = JSON.stringify({
"name": "Octoapp",
"url": "https://www.example.com",
"hook_attributes": {
"url": "https://example.com/github/events",
},
"redirect_url": "https://example.com/redirect",
"callback_urls": [
"https://example.com/callback"
],
"public": true,
"default_permissions": {
"issues": "write",
"checks": "write"
},
"default_events": [
"issues",
"issue_comment",
"check_suite",
"check_run"
]
})
</script>
В этом примере на веб-странице размещается форма с кнопкой, которая активирует запрос POST
для получения учетной записи организации. Замените ORGANIZATION
именем учетной записи организации, в которой вы хотите зарегистрировать приложение.
<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
<input type="submit" value="Submit">
</form>
<script>
input = document.getElementById("manifest")
input.value = JSON.stringify({
"name": "Octoapp",
"url": "https://www.example.com",
"hook_attributes": {
"url": "https://example.com/github/events",
},
"redirect_url": "https://example.com/redirect",
"callback_urls": [
"https://example.com/callback"
],
"public": true,
"default_permissions": {
"issues": "write",
"checks": "write"
},
"default_events": [
"issues",
"issue_comment",
"check_suite",
"check_run"
]
})
</script>
2. GitHub перенаправляет пользователей обратно на ваш сайт
Когда пользователь нажимает кнопку Создать приложение GitHub, GitHub выполняет обратное перенаправление к redirect_url
с использованием временного кода (code
) в параметре кода. Например:
https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679
Если задан параметр state
, этот параметр также будет представлен в параметре redirect_url
. Например:
https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123
3. Вы обмениваете временный код для получения конфигурации приложения
Чтобы завершить подтверждение, отправьте временный код (code
) в запросе POST
в конечную точку создания приложения GitHub на основе манифеста. Ответ будет содержать id
(идентификатор приложения GitHub), pem
(закрытый ключ) и webhook_secret
. GitHub создает секрет веб-перехватчика для приложения автоматически. Эти значения можно хранить в переменных среды на сервере приложения. Например, если для хранения переменных среды, в приложении используется dotenv, эти переменные будут храниться в файле .env
приложения.
Этот шаг в потоке манифеста приложения GitHub необходимо выполнить в течение одного часа.
Примечание. Для этой конечной точки устанавливается ограничение скорости. Сведения о том, как узнать текущее состояние ограничения скорости, см. в разделе Ограничения скорости.
POST /app-manifests/{code}/conversions
Дополнительные сведения об ответе конечной точки см. в разделе Создание приложения GitHub на основе манифеста.
После завершения последнего шага в потоке манифеста пользователь, регистрирующий приложение из потока, будет владельцем зарегистрированного приложения GitHub, который он может установить на любой из своих личных репозиториев. Владелец также может расширить приложение с помощью API GitHub, передать права владения другому пользователю или в любой момент удалить его.
Реализация потока манифеста приложения GitHub с помощью Probot
Probot — это созданная на основе Node.js платформа, которая выполняет многие используемые всеми приложениями GitHub задачи, в том числе проверку веб-перехватчиков и проверку подлинности. Probot реализует поток манифеста приложения GitHub, благодаря чему упрощается создание справочных проектов приложений GitHub и их совместное использование сообществом GitHub.
Чтобы создать доступное для совместного использования приложение Probot, сделайте следующее:
- Создайте новое приложение GitHub.
- Откройте созданный проект и настройте параметры в файле
app.yml
. Probot использует параметры в файлеapp.yml
в качестве параметров манифеста приложения GitHub. - Добавьте код своего приложения.
- Запустите приложение GitHub локально или разместите его в любом месте. При переходе по URL-адресу размещенного приложения вы найдете веб-страницу с кнопкой "Регистрация приложения GitHub", которую пользователи могут зарегистрировать предварительно настроенное приложение.
Используя dotenv, Probot создает файл .env
и присваивает переменным среды APP_ID
, PRIVATE_KEY
и WEBHOOK_SECRET
значения, полученные из конфигурации приложения.
Размещение приложения с помощью Glitch
Вы можете ознакомиться с примером приложения Probot, которое использует Glitch для размещения и совместного использования приложения. В этом примере используется API проверок и выбираются необходимые события и разрешения этого API в файле app.yml
. Glitch — это инструмент, позволяющий делать "ремиксы" собственных приложений. При этом создается копия приложения, которая размещается и развертывается средствами Glitch. Дополнительные сведения о создании ремиксов приложений с помощью Glitch см. на этой странице.