Сведения о параметрах 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:/. Дополнительные сведения см. в разделе Сведения о URL-адресе обратного вызова авторизации пользователя. |
request_oauth_ | 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 | Этот параметр позволяет приложению получить доступ к десяти указанным файлам в репозитории. При установке разрешения read или writeв single_file этом массиве можно хранить пути до десяти файлов, которыми будет управлять ваш GitHub App массив. Все эти файлы получают одно и то же разрешение, заданное single_file, и не имеют отдельных индивидуальных разрешений. При настройке двух или более файлов API возвращается multiple_single_, в противном случае он возвращается multiple_single_. |
GitHub App Разрешения
Параметры запроса можно использовать для выбора разрешений для GitHub App регистрации. Для параметра запроса URL-адреса используйте имя разрешения в качестве имени параметра запроса и задайте для запроса одно из возможных значений для этого набора разрешений.
Например, чтобы выбрать разрешения "Чтение и запись" в пользовательском интерфейсе, contentsстрока запроса будет включать contents=write. Чтобы выбрать разрешения только для чтения в пользовательском интерфейсе blocking, строка запроса будет включать blocking=read. Чтобы выбрать "Нет доступа" в пользовательском интерфейсе, checksстрока запроса не будет включать checks разрешение.
Если учетная запись владения не является организацией или организацией, она не может запрашивать разрешения предприятия.
Дополнительные сведения о разрешениях и GitHub Appsсм. в разделе Выбор разрешений для приложения GitHub. Список разрешений, доступных для использования и их параметризованных имен, см. в разделе Управление личными маркерами доступа.
GitHub App События веб-перехватчика
Параметры запроса можно использовать для включения GitHub App веб-перехватчика, назначения URL-адреса веб-перехватчика и подписки на приложение для получения полезных данных веб-перехватчика для определенных событий.
Чтобы включить веб-перехватчик, используйте webhook_active=true в строке GitHub App запроса. Чтобы назначить полный 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.