Skip to main content

We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the new Branches, Collaborators, Commits, Deploy Keys, Deployments, GitHub Pages, Releases, Metrics, Webhooks REST API pages.

分支

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

List branches

参数

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

Query parameters
Name, Type, Description
protectedboolean

Setting to true returns only protected branches. When set to false, only unprotected branches are returned. Omitting this parameter returns all branches.

per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP 响应状态代码

状态代码说明
200

OK

404

Resource not found

代码示例

get/repos/{owner}/{repo}/branches
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/repos/OWNER/REPO/branches

Response

Status: 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" } ]

Get a branch

参数

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

branchstringRequired

The name of the branch.

HTTP 响应状态代码

状态代码说明
200

OK

301

Moved permanently

404

Resource not found

代码示例

get/repos/{owner}/{repo}/branches/{branch}
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/repos/OWNER/REPO/branches/BRANCH

Response

Status: 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" }

Sync a fork branch with the upstream repository

Sync a branch of a forked repository to keep it up-to-date with the upstream repository.

参数

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

Body parameters
Name, Type, Description
branchstringRequired

The name of the branch which should be updated to match upstream.

HTTP 响应状态代码

状态代码说明
200

The branch has been successfully synced with the upstream repository

409

The branch could not be synced because of a merge conflict

422

The branch could not be synced for some other reason

代码示例

post/repos/{owner}/{repo}/merge-upstream
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/repos/OWNER/REPO/merge-upstream \ -d '{"branch":"main"}'

The branch has been successfully synced with the upstream repository

Status: 200
{ "message": "Successfully fetched and fast-forwarded from upstream defunkt:main", "merge_type": "fast-forward", "base_branch": "defunkt:main" }

Merge a branch

参数

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

Body parameters
Name, Type, Description
basestringRequired

The name of the base branch that the head will be merged into.

headstringRequired

The head to merge. This can be a branch name or a commit SHA1.

commit_messagestring

Commit message to use for the merge commit. If omitted, a default message will be used.

HTTP 响应状态代码

状态代码说明
201

Successful Response (The resulting merge commit)

204

Response when already merged

403

Forbidden

404

Not Found when the base or head does not exist

409

Conflict when there is a merge conflict

422

Validation failed, or the endpoint has been spammed.

代码示例

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

Successful Response (The resulting merge commit)

Status: 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": "Fix all the bugs", "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....." } ] }