关于用于注册的 URL 参数 GitHub Apps
可以使用 URL 参数预先选择新 GitHub App 注册的配置设置，并与其他人共享自定义链接。 该链接会将用户带到 GitHub App 注册页面，其中应用设置将根据 URL 中包含的 URL 参数预先填充。
此方法对于希望客户按特定要求在客户的个人帐户或组织中设置应用程序的集成商非常有用；也适用于使用 GitHub Enterprise Server 且无法从 GitHub Marketplace 安装应用程序的客户。
或者，您也可以创建一个 GitHub App 清单。 有关详细信息，请参阅“从manifest文件注册GitHub应用”。
使用查询参数创建自定义配置 URL
若要为 GitHub App 个人或组织帐户创建自定义配置 URL，请在以下基 URL 后面添加查询参数。
- 若要在个人帐户上注册应用，请将 URL 参数添加到：
http(s)://HOSTNAME/settings/apps/new - 若要在组织帐户上注册应用，请将 URL 参数添加到：
http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new。 将ORGANIZATION替换为要让客户在其中注册应用的组织的名称。 - 要在企业帐户上注册应用，请将 URL 参数添加到：
http(s)://HOSTNAME/enterprises/ENTERPRISE/settings/apps/new。 替换为ENTERPRISE你希望客户注册应用的企业的名称。
在应用注册页上，注册应用的人员可以在提交应用之前编辑预先选择的值。 如果没有在 URL 查询字符串中包含所需值（如 name）的参数，则注册应用的人员需要在注册该应用之前输入值。
例如，以下 URL 可在个人帐户上注册名为 octocat-github-app 的新公共应用。 使用查询参数，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:/。 有关详细信息，请参阅“关于用户授权回调 URL”。 |
request_oauth_ | boolean | 如果你的应用使用 OAuth 流授权用户，你可将此选项设置为 true，以允许用户在安装应用时授权它，从而省去一个步骤。 如果选择此选项，setup_url 将不可用，并且用户将在安装应用后被重定向到 callback_url。 |
setup_url | string | 如果该应用在安装后需要额外设置，这是用户安装 GitHub App 后要重定向到的完整 URL。 有关详细信息，请参阅“关于设置 URL”。 |
setup_on_update | boolean | 设置为 true 可在更新安装后（例如在添加或删除存储库之后）将用户重定向到设置 URL。 |
public | boolean | 当你的true可供公众使用时，设置为GitHub App；当仅供应用所有者访问时，设置为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 管理的十个文件的路径。 这些文件都接收由 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 Webhook 事件
可以使用查询参数启用 GitHub App Webhook、指定 Webhook URL，并订阅应用以接收特定事件的 Webhook 有效负载。
若要启用 GitHub App 网络钩子，请在查询字符串中使用 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”存储库权限至少具有读取级别的访问权限。 因此，查询字符串还应包含一个参数，用于将 contents 权限设置为 read 或 write。 有关详细信息，请参阅 GitHub 应用权限。
无法使用查询参数设置 Webhook 密钥的值。 如果应用需要机密来保护其 Webhook，则必须由注册应用的人员在 GitHub UI 中设置机密的值。
有关 webhook 和 GitHub Apps 的详细信息，请参阅 将 Webhook 与 GitHub 应用配合使用。