关于 GitHub App URL 参数
您可以将查询参数添� 到这些 URL 中,以便在个人或组织帐户上预选 GitHub App 的配置:
- 个人帐户:
http(s)://HOSTNAME/settings/apps/new
- 组织帐户:
http(s)://HOSTNAME/organizations/:org/settings/apps/new
创建应用程序的人在提交应用程序之前,可以从 GitHub App 注册页面编辑预选值。 如果� 没有在 URL 查询字符串中包含必需的参数(如 name
),则创建应用的人需要在提交该应用之前输入值。
对于需要密钥来保护其 web 挂钩的应用,该密钥的价值必须由应用创建者以该形式设置,而不是通过使用查询参数。 有关详细信息,请参阅“保护 Webhook”。
以下 URL 使用预配置的说明和回调 URL 创建名为 octocat-github-app
的新公共应用。 此 URL 还选择了 checks
的读取和写入权限,订阅了 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&events[]=check_run&events[]=check_suite
下面� 节列出了可用查询参数、权限和事件的完整列表。
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 。 |
request_oauth_on_install | boolean | 如果� 的应用使用 OAuth 流授权用户,� 可将此选项设置为 true ,以允许用户在安装应用时授权它,从而省去一个步骤。 如果选择此选项,setup_url 将不可用,并且用户将在安装应用后被重定向到 callback_url 。 |
setup_url | string | 在用户安装 GitHub App 后重定向到的完整 URL(如果应用程序在安装之后需要额外设置)。 |
setup_on_update | boolean | 设置为 true 可在更新安装后(例如在添� 或� 除存储库之后)将用户重定向到设置 URL。 |
public | boolean | 当 GitHub App 可供公众使用时,设置为 true ;当它仅供应用的所有者访问时,设置为 false 。 |
webhook_active | boolean | 设置为 false 以禁用 Webhook。 Web 挂钩默认启用。 |
webhook_url | string | 要向其发送 web 挂钩事件有效负载的完整 URL。 |
events | array of strings | Webhook 事件。 某些 Webhook 事件需要� 对资源有 read 或 write 权限,才能在注册新 GitHub App 时选择事件。 有关可用事件及其所需权限,请参阅“GitHub App Webhook 事件”一节。 您可以在查询字符串中选择多个事件。 例如 events[]=public&events[]=label 。 |
domain | string | 内容引用的 URL。 |
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 权限
您可以在查询字符串中选择权限:使用下表中的权限名称作为查询参数名称,使用权限类型作为查询值。 例如,要在用户界面中为 contents
选择 Read & write
权限,� 的查询字符串将包括 &contents=write
。 要在用户界面中为 blocking
选择 Read-only
权限,� 的查询字符串将包括 &blocking=read
。 要在用户界面中为 checks
选择 no-access
,� 的查询字符串将不包括 checks
权限。
权限 | 说明 |
---|---|
administration | 对用于组织和仓库管理的各种端点授予访问权限。 可以是以下选项之一:none 、read 或 write 。 |
checks | 授予对检查 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
content_references | 授予对“创建内容附件”终结点的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
contents | 对用于修改仓库内容的各种端点授予访问权限。 可以是以下选项之一:none 、read 或 write 。 |
deployments | 授予对部署 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
emails | 授予对电子邮件 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
followers | 授予对关注者 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
gpg_keys | 授予对 GPG 密钥 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
issues | 授予对问题 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
keys | 授予对公钥 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
members | 授予管理组织成员的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
organization_hooks | 授予对组织 Webhook API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
organization_plan | 授予使用“获取组织”终结点获取有关组织计划的信息的权限。 可以是以下选项之一:none 或 read 。 |
organization_projects | 授予对项目 API 的访问权限。 可以是以下选项之一:none 、read 、write 或 admin 。 |
pages | 授予对页面 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
plan | 授予使用“获取用户”终结点获取有关用户的 GitHub 计划的信息的权限。 可以是以下选项之一:none 或 read 。 |
pull_requests | 授予对各种拉取请求端点的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
repository_hooks | 授予对存储库 Webhook API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
repository_projects | 授予对项目 API 的访问权限。 可以是以下选项之一:none 、read 、write 或 admin 。 |
secret_scanning_alerts | 授予对机密扫描 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
security_events | 授予对代� �扫描 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
single_file | 授予对内容 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
starring | 授予对� �星 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
statuses | 授予对状态 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
team_discussions | 授予对团队讨论 API 和团队讨论评论 API 的访问权限。 可以是以下选项之一:none 、read 或 write 。 |
vulnerability_alerts | 授予访问权限以接收存储库中的 Dependabot alerts。 有关详细信息,请参阅“关于 Dependabot alerts”。 可以是以下选项之一:none 或 read 。 |
watching | 授予列出和更改用户订阅的仓库的权限。 可以是以下选项之一:none 、read 或 write 。 |
GitHub App web 挂钩事件
Web 挂钩事件名称 | 必需的权限 | 说明 |
---|---|---|
check_run | checks | 检查运行活动已发生。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“检查运行”REST API。 |
check_suite | checks | 检查套件活动已发生。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“检查套件”REST API。 |
commit_comment | contents | 提交评论已创建。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“提交评论”REST API。 |
content_reference | content_references | 新的内容引用为 created 。 当议题或拉取请求的正文或注释包含与配置的内容引用域匹配的 URL 时,将创建新的内容引用。 有关详细信息,请参阅“使用内容附件”详细了解内容引用和附件。 |
create | contents | Git 分支或� �签已创建。 有关详细信息,请参阅“Git 数据库”REST API。 |
delete | contents | Git 分支或� �签已� 除。 有关详细信息,请参阅“Git 数据库”REST API。 |
deployment | deployments | 已创建部署。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“部署”REST API。 |
deployment_status | deployments | 已创建部署。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“部署”REST API。 |
fork | contents | 用户复刻仓库。 有关详细信息,请参阅“复刻”REST API。 |
gollum | contents | 创建或更新 wiki 页面。 有关详细信息,请参阅“关于 Wikis”。 |
issues | issues | 与议题相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“问题”REST API。 |
issue_comment | issues | 与议题或拉取请求评论相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“发布评论”REST API。 |
label | metadata | 与� �签相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“� �签”REST API。 |
member | members | 与仓库协作者相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“协作者”REST API。 |
membership | members | 与团队成员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“团队成员”REST API。 |
milestone | pull_request | 与里程碑相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“里程碑”REST API。 |
organization | members | 与组织及其成员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“组织”REST API。 |
page_build | pages | 表示尝试构建一个 GitHub Pages 站点,� 论是否成功。 向 GitHub Pages 启用的分支(项目页面的 gh-pages 、用户和组织页面的默认分支)的推送将触发此事件。 |
project | repository_projects 或 organization_projects | 与 项目版块 相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“项目”REST API。 |
project_card | repository_projects 或 organization_projects | 与 项目版块 中的卡相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“项目卡”REST API。 |
project_column | repository_projects 或 organization_projects | 与 项目版块 中的列相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“项目列”REST API。 |
public | metadata | 当私有仓库公开时。 毫� 疑问:最好的 GitHub Enterprise Server 事件。 |
pull_request | pull_requests | 与拉取请求相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“拉取请求”REST API。 |
pull_request_review | pull_request | 与拉取请求审查相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“拉取请求审查”REST API。 |
pull_request_review_comment | pull_request | 与拉取请求统一差异中的拉取请求审查评论相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“拉取请求审查评论”REST API。 |
pull_request_review_thread | pull_request | 与拉取请求的批注线程相关的活动� �记为已解决或未解决。 活动类型在有效负载对象的 action 属性中指定。 |
push | contents | 一个或多个提交被推送到仓库分支或� �记。 |
release | contents | 与发行版相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“发行版”REST API。 |
repository | metadata | 与仓库相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“存储库”REST API。 |
status | statuses | 当 Git 提交的状态发生更改时。 有关详细信息,请参阅“状态”REST API。 |
team | members | 与组织的团队相关的活动。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“团队”REST API。 |
team_add | members | 存储库添� 到团队时。 |
watch | metadata | 当有人� �星仓库时。 活动类型在有效负载对象的 action 属性中指定。 有关详细信息,请参阅“� �星”REST API。 |