Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.

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.

Branches

Utilisez l’API REST pour modifier des branches et leurs paramètres de protection.

List branches

Compatible avec GitHub Apps

Paramètres

En-têtes
Nom, Type, Description
acceptstring

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

Paramètres de chemin d’accès
Nom, Type, Description
ownerstringObligatoire

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

repostringObligatoire

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

Paramètres de requête
Nom, 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

Codes de statut de réponse HTTP

Code d’étatDescription
200

OK

404

Resource not found

Exemples de code

get/repos/{owner}/{repo}/branches
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://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

Compatible avec GitHub Apps

Paramètres

En-têtes
Nom, Type, Description
acceptstring

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

Paramètres de chemin d’accès
Nom, Type, Description
ownerstringObligatoire

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

repostringObligatoire

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

branchstringObligatoire

The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API.

Codes de statut de réponse HTTP

Code d’étatDescription
200

OK

301

Moved permanently

404

Resource not found

Exemples de code

get/repos/{owner}/{repo}/branches/{branch}
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://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" }

Rename a branch

Compatible avec GitHub Apps

Renames a branch in a repository.

Note: Although the API responds immediately, the branch rename process might take some extra time to complete in the background. You won't be able to push to the old branch name while the rename process is in progress. For more information, see "Renaming a branch".

The permissions required to use this endpoint depends on whether you are renaming the default branch.

To rename a non-default branch:

  • Users must have push access.
  • GitHub Apps must have the contents:write repository permission.

To rename the default branch:

  • Users must have admin or owner permissions.
  • GitHub Apps must have the administration:write repository permission.

Paramètres

En-têtes
Nom, Type, Description
acceptstring

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

Paramètres de chemin d’accès
Nom, Type, Description
ownerstringObligatoire

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

repostringObligatoire

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

branchstringObligatoire

The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API.

Paramètres du corps
Nom, Type, Description
new_namestringObligatoire

The new name of the branch.

Codes de statut de réponse HTTP

Code d’étatDescription
201

Created

403

Forbidden

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

Exemples de code

post/repos/{owner}/{repo}/branches/{branch}/rename
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/branches/BRANCH/rename \ -d '{"new_name":"my_renamed_branch"}'

Response

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

Sync a fork branch with the upstream repository

Compatible avec GitHub Apps

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

Paramètres

En-têtes
Nom, Type, Description
acceptstring

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

Paramètres de chemin d’accès
Nom, Type, Description
ownerstringObligatoire

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

repostringObligatoire

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

Paramètres du corps
Nom, Type, Description
branchstringObligatoire

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

Codes de statut de réponse HTTP

Code d’étatDescription
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

Exemples de code

post/repos/{owner}/{repo}/merge-upstream
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://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

Compatible avec GitHub Apps

Paramètres

En-têtes
Nom, Type, Description
acceptstring

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

Paramètres de chemin d’accès
Nom, Type, Description
ownerstringObligatoire

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

repostringObligatoire

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

Paramètres du corps
Nom, Type, Description
basestringObligatoire

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

headstringObligatoire

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.

Codes de statut de réponse HTTP

Code d’étatDescription
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.

Exemples de code

post/repos/{owner}/{repo}/merges
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://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....." } ] }