Skip to main content

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

Манифест приложения GitHub — это предварительно настроенное приложение GitHub, к которому можно предоставить общий доступ всем пользователям, желающим использовать приложение в личных репозиториях. Поток манифеста позволяет пользователю быстро создать, установить и начать расширение приложения 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 состоит из следующих этапов:

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

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

Параметры манифеста приложения GitHub

ИмяТипОписание
namestringИмя приложения GitHub.
urlstringОбязательный. Домашняя страница приложения GitHub.
hook_attributesobjectКонфигурация веб-перехватчика приложения GitHub.
redirect_urlstringПолный URL-адрес, на который осуществляется перенаправление после того, как пользователь инициирует создание приложения GitHub на основе манифеста.
callback_urlsarray of stringsПолный URL-адрес для перенаправления после авторизации установки. Вы можете указать до 10 URL-адресов обратного вызова.
setup_urlstringПолный URL-адрес для перенаправления пользователей после установки приложения GitHub, если требуется дополнительная настройка.
descriptionstringОписание приложения GitHub.
publicbooleanЗадайте значение true, если приложение GitHub доступно для всех пользователей, или false — если оно доступно только владельцу.
default_eventsarrayСписок событий, на которые подписывается приложение GitHub.
default_permissionsobjectНабор разрешений, необходимых приложению GitHub. Формат объекта использует имя разрешения в качестве ключа (например, issues) и тип доступа в качестве значения (например, write).

Объект hook_attributes содержит следующие ключи:

ИмяТипОписание
urlstringОбязательный. URL-адрес сервера, который будет получать запросы POST веб-перехватчика.
activebooleanДоставка сведений о событии при активации этого перехватчика. По умолчанию используется значение true.

Параметры

ИмяТипОписание
statestringСлучайная строка, которую сложно угадать. Используется для защиты от атак в форме подделки межсайтовых запросов.

Примеры

В этом примере на веб-странице размещается форма с кнопкой, которая активирует запрос 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, сделайте следующее:

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

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

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

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

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