Branches
- List Branches
- Get Branch
- Get branch protection
- Update branch protection
- Remove branch protection
- Get required status checks of protected branch
- Update required status checks of protected branch
- Remove required status checks of protected branch
- List required status checks contexts of protected branch
- Replace required status checks contexts of protected branch
- Add required status checks contexts of protected branch
- Remove required status checks contexts of protected branch
- Get restrictions of protected branch
- Remove restrictions of protected branch
- List team restrictions of protected branch
- Replace team restrictions of protected branch
- Add team restrictions of protected branch
- Remove team restrictions of protected branch
- List user restrictions of protected branch
- Replace user restrictions of protected branch
- Add user restrictions of protected branch
- Remove user restrictions of protected branch
The Protected Branch API is currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.loki-preview+json
List Branches
GET /repos/:owner/:repo/branches
Parameters
Name | Type | Description |
---|---|---|
protected |
boolean |
Set to true to only return protected branches |
The Protected Branch API is currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.loki-preview+json
The protected
key will only be present in branch payloads if this header is passed.
Response
Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
<https://api.github.com/resource?page=5>; rel="last"
[
{
"name": "master",
"commit": {
"sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
},
"protected": true,
"protection_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection"
}
]
Get Branch
GET /repos/:owner/:repo/branches/:branch
Response
The Protected Branch API is currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.loki-preview+json
The protected
key will only be present in branch payloads if this header is passed.
Status: 200 OK
{
"name": "master",
"commit": {
"sha": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
"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"
}
},
"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"
},
"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"
}
},
"_links": {
"html": "https://github.com/octocat/Hello-World/tree/master",
"self": "https://api.github.com/repos/octocat/Hello-World/branches/master"
},
"protected": true,
"protection_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection"
}
Get branch protection
GET /repos/:owner/:repo/branches/:branch/protection
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection",
"required_status_checks": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks",
"strict": true,
"contexts": [
"continuous-integration/travis-ci"
],
"contexts_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts"
},
"restrictions": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions",
"users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/users",
"teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/teams",
"users": [
{
"login": "octocat",
"id": 1,
"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
}
],
"teams": [
{
"id": 1,
"url": "https://api.github.com/teams/1",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos"
}
]
}
}
Update branch protection
Protecting a branch requires admin access.
PUT /repos/:owner/:repo/branches/:branch/protection
Parameters
The required_status_checks
object must have the following keys:
Name | Type | Description |
---|---|---|
strict |
boolean |
Required. Require branches to be up to date before merging. |
contexts |
array |
Required. The list of status checks to require in order to merge into this branch |
The restrictions
object must have the following keys:
Name | Type | Description |
---|---|---|
users |
array |
The list of user login s with push access |
teams |
array |
The list of team slug s with push access |
- Teams and users
restrictions
are only available for organization-owned repositories. - The list of users and teams in total is limited to 100 items.
Example
{
"required_status_checks": {
"strict": true,
"contexts": [
"continuous-integration/travis-ci"
]
},
"enforce_admins": true,
"restrictions": {
"users": [
"octocat"
],
"teams": [
"justice-league"
]
}
}
Response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection",
"required_status_checks": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks",
"strict": true,
"contexts": [
"continuous-integration/travis-ci"
],
"contexts_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts"
},
"restrictions": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions",
"users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/users",
"teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/teams",
"users": [
{
"login": "octocat",
"id": 1,
"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
}
],
"teams": [
{
"id": 1,
"url": "https://api.github.com/teams/1",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos"
}
]
}
}
Remove branch protection
DELETE /repos/:owner/:repo/branches/:branch/protection
Status: 204 No Content
Get required status checks of protected branch
GET /repos/:owner/:repo/branches/:branch/protection/required_status_checks
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks",
"strict": true,
"contexts": [
"continuous-integration/travis-ci"
],
"contexts_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts"
}
Update required status checks of protected branch
Updating required status checks requires admin access and branch protection to be enabled.
PATCH /repos/:owner/:repo/branches/:branch/protection/required_status_checks
Parameters
The object passed can have the following keys:
Name | Type | Description |
---|---|---|
strict |
boolean |
Require branches to be up to date before merging. |
contexts |
array |
The list of status checks to require in order to merge into this branch |
Example
{
"strict": true,
"contexts": [
"continuous-integration/travis-ci"
]
}
Response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks",
"strict": true,
"contexts": [
"continuous-integration/travis-ci"
],
"contexts_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts"
}
Remove required status checks of protected branch
DELETE /repos/:owner/:repo/branches/:branch/protection/required_status_checks
Status: 204 No Content
List required status checks contexts of protected branch
GET /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts
Status: 200 OK
[
"continuous-integration/travis-ci"
]
Replace required status checks contexts of protected branch
PUT /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts
Example
[
"continuous-integration/travis-ci"
]
Response
Status: 200 OK
[
"continuous-integration/travis-ci"
]
Add required status checks contexts of protected branch
POST /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts
Example
[
"continuous-integration/jenkins"
]
Response
Status: 200 OK
[
"continuous-integration/travis-ci",
"continuous-integration/jenkins"
]
Remove required status checks contexts of protected branch
DELETE /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts
Example
[
"continuous-integration/jenkins"
]
Response
Status: 200 OK
[
"continuous-integration/travis-ci"
]
Get restrictions of protected branch
Teams and users restrictions
are only available for organization-owned repositories.
GET /repos/:owner/:repo/branches/:branch/protection/restrictions
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions",
"users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/users",
"teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/teams",
"users": [
{
"login": "octocat",
"id": 1,
"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
}
],
"teams": [
{
"id": 1,
"url": "https://api.github.com/teams/1",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos"
}
]
}
Remove restrictions of protected branch
DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions
Status: 204 No Content
List team restrictions of protected branch
GET /repos/:owner/:repo/branches/:branch/protection/restrictions/teams
Status: 200 OK
[
{
"id": 1,
"url": "https://api.github.com/teams/1",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos"
}
]
Replace team restrictions of protected branch
PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/teams
Body parameters
Pass the list of team slug
s with push access.
The list of users and teams in total is limited to 100 items.
Example
[
"justice-league"
]
Response
Status: 200 OK
[
{
"id": 1,
"url": "https://api.github.com/teams/1",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos"
}
]
Add team restrictions of protected branch
POST /repos/:owner/:repo/branches/:branch/protection/restrictions/teams
Body parameters
Pass the list of team slug
s with push access.
The list of users and teams in total is limited to 100 items.
Example
[
"justice-league"
]
Response
Status: 200 OK
[
{
"id": 1,
"url": "https://api.github.com/teams/1",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos"
}
]
Remove team restrictions of protected branch
DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/teams
Example
[
"octocats"
]
Response
Status: 200 OK
[
{
"id": 1,
"url": "https://api.github.com/teams/1",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos"
}
]
List user restrictions of protected branch
GET /repos/:owner/:repo/branches/:branch/protection/restrictions/users
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"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
}
]
Replace user restrictions of protected branch
PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/users
Body parameters
Pass the list of user login
s with push access.
The list of users and teams in total is limited to 100 items.
Example
[
"octocat"
]
Response
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"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
}
]
Add user restrictions of protected branch
POST /repos/:owner/:repo/branches/:branch/protection/restrictions/users
Body parameters
Pass the list of user login
s with push access.
The list of users and teams in total is limited to 100 items.
Example
[
"octocat"
]
Response
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"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
}
]
Remove user restrictions of protected branch
DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/users
Example
[
"defunkt"
]
Response
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"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
}
]