Сведения о параметрах URL-адреса для регистрации GitHub Apps
Параметры URL-адреса можно использовать для предварительного выбора параметров конфигурации новой регистрации GitHub App и предоставления доступа к пользовательской ссылке другим пользователям. Ссылка приведет пользователей на страницу регистрации GitHub App, где параметры приложения будут предварительно заполнены в соответствии с параметрами URL-адреса, включенными в URL-адрес.
Этот подход полезен для интеграторов, которые хотят, чтобы клиенты настраивали приложение в своей личная учетная запись или организации с определенными спецификациями, или для клиентов, использующих GitHub Enterprise Server, которые не могут устанавливать приложения из GitHub Marketplace.
Кроме того, можно создать манифест GitHub App. Дополнительные сведения см. в разделе Регистрация Приложение GitHub из манифеста.
Создание URL-адреса настраиваемой конфигурации с параметрами запроса
Чтобы создать настраиваемый URL-адрес конфигурации для GitHub App в личной или корпоративной учетной записи, добавьте параметры запроса после следующих базовых URL-адресов.
- Чтобы зарегистрировать приложение на личная учетная запись, добавьте параметры URL-адреса в:
http(s)://HOSTNAME/settings/apps/new - Чтобы зарегистрировать приложение в учетной записи организации, добавьте параметры URL-адреса в :
http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new. ЗаменитеORGANIZATIONименем организации, в которой вы хотите, чтобы клиент зарегистрировал приложение.
На странице регистрации приложения пользователь, регистрирующий приложение, может изменить предварительно выбранные значения перед отправкой приложения. Если не включить параметры обязательных значений (например name, ) в строку запроса URL-адреса, пользователю, регистрирующему приложение, потребуется ввести значение, прежде чем сможет зарегистрировать приложение.
Например, следующий URL-адрес регистрирует новое общедоступное приложение с именем octocat-github-app в личная учетная запись. Используя параметры запроса, URL-адрес предварительно настраивает описание и URL-адрес обратного вызова. Он также выбирает разрешения на чтение и запись для checks, активирует веб-перехватчики с помощью webhook_active параметра , подписывается на check_run события и check_suite webhook и выбирает параметр для запроса авторизации пользователя (OAuth) во время установки:
http(s)://HOSTNAME/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&webhook_active=true&events[]=check_run&events[]=check_suite
Параметры конфигурации GitHub App
Вы можете использовать следующие параметры запроса, чтобы выбрать определенную конфигурацию для регистрации GitHub App. Например, чтобы присвоить приложению имя octocat-github-app, строка запроса будет содержать name=octocat-github-app.
| Имя параметра | Тип | Описание |
|---|---|---|
name | string | Имя GitHub App. Присвойте своему приложению краткое и понятное имя. Это имя должно отличаться от имени существующего пользователя GitHub, если только это не ваше собственное имя пользователя или организации. Краткая версия имени вашего приложения будет отображаться в пользовательском интерфейсе, когда ваша интеграция выполнит действие. |
description | string | Описание GitHub App. |
url | string | Полный URL-адрес домашней страницы сайта GitHub App. |
callback_urls | array of strings | Полный URL-адрес для перенаправления после авторизации установки. Вы можете указать до 10 URL-адресов обратного вызова. Эти URL-адреса используются, если приложению требуется создать маркер доступа пользователя. Например, callback_urls[]=https://example.com&callback_urls[]=https://example-2.com. Дополнительные сведения см. в разделе Сведения о URL-адресе обратного вызова авторизации пользователя. |
request_oauth_on_install | boolean | Если ваше приложение выполняет авторизацию пользователей с помощью потока OAuth, вы можете установить для этого параметра значение true. Это позволит пользователям авторизовать приложение при его установке, уменьшив количество шагов. Если вы выберете этот вариант, setup_url станет недоступным и пользователи будут перенаправлены на ваш callback_url после установки приложения. |
setup_url | string | Полный URL-адрес для перенаправления после установки GitHub App, если для приложения требуется дополнительная настройка после установки. Дополнительные сведения см. в разделе Сведения о URL-адресе установки. |
setup_on_update | boolean | Задайте значение true, чтобы перенаправлять людей на URL-адрес настройки при обновлении установок, например после добавления или удаления репозиториев. |
public | boolean | Задайте значение true, если приложение GitHub App доступно для всех пользователей, или false — если оно доступно только владельцу. |
webhook_active | boolean | Установите значение , true чтобы включить веб-перехватчик. Веб-перехватчик отключен по умолчанию. |
webhook_url | string | Полный URL-адрес, на который вы хотите отправлять полезные данные события веб-перехватчика. |
events | array of strings | События веб-перехватчика. Для некоторых событий веб-перехватчика необходимо получить разрешения read или write для ресурса, прежде чем выбрать событие при регистрации нового GitHub App. Дополнительные сведения см. в разделе "События веб-перехватчикаGitHub App". Вы можете выбрать несколько событий в строке запроса. Например, events[]=public&events[]=label. |
single_file_name | string | Это узкоспециализированное разрешение, позволяющее приложению получать доступ к одному файлу в любом репозитории. При задании разрешения read или write для single_file в этом поле указывается путь к одному файлу, которым будет управлять GitHub App. Если вам нужно управлять несколькими файлами, см. single_file_paths ниже. |
single_file_paths | array of strings | Этот параметр позволяет приложению получить доступ к десяти указанным файлам в репозитории. При задании разрешения read или write для single_file этот массив может хранить пути до десяти файлов, которыми будет управлять GitHub App. Все эти файлы получают одно и то же разрешение, заданное single_file, и не имеют отдельных индивидуальных разрешений. При настройке двух или более файлов API возвращает multiple_single_files=true, в противном случае возвращается multiple_single_files=false. |
Разрешения GitHub App
С помощью параметров запроса можно выбрать разрешения для регистрации GitHub App. Дополнительные сведения о возможных разрешениях, которые можно выбрать для приложения, и конечных точках, к которым приложение может получить доступ с каждым разрешением, см. в разделе Разрешения, необходимые для приложений GitHub. Для параметра запроса URL-адреса используйте имя разрешения в качестве имени параметра запроса и задайте для запроса одно из возможных значений для этого набора разрешений.
Например, чтобы выбрать разрешения "Чтение & запись" в пользовательском интерфейсе для contents, строка запроса будет содержать contents=write. Чтобы выбрать разрешения "Только для чтения" в пользовательском интерфейсе для blocking, строка запроса будет содержать blocking=read. Чтобы выбрать "Нет доступа" в пользовательском интерфейсе для checks, строка запроса не будет включать checks разрешение.
Дополнительные сведения о разрешениях и GitHub Apps см. в разделе Выбор разрешений для Приложение GitHub.
События веб-перехватчика GitHub App
С помощью параметров запроса можно включить веб-перехватчик GitHub App, назначить URL-адрес веб-перехватчика и подписать приложение на получение полезных данных веб-перехватчика для определенных событий.
Чтобы включить веб-перехватчик GitHub App, используйте webhook_active=true в строке запроса. Чтобы указать полный URL-адрес, по которому вы хотите отправлять полезные данные событий веб-перехватчика, используйте webhook_url в строке запроса. Чтобы подписать приложение на определенные события полезных данных веб-перехватчика, используйте events[] в качестве имени параметра запроса и задайте в качестве значения запроса имя события веб-перехватчика. Дополнительные сведения о возможных событиях веб-перехватчика и разрешениях GitHub App, необходимых для подписки на каждое событие, см. в разделе События и полезные данные веб-перехватчика.
Например, чтобы подписать GitHub App на получение полезных данных веб-перехватчика для действий, связанных с комментариями к фиксации, строка запроса будет содержать &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment. Обратите внимание, что для commit_comment события веб-перехватчика GitHub App требуется доступ по крайней мере на уровне чтения для разрешения репозитория "Содержимое". Поэтому строка запроса также должна содержать параметр для задания contents разрешения read или write. Дополнительные сведения см. в разделе Разрешения приложенияGitHub.
Нельзя использовать параметры запроса для задания значения секрета веб-перехватчика. Если приложению требуется секрет для защиты своего веб-перехватчика, пользователь, регистрирующий приложение, должен задать значение секрета в пользовательском интерфейсе GitHub.
Дополнительные сведения о веб-перехватчиках и GitHub Apps см. в разделе Использование веб-перехватчиков с приложениями GitHub.