我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

此版本的 GitHub Enterprise 已停止服务 2020-11-12. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

Creating a GitHub App using URL parameters

You can preselect the settings of a new GitHub 应用程序 using URL query parameters to quickly set up the new GitHub 应用程序's configuration.

本文内容

About GitHub 应用程序 URL parameters

You can add query parameters to these URLs to preselect the configuration of a GitHub 应用程序 on a personal or organization account:

  • User account: http(s)://[hostname]/settings/apps/new
  • Organization account: http(s)://[hostname]/:org/settings/apps/new

The person creating the app can edit the preselected values from the GitHub 应用程序 registration page, before submitting the app. If you do not include required parameters in the URL query string, like name, the person creating the app will need to input a value before submitting the app.

The following URL creates a new public app called octocat-github-app with a preconfigured description and callback URL. This URL also selects read and write permissions for checks, subscribes to the check_run and check_suite webhook events, and selects the option to request user authorization (OAuth) during installation:

http(s)://[hostname]/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_url=https://example.com&request_oauth_on_install=true&public=true&checks=write&events[]=check_run&events[]=check_suite

The complete list of available query parameters, permissions, and events is listed in the sections below.

GitHub 应用程序 configuration parameters

名称类型描述
name字符串The name of the GitHub 应用程序. Give your app a clear and succinct name. Your app cannot have the same name as an existing GitHub user, unless it is your own user or organization name. A slugged version of your app's name will be shown in the user interface when your integration takes an action.
说明字符串A description of the GitHub 应用程序.
url字符串The full URL of your GitHub 应用程序's website homepage.
callback_url字符串The full URL to redirect to after someone authorizes an installation. This URL is used if your app needs to identify and authorize user-to-server requests.
request_oauth_on_install布尔值If your app authorizes users using the OAuth flow, you can set this option to true to allow people to authorize the app when they install it, saving a step. If you select this option, the setup_url becomes unavailable and users will be redirected to your callback_url after installing the app.
setup_url字符串The full URL to redirect to after someone installs the GitHub 应用程序 if the app requires additional setup after installation.
setup_on_update布尔值Set to true to redirect people to the setup URL when installations have been updated, for example, after repositories are added or removed.
public布尔值Set to true when your GitHub 应用程序 is available to the public or false when it is only accessible to the owner of the app.
webhook_url字符串The full URL that you would like to send webhook event payloads to.
webhook_secret字符串You can specify a secret to secure your webhooks. See "Securing your webhooks" for more details.
事件字符串数组Web 挂钩事件. Some webhook events require read or write permissions for a resource before you can select the event when registering a new GitHub 应用程序. See the "GitHub 应用程序 webhook events" section for available events and their required permissions. You can select multiple events in a query string. For example, events[]=public&events[]=label.
字符串The URL of a content reference.
single_file_name字符串This is a narrowly-scoped permission that allows the app to access a single file in any repository. When you set the single_file permission to read or write, this field provides the path to the single file your GitHub 应用程序 will manage.

GitHub 应用程序 permissions

You can select permissions in a query string using the permission name in the following table as the query parameter name and the permission type as the query value. For example, to select Read & write permissions in the user interface for contents, your query string would include &contents=write. To select Read-only permissions in the user interface for blocking, your query string would include &blocking=read. To select no-access in the user interface for checks, your query string would not include the checks permission.

权限描述
管理Grants access to various endpoints for organization and repository administration. Can be one of: none, read, or write.
检查Grants access to the Checks API. Can be one of: none, read, or write.
content_referencesGrants access to the "Create a content attachment" endpoint. Can be one of: none, read, or write.
内容Grants access to various endpoints that allow you to modify repository contents. Can be one of: none, read, or write.
部署Grants access to the Deployments API. Can be one of: none, read, or write.
emailsGrants access to the Emails API. Can be one of: none, read, or write.
关注者Grants access to the Followers API. Can be one of: none, read, or write.
gpg_keysGrants access to the GPG Keys API. Can be one of: none, read, or write.
issuesGrants access to the Issues API. Can be one of: none, read, or write.
Grants access to the Public Keys API. Can be one of: none, read, or write.
membersGrants access to manage an organization's members. Can be one of: none, read, or write.
organization_hooksGrants access to the Organization Webhooks API. Can be one of: none, read, or write.
organization_planGrants access to get information about an organization's plan using the "Get an organization" endpoint. Can be one of: none or read.
organization_projectsGrants access to the Projects API. Can be one of: none, read, write, or admin.
页面Grants access to the Pages API. Can be one of: none, read, or write.
planGrants access to get information about a user's GitHub plan using the "Get a user" endpoint. Can be one of: none or read.
pull_requestsGrants access to various pull request endpoints. Can be one of: none, read, or write.
repository_hooksGrants access to the Repository Webhooks API. Can be one of: none, read, or write.
repository_projectsGrants access to the Projects API. Can be one of: none, read, write, or admin.
single_fileGrants access to the Contents API. Can be one of: none, read, or write.
标星Grants access to the Starring API. Can be one of: none, read, or write.
statusesGrants access to the Statuses API. Can be one of: none, read, or write.
team_discussionsGrants access to the Team Discussions API and the Team Discussion Comments API. Can be one of: none, read, or write.
vulnerability_alertsGrants access to receive security alerts for vulnerable dependencies in a repository. See "About security alerts for vulnerable dependencies" to learn more. Can be one of: none or read.
关注Grants access to list and change repositories a user is subscribed to. Can be one of: none, read, or write.

GitHub 应用程序 webhook events

Web 挂钩事件名称Required permission描述
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”。
issuesissues与议题相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“议题”REST API。
issue_commentissues与议题评论相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“议题评论”REST API。
标签元数据与议题相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“标签”REST API。
成员members与仓库协作者相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“协作者”REST API。
membershipmembers与团队成员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“团队成员”REST API。
里程碑pull_request与里程碑相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“里程碑”REST API。
组织members与组织及其成员相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“组织”REST API。
page_build页面表示尝试构建一个 GitHub Pages 站点,无论是否成功。 向 GitHub Pages 启用的分支(项目页面的 gh-pages、用户和组织页面的默认分支)的推送将触发此事件。
projectrepository_projects or organization_projects与项目板有关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“项目”REST API。
project_cardrepository_projects or organization_projects与项目卡有关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“项目卡”REST API。
project_columnrepository_projects or organization_projects与项目板中的列相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“项目列”REST API。
public元数据当私有仓库公开时。 毫无疑问:最好的 GitHub Enterprise Server 事件。
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。
状态statuses当 Git 提交的状态发生更改时。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“状态”REST API。
团队members与组织的团队相关的活动。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“团队”REST API。
team_addmembers仓库被添加到团队时。
查看元数据当有人标星仓库时。 活动类型在有效负载对象的 action 属性中指定。 更多信息请参阅“星标”REST API。