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

您可以使用 URL 查询参数 预选新 GitHub 应用程序 的设置,以快速设置新 GitHub 应用程序 的配置。

关于 GitHub 应用程序 URL 参数

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

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

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

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

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

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

GitHub 应用程序 权限

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

权限描述
管理对用于组织和仓库管理的各种端点授予访问权限。 可以是以下项之一:nonereadwrite
blocking授予对阻止用户 API 的访问权限。 可以是以下项之一:nonereadwrite
检查授予对检查 API 的访问权限。 可以是以下项之一:nonereadwrite
content_references授予对“创建内容附件”端点的访问权限。 可以是以下项之一:nonereadwrite
内容对用于修改仓库内容的各种端点授予访问权限。 可以是以下项之一:nonereadwrite
部署授予对部署 API 的访问权限。 可以是以下项之一:nonereadwrite
emails授予对电子邮件 API 的访问权限。 可以是以下项之一:nonereadwrite
关注者授予对关注者 API 的访问权限。 可以是以下项之一:nonereadwrite
gpg_keys授予对GPG 密钥 API 的访问权限。 可以是以下项之一:nonereadwrite
议题授予对议题 API 的访问权限。 可以是以下项之一:nonereadwrite
授予对公钥 API 的访问权限。 可以是以下项之一:nonereadwrite
members授予管理组织成员的访问权限。 可以是以下项之一:nonereadwrite
元数据授予对不泄漏敏感数据的只读端点的访问权限。 可以是 readnone。 设置任何权限时,默认值为 read;没有为 GitHub 应用程序 指定任何权限时,默认值为 none
organization_administration授予对“更新组织”端点和组织交互限制 API 的访问权限。 可以是以下项之一:nonereadwrite
organization_hooks授予对组织 web 挂钩 API 的访问权限。 可以是以下项之一:nonereadwrite
organization_plan授予使用“获取组织”端点获取有关组织计划的信息的权限。 可以是以下项之一:noneread
organization_projects授予对项目 API 的访问权限。 可以是以下项之一:nonereadwriteadmin
organization_user_blocking授予对阻止组织用户 API 的访问权限。 可以是以下项之一:nonereadwrite
页面授予对页面 API 的访问权限。 可以是以下项之一:nonereadwrite
plan授予使用“获取用户”端点获取有关用户 GitHub 计划的信息的权限。 可以是以下项之一:noneread
pull_requests授予对各种拉取请求端点的访问权限。 可以是以下项之一:nonereadwrite
repository_hooks授予对仓库 web 挂钩 API 的访问权限。 可以是以下项之一:nonereadwrite
repository_projects授予对项目 API 的访问权限。 可以是以下项之一:nonereadwriteadmin
secret_scanning_alerts授予对密钥扫描 API 的访问权限。 可以是以下项之一:nonereadwrite
security_events授予对代码扫描 API 的访问权限。 可以是以下项之一:nonereadwrite
single_file授予对内容 API 的访问权限。 可以是以下项之一:nonereadwrite
标星授予对标星 API 的访问权限。 可以是以下项之一:nonereadwrite
状态授予对状态 API 的访问权限。 可以是以下项之一:nonereadwrite
team_discussions授予对团队讨论 API团队讨论注释 API 的访问权限。 可以是以下项之一:nonereadwrite
vulnerability_alerts授予接收仓库漏洞依赖项安全警报的权限。 更多信息请参阅“关于漏洞依赖项的警报”。 可以是以下项之一:noneread
关注授予列出和更改用户订阅的仓库的权限。 可以是以下项之一:nonereadwrite

GitHub 应用程序 web 挂钩事件

Web 挂钩事件名称所需权限描述
check_run检查检查运行活动已发生。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“检查运行”REST API。
check_suite检查检查套件活动已发生。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“检查套件”REST API。
commit_comment内容提交评论已创建。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“提交评论”REST API。
content_referencecontent_references新的内容引用为 created。 当议题或拉取请求的正文或注释包含与配置的内容引用域匹配的 URL 时,将创建新的内容引用。 有关内容引用和附件的更多信息,请参阅“使用内容附件”。
create内容Git 分支或标签已创建。 更多信息请参阅“Git 数据”REST API。
delete内容Git 分支或标签已删除。 更多信息请参阅“Git 数据”REST API。
deployment部署已创建部署。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“部署”REST API。
deployment_status部署已创建部署。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“部署状态”REST API。
复刻内容用户复刻仓库。 更多信息请参阅“复刻”REST API。
gollum内容创建或更新 wiki 页面。 更多信息请参阅“关于 wikis”。
议题议题与议题相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“议题”REST API。
issue_comment议题与议题或拉取请求评论相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“议题评论”REST API。
标签元数据与标签相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“标签”REST API。
成员members与仓库协作者相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“协作者”REST API。
membershipmembers与团队成员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“团队成员”REST API。
里程碑pull_request与里程碑相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“里程碑”REST API。
org_blockorganization_administration与组织中被阻止人员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“阻止组织用户”REST API。
组织members与组织及其成员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“组织”REST API。
page_build页面表示尝试构建一个 GitHub Pages 站点,无论是否成功。 向 GitHub Pages 启用的分支(项目页面的 gh-pages、用户和组织页面的默认分支)的推送将触发此事件。
projectrepository_projectsorganization_projects与项目板有关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“项目”REST API。
project_cardrepository_projectsorganization_projects与项目卡有关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“项目卡”REST API。
project_columnrepository_projectsorganization_projects与项目板中的列相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“项目列”REST API。
public元数据当私有仓库公开时。 毫无疑问:最好的 GitHub 事件。
pull_requestpull_requests与拉取请求相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“拉取请求”REST API。
pull_request_reviewpull_request与拉取请求审查相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“拉取请求审查”REST API。
pull_request_review_commentpull_request与拉取请求统一差异中的拉取请求审查评论相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“拉取请求审查评论”REST API。
推送内容一个或多个提交被推送到仓库分支或标记。
发行版内容与发行版相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“发行版”REST API。
仓库元数据与仓库相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“仓库”REST API。
repository_dispatch内容允许集成者使用 GitHub Actions 触发自定义事件。
状态状态当 Git 提交的状态发生更改时。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“状态”REST API。
团队members与组织的团队相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“团队”REST API。
team_addmembers仓库被添加到团队时。
查看元数据当有人标星仓库时。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“星标”REST API。

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。