REST API 现在已版本化。 有关更多信息，请参阅“关于 API 版本控制”。

分支的 REST API 端点

使用 REST API 修改分支及其保护设置。

列出分支

“列出分支”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”仓库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“列出分支”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必需

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带.git扩展名的仓库名称。名称不区分大小写。

查询参数
protected 布尔值

设置为true仅返回受分支保护或规则集保护的分支。设置为false时，仅返回不受保护的分支。省略此参数将返回所有分支。

per_page 整数

每页结果数（最大 100）。有关更多信息，请参阅“在 REST API 中使用分页”。

默认： 30

page 整数

要获取的结果的页码。有关更多信息，请参阅“在 REST API 中使用分页”。

默认： 1

“列出分支”的 HTTP 响应状态代码

状态码描述
200

确定

404

资源未找到

“列出分支”的代码示例

请求示例

获取/repos/{owner}/{repo}/branches
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/branches

回应

状态：200
[ { "name": "master", "commit": { "sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc", "url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc" }, "protected": true, "protection": { "required_status_checks": { "enforcement_level": "non_admins", "contexts": [ "ci-test", "linter" ] } }, "protection_url": "https://api.github.com/repos/octocat/hello-world/branches/master/protection" } ]

获取分支

“获取分支”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”仓库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“获取分支”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必需

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带.git扩展名的仓库名称。名称不区分大小写。

branch 字符串 必需

分支的名称。不能包含通配符。要在分支名称中使用通配符，请使用GraphQL API。

“获取分支”的 HTTP 响应状态代码

状态码描述
200

确定

301

永久移动

404

资源未找到

“获取分支”的代码示例

请求示例

获取/repos/{owner}/{repo}/branches/{branch}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/branches/BRANCH

回应

