Сведения о параметрах 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 и выбирает параметр для запроса авторизации пользователя (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. Для параметра запроса 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".