Сведения о параметрах 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.