Сведения о параметрах URL-адреса для создания GitHub Apps
Параметры URL-адреса можно использовать для предварительного выбора параметров конфигурации нового 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.