状态：200
{ "name": "main", "commit": { "sha": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "node_id": "MDY6Q29tbWl0MTI5NjI2OTo3ZmQxYTYwYjAxZjkxYjMxNGY1OTk1NWE0ZTRkNGU4MGQ4ZWRmMTFk", "commit": { "author": { "name": "The Octocat", "email": "octocat@nowhere.com", "date": "2012-03-06T23:06:50Z" }, "committer": { "name": "The Octocat", "email": "octocat@nowhere.com", "date": "2012-03-06T23:06:50Z" }, "message": "Merge pull request #6 from Spaceghost/patch-1\n\nNew line at end of file.", "tree": { "sha": "b4eecafa9be2f2006ce1b709d6857b07069b4608", "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/b4eecafa9be2f2006ce1b709d6857b07069b4608" }, "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "comment_count": 77, "verification": { "verified": false, "reason": "unsigned", "signature": null, "payload": null } }, "url": "https://api.github.com/repos/octocat/Hello-World/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "html_url": "https://github.com/octocat/Hello-World/commit/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d/comments", "author": { "login": "octocat", "id": 583231, "node_id": "MDQ6VXNlcjU4MzIzMQ==", "avatar_url": "https://avatars.githubusercontent.com/u/583231?v=4", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "committer": { "login": "octocat", "id": 583231, "node_id": "MDQ6VXNlcjU4MzIzMQ==", "avatar_url": "https://avatars.githubusercontent.com/u/583231?v=4", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "parents": [ { "sha": "553c2077f0edc3d5dc5d17262f6aa498e69d6f8e", "url": "https://api.github.com/repos/octocat/Hello-World/commits/553c2077f0edc3d5dc5d17262f6aa498e69d6f8e", "html_url": "https://github.com/octocat/Hello-World/commit/553c2077f0edc3d5dc5d17262f6aa498e69d6f8e" }, { "sha": "762941318ee16e59dabbacb1b4049eec22f0d303", "url": "https://api.github.com/repos/octocat/Hello-World/commits/762941318ee16e59dabbacb1b4049eec22f0d303", "html_url": "https://github.com/octocat/Hello-World/commit/762941318ee16e59dabbacb1b4049eec22f0d303" } ] }, "_links": { "self": "https://api.github.com/repos/octocat/Hello-World/branches/main", "html": "https://github.com/octocat/Hello-World/tree/main" }, "protected": false, "protection": { "enabled": false, "required_status_checks": { "enforcement_level": "off", "contexts": [], "checks": [] } }, "protection_url": "https://api.github.com/repos/octocat/Hello-World/branches/main/protection" }

重命名分支

重命名存储库中的分支。

注意

尽管 API 会立即响应，但分支重命名过程可能需要一些额外的时间才能在后台完成。在重命名过程进行期间，您将无法推送到旧的分支名称。有关更多信息，请参阅“重命名分支”。

经过身份验证的用户必须对分支具有推送访问权限。如果分支是默认分支，则经过身份验证的用户还必须具有管理员或所有者权限。

为了重命名默认分支，细粒度访问令牌还需要administration:write仓库权限。

“重命名分支”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”仓库权限（写入）

“重命名分支”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必需

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带.git扩展名的仓库名称。名称不区分大小写。

branch 字符串 必需

分支的名称。不能包含通配符。要在分支名称中使用通配符，请使用GraphQL API。

正文参数
new_name 字符串 必需

分支的新名称。

“重命名分支”的 HTTP 响应状态代码

状态码描述
201

已创建

403

禁止

404

资源未找到

422

验证失败或端点已被垃圾邮件轰炸。

“重命名分支”的代码示例

请求示例

发布/repos/{owner}/{repo}/branches/{branch}/rename
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/branches/BRANCH/rename \ -d '{"new_name":"my_renamed_branch"}'

回应

状态：201

{ "name": "master", "commit": { "sha": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "node_id": "MDY6Q29tbWl0N2ZkMWE2MGIwMWY5MWIzMTRmNTk5NTVhNGU0ZDRlODBkOGVkZjExZA==", "commit": { "author": { "name": "The Octocat", "date": "2012-03-06T15:06:50-08:00", "email": "octocat@nowhere.com" }, "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "message": "合并拉取请求 #6 来自 Spaceghost/patch-1\n\n在文件末尾添加新行。", "tree": { "sha": "b4eecafa9be2f2006ce1b709d6857b07069b4608", "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/b4eecafa9be2f2006ce1b709d6857b07069b4608" }, "committer": { "name": "The Octocat", "date": "2012-03-06T15:06:50-08:00", "email": "octocat@nowhere.com" }, "verification": { "verified": false, "reason": "unsigned", "signature": null, "payload": null }, "comment_count": 0 }, "author": { "gravatar_id": "", "avatar_url": "https://secure.gravatar.com/avatar/7ad39074b0584bc555d0417ae3e7d974?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png", "url": "https://api.github.com/users/octocat", "id": 583231, "login": "octocat", "node_id": "MDQ6VXNlcjE=", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": true }, "parents": [ { "sha": "553c2077f0edc3d5dc5d17262f6aa498e69d6f8e", "url": "https://api.github.com/repos/octocat/Hello-World/commits/553c2077f0edc3d5dc5d17262f6aa498e69d6f8e" }, { "sha": "762941318ee16e59dabbacb1b4049eec22f0d303", "url": "https://api.github.com/repos/octocat/Hello-World/commits/762941318ee16e59dabbacb1b4049eec22f0d303" } ], "url": "https://api.github.com/repos/octocat/Hello-World/commits/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "committer": { "gravatar_id": "", "avatar_url": "https://secure.gravatar.com/avatar/7ad39074b0584bc555d0417ae3e7d974?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png", "url": "https://api.github.com/users/octocat", "id": 583231, "login": "octocat", "node_id": "MDQ6VXNlcjE=", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": true }, "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e", "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments" }, "_links": { "html": "https://github.com/octocat/Hello-World/tree/master", "self": "https://api.github.com/repos/octocat/Hello-World/branches/master" }, "protected": true, "protection": { "required_status_checks": { "enforcement_level": "non_admins", "contexts": [ "ci-test", "linter" ] } }, "protection_url": "https://api.github.com/repos/octocat/hello-world/branches/master/protection" }

将分支与上游仓库同步

同步派生仓库的分支，使其与上游仓库保持最新。

“将分支与上游仓库同步”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”仓库权限（写入）

“将分支与上游仓库同步”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必需

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带.git扩展名的仓库名称。名称不区分大小写。

正文参数
branch 字符串 必需

应更新以匹配上游的分支名称。

“将分支与上游仓库同步”的 HTTP 响应状态码

状态码描述
200

分支已成功与上游仓库同步

409

由于合并冲突，无法同步分支

422

由于某些其他原因，无法同步分支

“将分支与上游仓库同步”的代码示例

请求示例

post/repos/{owner}/{repo}/merge-upstream
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/merge-upstream \ -d '{"branch":"main"}'

分支已成功与上游仓库同步

状态：200
{ "message": "已成功从上游 defunkt:main 获取并快进", "merge_type": "fast-forward", "base_branch": "defunkt:main" }

合并分支

“合并分支”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”仓库权限（写入）

“合并分支”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必需

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带.git扩展名的仓库名称。名称不区分大小写。

正文参数
base 字符串 必需

将 head 合并到的基分支的名称。

head 字符串 必需

要合并的 head。这可以是分支名称或提交 SHA1。

commit_message 字符串

用于合并提交的提交消息。如果省略，将使用默认消息。

“合并分支”的 HTTP 响应状态码

状态码描述
201

成功响应（生成的合并提交）

204

已合并时的响应

403

禁止

404

当 base 或 head 不存在时未找到

409

当存在合并冲突时发生冲突

422

验证失败或端点已被垃圾邮件轰炸。

“合并分支”的代码示例

请求示例

post/repos/{owner}/{repo}/merges
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/merges \ -d '{"base":"master","head":"cool_feature","commit_message":"Shipped cool_feature!"}'

成功响应（生成的合并提交）

状态：201

{ "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "node_id": "MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==", "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e", "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments", "commit": { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "author": { "name": "Monalisa Octocat", "email": "mona@github.com", "date": "2011-04-14T16:00:49Z" }, "committer": { "name": "Monalisa Octocat", "email": "mona@github.com", "date": "2011-04-14T16:00:49Z" }, "message": "修复所有错误", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e" }, "comment_count": 0, "verification": { "verified": false, "reason": "unsigned", "signature": null, "payload": null } }, "author": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "committer": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e", "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e" } ], "stats": { "additions": 104, "deletions": 4, "total": 108 }, "files": [ { "filename": "file1.txt", "additions": 10, "deletions": 2, "changes": 12, "status": "modified", "raw_url": "https://github.com/octocat/Hello-World/raw/7ca483543807a51b6079e54ac4cc392bc29ae284/file1.txt", "blob_url": "https://github.com/octocat/Hello-World/blob/7ca483543807a51b6079e54ac4cc392bc29ae284/file1.txt", "patch": "@@ -29,7 +29,7 @@\n....." } ] }