Регистрация Приложение 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

Чтобы перенаправить пользователей для регистрации нового Приложение GitHub, укажите ссылку для щелчкаPOST, которая отправляет запрос https://github.com/settings/apps/new на личная учетная запись или 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`).
`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 из манифеста

В этой статье