Создание приложения GitHub на основе манифеста

Сведения о манифестах приложений GitHub

Чтобы создать приложение GitHub на основе манифеста, достаточно указать URL-адрес и имя приложения. Манифест содержит разрешения, события и URL-адрес веб-перехватчика, которые необходимы для автоматической регистрации приложения. Поток манифеста создает регистрацию приложения GitHub и извлекает секрет веб-перехватчика приложения, закрытый ключ (PEM-файл), а также идентификатор приложения GitHub. Пользователь, создающий приложение на основе манифеста, становится владельцем приложения и может изменять параметры конфигурации приложения, удалять его или передавать его другому пользователю на 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">
 Create 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">
 Create 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 на основе манифеста

В этой статье