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

О манифестах GitHub App

Если кто-то регистрирует данные GitHub App из манифеста, им нужно только следовать URL-адресу и имени приложения. Манифест содержит разрешения, события и URL-адрес веб-перехватчика, которые необходимы для автоматической регистрации приложения. Поток манифеста создает регистрацию GitHub App и создает секрет веб-перехватчика приложения, закрытый ключ (PEM-файл), секрет клиента и GitHub App идентификатор. Пользователь, создающий регистрацию GitHub App из манифеста, будет принадлежать регистрации GitHub App и может изменить параметры регистрации, удалить его или передать его другому пользователю на GitHub.

Вы можете использовать Probot для начала работы с манифестами GitHub App или примером реализации. Дополнительные сведения см. в статье "Использование Probot для реализации потока манифеста GitHub App".

Ниже приведены некоторые сценарии, в которых можно использовать манифесты GitHub App для регистрации предварительно настроенных приложений:

Помогите новым участникам команды быстро быстро при разработке GitHub Apps.
Разрешите другим пользователям расширить GitHub App с помощью API GitHub без необходимости настраивать приложение.
Создайте эталонные проекты GitHub App для совместного использования с сообществом GitHub .
Убедитесь, что вы развертываете GitHub Apps в средах разработки и рабочей среды с помощью той же конфигурации.
Отслеживайте изменения в конфигурации GitHub App.

Реализация потока манифеста GitHub App

Поток манифеста GitHub App использует процесс подтверждения, аналогичный потоку OAuth. Поток использует манифест для регистрации GitHub App и получает временный code используемый для получения закрытого ключа приложения, секрета веб-перехватчика и идентификатора.

Note

Все три шага необходимо выполнить в потоке манифеста GitHub App в течение одного часа.

Выполните следующие действия, чтобы реализовать поток манифеста GitHub App:

Вы перенаправляете пользователей на GitHub для регистрации новых данных GitHub App.
GitHub перенаправляет людей обратно на ваш сайт.
Вы обмениваете временный код для получения конфигурации приложения.

1. Вы перенаправляете пользователей на GitHub для регистрации новых данных GitHub App

Чтобы перенаправить пользователей для регистрации новых данных GitHub App, укажите ссылку для них, чтобы щелкнуть запрос POST https://github.com/settings/apps/new на личная учетная запись или https://github.com/organizations/ORGANIZATION/settings/apps/new учетную запись организации, заменив ORGANIZATION имя учетной записи организации, в которой будет зарегистрировано приложение.

Необходимо включить параметры манифеста GitHub App в виде строки в кодировке JSON в параметре с именем manifest. Также для дополнительной безопасности вы можете включить параметр state.

Пользователь, регистрирующий приложение, будет перенаправлен на страницу GitHub с полем ввода, в котором можно изменить имя приложения, включенного manifest в параметр. Если в параметре manifest не задано name, пользователь может указать в этом поле собственное имя приложения.

GitHub App Параметры манифеста

Имя.	Тип	Описание
`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 App. Формат объекта использует имя разрешения в качестве ключа (например, `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 App, 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 App из конечной точки манифеста . Ответ будет содержать id идентификатор (GitHub App), pem (закрытый ключ) и webhook_secret. GitHub создает секрет веб-перехватчика для приложения автоматически. Эти значения можно хранить в переменных среды на сервере приложения. Например, если для хранения переменных среды, в приложении используется dotenv, эти переменные будут храниться в файле .env приложения.

Этот шаг необходимо выполнить в потоке манифеста GitHub App в течение одного часа.

Note

Эта конечная точка ограничена скоростью. Сведения о том, как узнать текущее состояние ограничения скорости, см. в разделе Ограничения скорости.

POST /app-manifests/{code}/conversions

Дополнительные сведения об ответе конечной точки см. в статье "Создание GitHub App из манифеста.

После завершения последнего шага в потоке манифеста пользователь, регистрирующий приложение из потока, будет владельцем зарегистрированного GitHub App, который он может установить на любом из своих личных репозиториев. Они могут расширить приложение с помощью API -интерфейсов GitHub, передать владение другому пользователю или удалить его в любое время.

Использование Probot для реализации потока манифеста GitHub App

Probot — это платформа, созданная с Node.js , которая выполняет множество задач, необходимых для всех GitHub Apps, таких как проверка веб-перехватчиков и выполнение проверки подлинности. Probot реализует поток манифеста GitHub App, что упрощает создание и совместное использование эталонных проектов GitHub App с сообществом GitHub .

Чтобы создать доступное для совместного использования приложение Probot, сделайте следующее:

Создайте новые данные GitHub App.
Откройте созданный проект и настройте параметры в файле app.yml. Probot использует параметры в app.yml качестве параметров манифеста GitHub App.
Добавьте код своего приложения.
Запустите GitHub App локально или разместите его в любом месте. При переходе по URL-адресу размещенного приложения вы найдете веб-страницу с кнопкой "Регистрация GitHub App ", которую пользователи могут нажать, чтобы зарегистрировать предварительно настроенное приложение.

Используя dotenv, Probot создает файл .env и присваивает переменным среды APP_ID, PRIVATE_KEY и WEBHOOK_SECRET значения, полученные из конфигурации приложения.

Размещение приложения с помощью Glitch

Вы можете ознакомиться с примером приложения Probot, которое использует Glitch для размещения и совместного использования приложения. В этом примере используется API проверок и выбираются необходимые события и разрешения этого API в файле app.yml. Glitch — это инструмент, позволяющий делать "ремиксы" собственных приложений. При этом создается копия приложения, которая размещается и развертывается средствами Glitch. Дополнительные сведения о создании ремиксов приложений с помощью Glitch см. на этой странице.

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

В этой статье