使用 URL 参数注册 GitHub 应用

关于用于注册 GitHub Apps

的 URL 参数

可以使用 URL 参数预先选择新 GitHub App 注册的配置设置，并与其他人共享自定义链接。 该链接会让用户转到 GitHub App 注册页面，其中应用设置将根据 URL 中包含的 URL 参数预先填充。

对于希望客户在其个人帐户或组织中设置具有特定规范的应用的集成商，或者对于使用 GitHub Enterprise Server 但无法从 GitHub Marketplace 安装应用的客户，此方法非常有用。

或者，可以创建 GitHub App 清单。 有关详细信息，请参阅“从清单注册 GitHub 应用”。

使用查询参数创建自定义配置 URL

若要在个人或组织帐户上为 GitHub App 创建自定义配置 URL，请在以下基 URL 后面添加查询参数。

• 若要在个人帐户上注册应用，请将 URL 参数添加到：http(s)://HOSTNAME/settings/apps/new
• 若要在组织帐户上注册应用，请将 URL 参数添加到：http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new。 将 ORGANIZATION 替换为要让客户在其中注册应用的组织的名称。

在应用注册页上，注册应用的人员可以在提交应用之前编辑预先选择的值。 如果没有在 URL 查询字符串中包含所需值（如 name）的参数，则注册应用的人员需要在注册该应用之前输入值。

例如，以下 URL 可在个人帐户上注册名为 octocat-github-app 的新公共应用。 使用查询参数，URL 可预配置说明和回叫 URL。 此 URL 还可选择 checks 的读取和写入权限、使用 webhook_active 参数激活 Webhook、订阅 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	您的 GitHub App 网站主页的完整 URL。
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	在用户安装 GitHub App 后重定向到的完整 URL（如果应用程序在安装之后需要额外设置）。 有关详细信息，请参阅“关于设置 URL”。
setup_on_update	boolean	设置为 true 可在更新安装后（例如在添加或删除存储库之后）将用户重定向到设置 URL。
public	boolean	当 GitHub App 可供公众使用时，设置为 true；当它仅供应用的所有者访问时，设置为 false。 此参数不适用于由企业拥有的应用。
webhook_active	boolean	设置为 true 以启用 Webhook。 默认情况下，Webhook 处于禁用状态。
webhook_url	string	要向其发送 web 挂钩事件有效负载的完整 URL。
events	array of strings	Webhook 事件。 某些 Webhook 事件需要你对资源有 read 或 write 权限，才能在注册新 GitHub App 时选择事件。 有关详细信息，请参阅“GitHub App Webhook 事件”部分。 您可以在查询字符串中选择多个事件。 例如，events[]=public&events[]=label。
single_file_name	string	这是一种范围狭窄的权限，允许应用程序访问任何仓库中的单个文件。 将 single_file 权限设置为 read 或 write 时，此字段提供 GitHub App 将要管理的单个文件的路径。 如果需要托管多个文件，请参阅下文：single_file_paths。
single_file_paths	array of strings	这允许应用程序访问仓库中的最多 10 个指定文件。 将 single_file 权限设置为 read 或 write 时，此数组可存储 GitHub App 将要管理的最多 10 个文件的路径。 这些文件都接收由 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 Apps 选择权限”。

GitHub App web 挂钩事件

可以使用查询参数启用 GitHub App Webhook、指定 Webhook URL，并订阅应用以接收特定事件的 Webhook 有效负载。

若要启用 GitHub App Webhook，请在查询字符串中使用 webhook_active=true。 若要指定要向其发送 Webhook 事件有效负载的完整 URL，请在查询字符串中使用 webhook_url。 要为应用订阅特定 Webhook 有效负载事件，请使用 events[] 作为查询参数名称，并将查询值设置为 Webhook 事件的名称。 有关可能的 Webhook 事件以及订阅每个事件所需的 GitHub App 权限的详细信息，请参阅“Webhook 事件和有效负载”。

例如，若要订阅 GitHub App 以接收与提交评论相关的活动的 Webhook 有效负载，查询字符串将包含 &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment。 请注意，commit_comment Webhook 事件要求 GitHub App 至少具有“内容”存储库权限的读取级别访问权限。 因此，查询字符串还应包含一个参数，用于将 contents 权限设置为 read 或 write。 有关详细信息，请参阅“GitHub 应用权限”。

无法使用查询参数设置 Webhook 机密的值。 如果应用需要机密来保护其 Webhook，则必须由注册应用的人员在 GitHub UI 中设置机密的值。

有关 Webhook 和 GitHub Apps 的详细信息，请参阅“将 Webhook 与 GitHub 应用配合使用”。