Skip to main content

Регистрация приложения GitHub с помощью параметров URL-адреса

Вы можете использовать параметры запроса URL-адреса, чтобы помочь другим пользователям быстро настроить новый GitHub App с определенной конфигурацией, выбранной вами.

Сведения о параметрах URL-адреса для регистрации GitHub Apps

Параметры URL-адреса можно использовать для предварительного выбора параметров конфигурации новой регистрации GitHub App и совместного использования пользовательской ссылки с другими людьми. Ссылка будет принимать людей на страницу регистрации GitHub App , где параметры приложения будут предварительно заполнены в соответствии с параметрами URL-адреса, включенными в URL-адрес.

Этот подход полезен для интеграторов, которые хотят, чтобы клиенты могли настроить приложение на своих личная учетная запись или организации с определенными спецификациями или для клиентов, использующих GitHub Enterprise Server которые не могут устанавливать приложения из GitHub Marketplace.

Кроме того, можно создать манифест GitHub App. Дополнительные сведения см. в разделе Регистрация приложения GitHub из манифеста.

Создание пользовательского URL-адреса конфигурации с параметрами запроса

Чтобы создать пользовательский URL-адрес конфигурации для GitHub App в личной или корпоративной учетной записи, добавьте параметры запроса после следующих базовых URL-адресов.

  • Чтобы зарегистрировать приложение в личная учетная запись, добавьте параметры URL-адреса в:https://github.com/settings/apps/new
  • Чтобы зарегистрировать приложение в учетной записи организации, добавьте параметры URL-адреса в: https://github.com/organizations/ORGANIZATION/settings/apps/new Замените ORGANIZATION именем организации, в которой клиент хочет зарегистрировать приложение.

На странице регистрации приложения пользователь, регистрирующий приложение, может изменить предварительно выбранные значения перед отправкой приложения. Если вы не включаете параметры для обязательных значений (например 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.

Наименование параметраТипОписание
namestringИмя GitHub App. Присвойте своему приложению краткое и понятное имя. Это имя должно отличаться от имени существующего пользователя GitHub, если только это не ваше собственное имя пользователя или организации. Укороченная версия имени вашего приложения будет отображаться в пользовательском интерфейсе, когда ваша интеграция выполнит действие.
descriptionstringОписание GitHub App.
urlstringПолный URL-адрес домашней страницы сайта GitHub App.
callback_urlsarray of stringsПолный URL-адрес для перенаправления после авторизации установки. Вы можете указать до 10 URL-адресов обратного вызова. Эти URL-адреса используются, если приложению требуется создать маркер доступа пользователя. Например, callback_urls[]=https://example.com&callback_urls[]=https://example-2.com. Дополнительные сведения см. в разделе Сведения о URL-адресе обратного вызова авторизации пользователя.
request_oauth_on_installbooleanЕсли ваше приложение выполняет авторизацию пользователей с помощью потока OAuth, вы можете установить для этого параметра значение true. Это позволит пользователям авторизовать приложение при его установке, уменьшив количество шагов. Если вы выберете этот вариант, setup_url станет недоступным и пользователи будут перенаправлены на ваш callback_url после установки приложения.
setup_urlstringПолный URL-адрес для перенаправления после установки GitHub App, если для приложения требуется дополнительная настройка после установки. Дополнительные сведения см. в разделе Сведения о URL-адресе установки.
setup_on_updatebooleanЗадайте значение true, чтобы перенаправлять людей на URL-адрес настройки при обновлении установок, например после добавления или удаления репозиториев.
publicbooleanЗадайте значение true, если приложение GitHub App доступно для всех пользователей, или false — если оно доступно только владельцу.
webhook_activebooleanУстановите для true включения веб-перехватчика. Веб-перехватчик по умолчанию отключен.
webhook_urlstringПолный URL-адрес, на который вы хотите отправлять полезные данные события веб-перехватчика.
eventsarray of stringsСобытия веб-перехватчика. Для некоторых событий веб-перехватчика необходимо получить разрешения read или write для ресурса, прежде чем выбрать событие при регистрации нового GitHub App. Дополнительные сведения см. в разделе "GitHub App событий веб-перехватчика". Вы можете выбрать несколько событий в строке запроса. Например, events[]=public&events[]=label.
single_file_namestringЭто узкоспециализированное разрешение, позволяющее приложению получать доступ к одному файлу в любом репозитории. При задании разрешения read или write для single_file в этом поле указывается путь к одному файлу, которым будет управлять GitHub App. Если вам нужно управлять несколькими файлами, см single_file_paths . ниже.
single_file_pathsarray 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".