Сведения о параметрах URL-адреса для регистрации GitHub Apps
Параметры URL-адреса можно использовать для предварительного выбора параметров конфигурации новой регистрации GitHub App и совместного использования пользовательской ссылки с другими людьми. Ссылка будет принимать людей на страницу регистрации GitHub App , где параметры приложения будут предварительно заполнены в соответствии с параметрами URL-адреса, включенными в URL-адрес.
Этот подход полезен для интеграторов, которые хотят, чтобы клиенты могли настроить приложение на своих личная учетная запись или организации с определенными спецификациями или для клиентов, использующих GitHub Enterprise Server которые не могут устанавливать приложения из GitHub Marketplace.
Кроме того, можно создать манифест GitHub App. Дополнительные сведения см. в разделе Регистрация приложения GitHub из манифеста.
Примечание.
В этой статье содержатся команды или примеры, использующие github.com домен. Вы можете получить доступ к GitHub в другом домене, например octocorp.ghe.com.
Создание пользовательского URL-адреса конфигурации с параметрами запроса
Чтобы создать пользовательский URL-адрес конфигурации для GitHub App в личной или корпоративной учетной записи, добавьте параметры запроса после следующих базовых URL-адресов.
- Чтобы зарегистрировать приложение в личная учетная запись, добавьте параметры URL-адреса в:
https://github.com/settings/apps/new - Чтобы зарегистрировать приложение в учетной записи организации, добавьте параметры URL-адреса в:
https://github.com/organizations/ORGANIZATION/settings/apps/newЗаменитеORGANIZATIONименем организации, в которой клиент хочет зарегистрировать приложение. - Чтобы зарегистрировать приложение в корпоративной учетной записи, добавьте параметры URL-адреса в:
https://github.com/enterprises/ENTERPRISE/settings/apps/newЗаменитеENTERPRISEименем предприятия, в котором клиент хотел бы зарегистрировать приложение.
На странице регистрации приложения пользователь, регистрирующий приложение, может изменить предварительно выбранные значения перед отправкой приложения. Если вы не включаете параметры для обязательных значений (например name) в строку запроса URL-адреса, пользователь, регистрирующий приложение, должен ввести значение, прежде чем они смогут зарегистрировать приложение.
Например, следующий URL-адрес регистрирует новое общедоступное приложение с именем octocat-github-app личная учетная запись. С помощью параметров запроса URL-адрес предварительно настраивает описание и URL-адрес обратного вызова. Он также выбирает разрешения на чтение и запись для checks, активирует веб-перехватчики с помощью webhook_active параметра, подписывается на check_run события веб-перехватчика check_suite и выбирает параметр для запроса авторизации пользователя (OAuth) во время установки:
https://github.com/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 | Это узкоспециализированное разрешение, позволяющее приложению получать доступ к одному файлу в любом репозитории. При задании разрешения single_file или read для write в этом поле указывается путь к одному файлу, которым будет управлять GitHub App. Если вам нужно управлять несколькими файлами, см single_file_paths . ниже. |
single_file_paths | array of strings | Этот параметр позволяет приложению получить доступ к десяти указанным файлам в репозитории. При задании разрешения single_file или read для write этот массив может хранить пути до десяти файлов, которыми будет управлять 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.