Skip to main content
我们经常发布文档更新,此页面的翻译可能仍在进行中。 有关最新信息,请访问英语文档

使用 URL 参数创建 GitHub 应用程序

你可以使用 URL 查询参数来预选择新 GitHub App 的设置,从而快速设置新 GitHub App 的配置。

关于 GitHub App URL 参数

您可以将查询参数添加到这些 URL 中,以便在个人或组织帐户上预选 GitHub App 的配置:

  • 个人帐户:https://github.com/settings/apps/new
  • 组织帐户:https://github.com/organizations/:org/settings/apps/new

创建应用程序的人在提交应用程序之前,可以从 GitHub App 注册页面编辑预选值。 如果你没有在 URL 查询字符串中包含必需的参数(如 name),则创建应用的人需要在提交该应用之前输入值。

对于需要密钥来保护其 web 挂钩的应用,该密钥的价值必须由应用创建者以该形式设置,而不是通过使用查询参数。 有关详细信息,请参阅“保护 Webhook”。

以下 URL 使用预配置的说明和回调 URL 创建名为 octocat-github-app 的新公共应用。 此 URL 还选择了 checks 的读取和写入权限,订阅了 check_runcheck_suite Webhook 事件,并选择了在安装过程中请求用户授权 (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&events[]=check_run&events[]=check_suite

下面几节列出了可用查询参数、权限和事件的完整列表。

GitHub App 配置参数

名称类型说明
namestringGitHub App 的名称。 给应用程序一个清晰简洁的名称。 应用程序不能与现有 GitHub 用户同名,除非它是您自己的用户或组织的名称。 当您的集成执行操作时,应用程序名称的缓存版本将显示在用户界面上。
descriptionstringGitHub App 的说明。
urlstring您的 GitHub App 网站主页的完整 URL。
callback_urlsarray of strings在用户授权安装后重定向到的完整 URL。 您可以提供最多 10 个回叫 URL。 如果应用程序需要识别和授权用户到服务器的请求,则使用这些 URL。 例如,callback_urls[]=https://example.com&callback_urls[]=https://example-2.com
request_oauth_on_installboolean如果你的应用使用 OAuth 流授权用户,你可将此选项设置为 true,以允许用户在安装应用时授权它,从而省去一个步骤。 如果选择此选项,setup_url 将不可用,并且用户将在安装应用后被重定向到 callback_url
setup_urlstring在用户安装 GitHub App 后重定向到的完整 URL(如果应用程序在安装之后需要额外设置)。
setup_on_updateboolean设置为 true 可在更新安装后(例如在添加或删除存储库之后)将用户重定向到设置 URL。
publicboolean当 GitHub App 可供公众使用时,设置为 true;当它仅供应用的所有者访问时,设置为 false
webhook_activeboolean设置为 false 以禁用 Webhook。 Web 挂钩默认启用。
webhook_urlstring要向其发送 web 挂钩事件有效负载的完整 URL。
eventsarray of stringsWebhook 事件。 某些 Webhook 事件需要你对资源有 readwrite 权限,才能在注册新 GitHub App 时选择事件。 有关可用事件及其所需权限,请参阅“GitHub App Webhook 事件”一节。 您可以在查询字符串中选择多个事件。 例如 events[]=public&events[]=label
single_file_namestring这是一种范围狭窄的权限,允许应用程序访问任何仓库中的单个文件。 将 single_file 权限设置为 readwrite 时,此字段提供 GitHub App 将要管理的单个文件的路径。 如果需要管理多个文件,请参阅下面的 single_file_paths
single_file_pathsarray of strings这允许应用程序访问仓库中的最多 10 个指定文件。 将 single_file 权限设置为 readwrite 时,此数组可存储 GitHub App 将要管理的最多 10 个文件的路径。 这些文件都接收由 single_file 设置的相同权限,没有单独的权限。 配置了两个或更多文件时,API 将返回 multiple_single_files=true,否则它将返回 multiple_single_files=false

GitHub App 权限

您可以在查询字符串中选择权限:使用下表中的权限名称作为查询参数名称,使用权限类型作为查询值。 例如,要在用户界面中为 contents 选择 Read & write 权限,你的查询字符串将包括 &contents=write。 要在用户界面中为 blocking 选择 Read-only 权限,你的查询字符串将包括 &blocking=read。 要在用户界面中为 checks 选择 no-access,你的查询字符串将不包括 checks 权限。

权限说明
administration对用于组织和仓库管理的各种端点授予访问权限。 可以是以下选项之一:nonereadwrite
blocking授予对阻止用户 API 的访问权限。 可以是以下选项之一:nonereadwrite
checks授予对检查 API 的访问权限。 可以是以下选项之一:nonereadwrite
contents对用于修改仓库内容的各种端点授予访问权限。 可以是以下选项之一:nonereadwrite
deployments授予对部署 API 的访问权限。 可以是以下选项之一:nonereadwrite
emails授予对电子邮件 API 的访问权限。 可以是以下选项之一:nonereadwrite
followers授予对关注者 API 的访问权限。 可以是以下选项之一:nonereadwrite
gpg_keys授予对 GPG 密钥 API 的访问权限。 可以是以下选项之一:nonereadwrite
issues授予对问题 API 的访问权限。 可以是以下选项之一:nonereadwrite
keys授予对公钥 API 的访问权限。 可以是以下选项之一:nonereadwrite
members授予管理组织成员的访问权限。 可以是以下选项之一:nonereadwrite
metadata授予对不泄漏敏感数据的只读端点的访问权限。 可以是 readnone。 设置任何权限时,默认值为 read;没有为 GitHub App 指定任何权限时,默认值为 none
organization_administration授予对“更新组织”终结点和“组织交互限制 API”的访问权限。 可以是以下选项之一:nonereadwrite
organization_hooks授予对组织 Webhook API 的访问权限。 可以是以下选项之一:nonereadwrite
organization_plan授予使用“获取组织”终结点获取有关组织计划的信息的权限。 可以是以下选项之一:noneread
organization_projects授予对项目 API 的访问权限。 可以是以下选项之一:nonereadwriteadmin
organization_user_blocking授予对阻止组织用户 API 的访问权限。 可以是以下选项之一:nonereadwrite
pages授予对页面 API 的访问权限。 可以是以下选项之一:nonereadwrite
plan授予使用“获取用户”终结点获取有关用户的 GitHub 计划的信息的权限。 可以是以下选项之一:noneread
pull_requests授予对各种拉取请求端点的访问权限。 可以是以下选项之一:nonereadwrite
repository_hooks授予对存储库 Webhook API 的访问权限。 可以是以下选项之一:nonereadwrite
repository_projects授予对项目 API 的访问权限。 可以是以下选项之一:nonereadwriteadmin
security_events授予对代码扫描 API 的访问权限。 可以是以下选项之一:nonereadwrite
single_file授予对内容 API 的访问权限。 可以是以下选项之一:nonereadwrite
starring授予对标星 API 的访问权限。 可以是以下选项之一:nonereadwrite
statuses授予对状态 API 的访问权限。 可以是以下选项之一:nonereadwrite
team_discussions授予对团队讨论 API团队讨论评论 API 的访问权限。 可以是以下选项之一:nonereadwrite
vulnerability_alerts授予访问权限以接收存储库中的 Dependabot alerts。 有关详细信息,请参阅“关于 Dependabot alerts”。 可以是以下选项之一:nonereadwrite
watching授予列出和更改用户订阅的仓库的权限。 可以是以下选项之一:nonereadwrite

GitHub App web 挂钩事件

Web 挂钩事件名称必需的权限说明
check_runchecks检查运行活动已发生。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“检查运行”REST API。
check_suitechecks检查套件活动已发生。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“检查套件”REST API。
commit_commentcontents提交评论已创建。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“提交评论”REST API。
createcontentsGit 分支或标签已创建。 有关详细信息,请参阅“Git 数据库”REST API。
deletecontentsGit 分支或标签已删除。 有关详细信息,请参阅“Git 数据库”REST API。
deploymentdeployments已创建部署。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“部署”REST API。
deployment_statusdeployments已创建部署。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“部署”REST API。
forkcontents用户复刻仓库。 有关详细信息,请参阅“复刻”REST API。
gollumcontents创建或更新 wiki 页面。 有关详细信息,请参阅“关于 Wikis”。
issuesissues与议题相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“问题”REST API。
issue_commentissues与议题或拉取请求评论相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“发布评论”REST API。
labelmetadata与标签相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“标签”REST API。
membermembers与仓库协作者相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“协作者”REST API。
membershipmembers与团队成员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“团队成员”REST API。
milestonepull_request与里程碑相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“里程碑”REST API。
org_blockorganization_administration与组织中被阻止人员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“阻止组织用户”REST API。
organizationmembers与组织及其成员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“组织”REST API。
page_buildpages表示尝试构建一个 GitHub Pages 站点,无论是否成功。 向 GitHub Pages 启用的分支(项目页面的 gh-pages、用户和组织页面的默认分支)的推送将触发此事件。
projectrepository_projectsorganization_projects与 classic projects 相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“项目”REST API。
project_cardrepository_projectsorganization_projects与 classic project 中的卡相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“项目卡”REST API。
project_columnrepository_projectsorganization_projects与 classic project 中的列相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“项目列”REST API。
publicmetadata当私有仓库公开时。 毫无疑问:最好的 GitHub 事件。
pull_requestpull_requests与拉取请求相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“拉取请求”REST API。
pull_request_reviewpull_request与拉取请求审查相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“拉取请求审查”REST API。
pull_request_review_commentpull_request与拉取请求统一差异中的拉取请求审查评论相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“拉取请求审查评论”REST API。
pull_request_review_threadpull_request与拉取请求的批注线程相关的活动标记为已解决或未解决。 活动类型在有效负载对象的 action 属性中指定。
pushcontents一个或多个提交被推送到仓库分支或标记。
releasecontents与发行版相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“发行版”REST API。
repositorymetadata与仓库相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“存储库”REST API。
repository_dispatchcontents允许集成者使用 GitHub Actions 触发自定义事件。
statusstatuses当 Git 提交的状态发生更改时。 有关详细信息,请参阅“状态”REST API。
teammembers与组织的团队相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“团队”REST API。
team_addmembers存储库添加到团队时。
watchmetadata当有人标星仓库时。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“标星”REST API。