关于注册 GitHub 应用的 URL 参数
您可以使用 URL 参数预选新 GitHub 应用注册的配置设置，并与其他人共享自定义链接。该链接将引导用户进入 GitHub 应用注册页面，应用设置将根据您在 URL 中包含的 URL 参数预先填写。
对于希望客户在其个人帐户或组织中按特定规范设置应用的集成商，或者对于无法从 GitHub Marketplace 安装应用的 GitHub Enterprise Server 客户，此方法非常有用。
或者，您可以创建一个 GitHub 应用清单。更多信息，请参阅“从清单注册 GitHub 应用”。
创建带有查询参数的自定义配置 URL
要为个人或组织帐户上的 GitHub 应用创建自定义配置 URL，请在以下基本 URL 后添加查询参数。
- 要在个人帐户上注册应用，请将 URL 参数添加到：
https://github.com/settings/apps/new - 要在组织帐户上注册应用，请将 URL 参数添加到：
https://github.com/organizations/ORGANIZATION/settings/apps/new。将ORGANIZATION替换为您希望客户注册应用的组织名称。
在应用注册页面上，注册应用的人员可以在提交应用之前编辑预选值。如果您未在 URL 查询字符串中包含必填值的参数（如name），则注册应用的人员需要输入值才能注册应用。
例如，以下 URL 在个人帐户上注册一个名为octocat-github-app的新公共应用。使用查询参数，URL 预先配置了描述和回调 URL。它还为checks选择了读写权限，使用webhook_active参数激活 Webhook，订阅了check_run和check_suiteWebhook 事件，并选择了在安装过程中请求用户授权（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 应用配置参数
您可以使用以下查询参数为 GitHub 应用注册选择特定的配置。例如，要将应用命名为“octocat-github-app”，您的查询字符串应包含name=octocat-github-app。
| 参数名称 | 类型 | 描述 |
|---|---|---|
name | 字符串 | GitHub 应用的名称。为您的应用起一个清晰简洁的名称。您的应用名称不能与现有的 GitHub 用户名称相同，除非它是您自己的用户名或组织名称。当您的集成采取行动时，您的应用名称的slug版本将显示在用户界面中。 |
description | 字符串 | GitHub 应用的描述。 |
url | 字符串 | GitHub 应用网站主页的完整 URL。 |
callback_urls | 字符串数组 | 有人授权安装后重定向到的完整 URL。您可以提供最多 10 个回调 URL。如果您的应用需要生成用户访问令牌，则会使用这些 URL。例如，callback_urls[]=https://example.com&callback_urls[]=https://example-2.com。更多信息，请参阅“关于用户授权回调 URL”。 |
request_oauth_on_install | 布尔值 | 如果您的应用使用 OAuth 流程授权用户，您可以将此选项设置为true，以允许用户在安装应用时授权，从而节省一个步骤。如果您选择此选项，则setup_url将不可用，用户将在安装应用后重定向到您的callback_url。 |
setup_url | 字符串 | 如果应用在安装后需要额外设置，则有人安装 GitHub 应用后重定向到的完整 URL。更多信息，请参阅“关于设置 URL”。 |
setup_on_update | 布尔值 | 设置为true，以便在安装更新后（例如，添加或删除存储库后）将用户重定向到设置 URL。 |
public | 布尔值 | 当您的 GitHub 应用可供公众使用时设置为true，当它仅对应用所有者可用时设置为false。此参数不适用于企业拥有的应用。 |
webhook_active | 布尔值 | 设置为true以启用 Webhook。Webhook 默认情况下处于禁用状态。 |
webhook_url | 字符串 | 您希望将 Webhook 事件有效负载发送到的完整 URL。 |
events | 字符串数组 | Webhook 事件。在注册新的 GitHub 应用时，某些 Webhook 事件需要对资源具有read或write权限才能选择该事件。更多信息，请参阅“GitHub 应用 Webhook 事件”部分。您可以在查询字符串中选择多个事件。例如，events[]=public&events[]=label。 |
single_file_name | 字符串 | 这是一个范围狭窄的权限，允许应用访问任何存储库中的单个文件。当您将single_file权限设置为read或write时，此字段提供了 GitHub 应用将管理的单个文件的路径。如果您需要管理多个文件，请参阅下面的single_file_paths。 |
single_file_paths | 字符串数组 | 这允许应用访问存储库中最多十个指定的文件。当您将single_file权限设置为read或write时，此数组可以存储最多十个 GitHub 应用将管理的文件的路径。所有这些文件都接收由single_file设置的相同权限集，并且没有单独的个体权限。配置两个或更多文件时，API 返回multiple_single_files=true，否则返回multiple_single_files=false。 |
GitHub 应用权限
您可以使用查询参数选择 GitHub 应用注册的权限。对于 URL 查询参数，请使用权限名称作为查询参数名称，并将查询值设置为该权限集的可能值之一。
例如，要在用户界面中为contents选择“读写”权限，您的查询字符串应包含contents=write。要在用户界面中为blocking选择“只读”权限，您的查询字符串应包含blocking=read。要在用户界面中为checks选择“无访问权限”，您的查询字符串不应包含checks权限。
有关权限和 GitHub 应用的更多信息，请参阅“选择 GitHub 应用的权限”。
GitHub 应用 Webhook 事件
您可以使用查询参数启用 GitHub 应用 Webhook，指定 Webhook URL，并订阅应用以接收特定事件的 Webhook 有效负载。
要启用 GitHub 应用 Webhook，请在您的查询字符串中使用webhook_active=true。要指定您希望将 Webhook 事件有效负载发送到的完整 URL，请在您的查询字符串中使用webhook_url。要订阅应用以接收特定 Webhook 有效负载事件，请使用events[]作为查询参数名称，并将查询值设置为 Webhook 事件的名称。有关可能的 Webhook 事件以及订阅每个事件所需的 GitHub 应用权限的更多信息，请参阅“Webhook 事件和有效负载”。
例如，要订阅 GitHub 应用以接收与提交注释相关的活动的 Webhook 有效负载，查询字符串应包含&webhook_active=true&webhook_url=https://example.com&events[]=commit_comment。请注意，commit_commentWebhook 事件要求 GitHub 应用至少对“内容”存储库权限具有读取级别访问权限。因此，您的查询字符串还应包含一个参数，将contents权限设置为read或write。更多信息，请参阅“GitHub 应用权限”。
您不能使用查询参数来设置 Webhook 密钥的值。如果应用需要密钥来保护其 Webhook，则必须由注册应用的人员在 GitHub UI 中设置密钥的值。
有关 Webhook 和 GitHub 应用的更多信息，请参阅“将 Webhook 与 GitHub 应用一起使用”。