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

О GitHub App Manifests

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

Вы можете использовать Probot для начала работы GitHub App с Manifests или посмотреть пример реализации. См. раздел «Использование Probot для реализации GitHub App потока манифеста », чтобы узнать больше.

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

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

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

          GitHub App Поток Манифеста использует процесс рукопожатия, похожий на [поток OAuth](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). Поток использует манифест для [регистрации GitHub App](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) a и получает временное `code` приложение, используемое для получения приватного ключа приложения, секрета вебхука и ID.

Примечание.

Вы должны выполнить все три шага потока 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 . Если в параметре name не задано manifest, пользователь может указать в этом поле собственное имя приложения.

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

Имя.	Тип	Описание
`name`	`string`	Имя GitHub App.
`url`	`string`

          **Обязательно**. Главная страница вашего GitHub App.

hook_attributes | object | Конфигурация GitHub Appвебхука 's. 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 в Create a GitHub App from a manifest endpoint. Ответ будет включать id (GitHub App ID), pem (приватный ключ) и webhook_secret. GitHub Автоматически создаёт секрет Webhook для приложения. Эти значения можно хранить в переменных среды на сервере приложения. Например, если для хранения переменных среды, в приложении используется dotenv, эти переменные будут храниться в файле .env приложения.

Вы должны завершить этот шаг потока GitHub App Манифеста в течение одного часа.

Примечание.

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

POST /app-manifests/{code}/conversions

Для получения дополнительной информации о реакции конечной точки см. раздел «Создать a GitHub App из манифеста».

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

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

          [Probot](https://probot.github.io/) — это фреймворк, построенный на [Node.js](https://nodejs.org/) , который выполняет многие задачи, необходимые всем GitHub Apps, такие как проверка вебхуков и аутентификация. Probot реализует [GitHub App манифестный поток](#implementing-the-github-app-manifest-flow), что облегчает создание и обмен GitHub App эталонными дизайнами с GitHub сообществом.

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

       [Сгенерируйте новый GitHub App](https://probot.github.io/docs/development/#generating-a-new-app).

Откройте созданный проект и настройте параметры в файле app.yml. Probot использует настройки в app.yml в качестве параметровGitHub App Манифеста.
Добавьте код своего приложения.

       [Запускайте GitHub App его локально](https://probot.github.io/docs/development/#running-the-app-locally) или размещайте где угодно. Когда вы переходите по URL размещённого приложения, вы обнаружите веб-страницу с **кнопкой «Регистрация GitHub App** », по которой можно зарегистрировать заранее настроенное приложение.

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

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

В этой статье