Регистрация приложения GitHub из манифеста

Сведения о манифестах приложений 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 см. на этой странице.

Регистрация приложения GitHub из манифеста

В этой статье