List organization repositories
Lists repositories for the specified organization.
get /orgs/{org}/repos
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
org |
string | path | |
type |
string | query |
Specifies the types of repositories you want returned. Can be one of |
sort |
string | query |
Can be one of |
direction |
string | query |
Can be one of |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/orgs/ORG/repos
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/repos', {
org: 'org'
})
Default response
Status: 200 OK
[
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"template_repository": null,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false,
"license": {
"key": "mit",
"name": "MIT License",
"spdx_id": "MIT",
"url": "https://api.github.com/licenses/mit",
"node_id": "MDc6TGljZW5zZW1pdA=="
}
}
]
Notes
Preview notice
The is_template
and template_repository
keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.baptiste-preview+json
Create an organization repository
Creates a new repository in the specified organization. The authenticated user must be a member of the organization.
OAuth scope requirements
When using OAuth, authorizations must include:
public_repo
scope orrepo
scope to create a public repositoryrepo
scope to create a private repository
post /orgs/{org}/repos
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
org |
string | path | |
name |
string | body |
Required. The name of the repository. |
description |
string | body |
A short description of the repository. |
homepage |
string | body |
A URL with more information about the repository. |
private |
boolean | body |
Either |
has_issues |
boolean | body |
Either true
|
has_projects |
boolean | body |
Either true
|
has_wiki |
boolean | body |
Either true
|
is_template |
boolean | body |
Either |
team_id |
integer | body |
The id of the team that will be granted access to this repository. This is only valid when creating a repository in an organization. |
auto_init |
boolean | body |
Pass |
gitignore_template |
string | body |
Desired language or platform .gitignore template to apply. Use the name of the template without the extension. For example, "Haskell". |
license_template |
string | body |
Choose an open source license template that best suits your needs, and then use the license keyword as the |
allow_squash_merge |
boolean | body |
Either true
|
allow_merge_commit |
boolean | body |
Either true
|
allow_rebase_merge |
boolean | body |
Either true
|
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/orgs/ORG/repos \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /orgs/{org}/repos', {
org: 'org',
name: 'name'
})
Default response
Status: 201 Created
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
}
Notes
Preview notice
The is_template
and template_repository
keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.baptiste-preview+json
Get a repository
When you pass the scarlet-witch-preview
media type, requests to get a repository will also return the repository's code of conduct if it can be detected from the repository's code of conduct file.
The parent
and source
objects are present when the repository is a fork. parent
is the repository this repository was forked from, source
is the ultimate source for the network.
get /repos/{owner}/{repo}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"pull": true,
"triage": true,
"push": false,
"maintain": false,
"admin": false
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"license": {
"key": "mit",
"name": "MIT License",
"spdx_id": "MIT",
"url": "https://api.github.com/licenses/mit",
"node_id": "MDc6TGljZW5zZW1pdA=="
},
"organization": {
"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": "Organization",
"site_admin": false
},
"parent": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
},
"source": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
},
"anonymous_access_enabled": false
}
Response with scarlet-witch-preview media type
Status: 200 OK
{
"id": 88760408,
"node_id": "MDEwOlJlcG9zaXRvcnk4ODc2MDQwOA==",
"name": "cosee",
"full_name": "LindseyB/cosee",
"owner": {
"login": "LindseyB",
"id": 33750,
"node_id": "MDQ6VXNlcjMzNzUw",
"avatar_url": "https://avatars2.githubusercontent.com/u/33750?v=3",
"gravatar_id": "",
"url": "https://api.github.com/users/LindseyB",
"html_url": "https://github.com/LindseyB",
"followers_url": "https://api.github.com/users/LindseyB/followers",
"following_url": "https://api.github.com/users/LindseyB/following{/other_user}",
"gists_url": "https://api.github.com/users/LindseyB/gists{/gist_id}",
"starred_url": "https://api.github.com/users/LindseyB/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/LindseyB/subscriptions",
"organizations_url": "https://api.github.com/users/LindseyB/orgs",
"repos_url": "https://api.github.com/users/LindseyB/repos",
"events_url": "https://api.github.com/users/LindseyB/events{/privacy}",
"received_events_url": "https=>//api.github.com/users/LindseyB/received_events",
"type": "User",
"site_admin": true
},
"private": false,
"html_url": "https://github.com/LindseyB/cosee",
"description": null,
"fork": false,
"url": "https://api.github.com/repos/LindseyB/cosee",
"forks_url": "https://api.github.com/repos/LindseyB/cosee/forks",
"keys_url": "https://api.github.com/repos/LindseyB/cosee/keys{/key_id}",
"collaborators_url": "https://api.github.com/repos/LindseyB/cosee/collaborators{/collaborator}",
"teams_url": "https://api.github.com/repos/LindseyB/cosee/teams",
"hooks_url": "https://api.github.com/repos/LindseyB/cosee/hooks",
"issue_events_url": "https://api.github.com/repos/LindseyB/cosee/issues/events{/number}",
"events_url": "https://api.github.com/repos/LindseyB/cosee/events",
"assignees_url": "https://api.github.com/repos/LindseyB/cosee/assignees{/user}",
"branches_url": "https://api.github.com/repos/LindseyB/cosee/branches{/branch}",
"tags_url": "https://api.github.com/repos/LindseyB/cosee/tags",
"blobs_url": "https://api.github.com/repos/LindseyB/cosee/git/blobs{/sha}",
"git_tags_url": "https://api.github.com/repos/LindseyB/cosee/git/tags{/sha}",
"git_refs_url": "https://api.github.com/repos/LindseyB/cosee/git/refs{/sha}",
"trees_url": "https://api.github.com/repos/LindseyB/cosee/git/trees{/sha}",
"statuses_url": "https://api.github.com/repos/LindseyB/cosee/statuses/{sha}",
"languages_url": "https://api.github.com/repos/LindseyB/cosee/languages",
"stargazers_url": "https://api.github.com/repos/LindseyB/cosee/stargazers",
"contributors_url": "https://api.github.com/repos/LindseyB/cosee/contributors",
"subscribers_url": "https://api.github.com/repos/LindseyB/cosee/subscribers",
"subscription_url": "https://api.github.com/repos/LindseyB/cosee/subscription",
"commits_url": "https://api.github.com/repos/LindseyB/cosee/commits{/sha}",
"git_commits_url": "https://api.github.com/repos/LindseyB/cosee/git/commits{/sha}",
"comments_url": "https://api.github.com/repos/LindseyB/cosee/comments{/number}",
"issue_comment_url": "https://api.github.com/repos/LindseyB/cosee/issues/comments{/number}",
"contents_url": "https://api.github.com/repos/LindseyB/cosee/contents/{+path}",
"compare_url": "https://api.github.com/repos/LindseyB/cosee/compare/{base}...{head}",
"merges_url": "https://api.github.com/repos/LindseyB/cosee/merges",
"archive_url": "https://api.github.com/repos/LindseyB/cosee/{archive_format}{/ref}",
"downloads_url": "https://api.github.com/repos/LindseyB/cosee/downloads",
"issues_url": "https://api.github.com/repos/LindseyB/cosee/issues{/number}",
"pulls_url": "https://api.github.com/repos/LindseyB/cosee/pulls{/number}",
"milestones_url": "https://api.github.com/repos/LindseyB/cosee/milestones{/number}",
"notifications_url": "https://api.github.com/repos/LindseyB/cosee/notifications{?since,all,participating}",
"labels_url": "https://api.github.com/repos/LindseyB/cosee/labels{/name}",
"releases_url": "https://api.github.com/repos/LindseyB/cosee/releases{/id}",
"deployments_url": "https://api.github.com/repos/LindseyB/cosee/deployments",
"created_at": "2017-04-19T15=>23=>26Z",
"updated_at": "2017-04-19T15=>23=>26Z",
"pushed_at": "2017-04-19T15=>34=>03Z",
"git_url": "git://github.com/LindseyB/cosee.git",
"ssh_url": "git@github.com=>LindseyB/cosee.git",
"clone_url": "https://github.com/LindseyB/cosee.git",
"svn_url": "https://github.com/LindseyB/cosee",
"homepage": null,
"size": 1,
"stargazers_count": 0,
"watchers_count": 0,
"language": null,
"has_issues": true,
"has_projects": true,
"has_downloads": true,
"has_wiki": true,
"has_pages": false,
"forks_count": 0,
"mirror_url": null,
"open_issues_count": 0,
"default_branch": "master",
"code_of_conduct": {
"key": "contributor_covenant",
"name": "Contributor Covenant",
"url": "https://github.com/LindseyB/cosee/blob/master/CODE_OF_CONDUCT.md"
},
"network_count": 0,
"subscribers_count": 0
}
Notes
Preview notice
The Codes of Conduct API is currently available for developers to preview.
To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.scarlet-witch-preview+json
Update a repository
Note: To edit a repository's topics, use the Replace all repository topics endpoint.
patch /repos/{owner}/{repo}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notices. |
owner |
string | path | |
repo |
string | path | |
name |
string | body |
The name of the repository. |
description |
string | body |
A short description of the repository. |
homepage |
string | body |
A URL with more information about the repository. |
private |
boolean | body |
Either |
has_issues |
boolean | body |
Either true
|
has_projects |
boolean | body |
Either true
|
has_wiki |
boolean | body |
Either true
|
is_template |
boolean | body |
Either |
default_branch |
string | body |
Updates the default branch for this repository. |
allow_squash_merge |
boolean | body |
Either true
|
allow_merge_commit |
boolean | body |
Either true
|
allow_rebase_merge |
boolean | body |
Either true
|
archived |
boolean | body |
|
anonymous_access_enabled |
boolean | body |
Either |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.x-ray-preview+json" \
https://{hostname}/repos/octocat/hello-world \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}', {
owner: 'octocat',
repo: 'hello-world',
name: 'name',
mediaType: {
previews: [
'x-ray'
]
}
})
Default response
Status: 200 OK
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"pull": true,
"triage": true,
"push": false,
"maintain": false,
"admin": false
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"organization": {
"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": "Organization",
"site_admin": false
},
"parent": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
},
"source": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
},
"anonymous_access_enabled": false
}
Notes
Preview notices
When a GitHub Enterprise instance is in private mode, site and repository administrators can enable anonymous Git access for a public repository. This feature is currently available for developers to preview. 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.x-ray-preview+json
☝️ This header is required.
The is_template
and template_repository
keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.baptiste-preview+json
Delete a repository
Deleting a repository requires admin access. If OAuth is used, the delete_repo
scope is required.
If an organization owner or site admin has configured the organization to prevent members from deleting organization-owned repositories, you will get a 403 Forbidden
response.
delete /repos/{owner}/{repo}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}', {
owner: 'octocat',
repo: 'hello-world'
})
Default Response
Status: 204 No Content
{
"message": "Organization members cannot delete repositories.",
"documentation_url": "https://developer.github.com/enterprise/2.18/v3/repos/#delete-a-repository"
}
Notes
List repository contributors
Lists contributors to the specified repository and sorts them by the number of commits per contributor in descending order. This endpoint may return information that is a few hours old because the GitHub REST API v3 caches contributor data to improve performance.
GitHub identifies contributors by author email address. This endpoint groups contribution counts by GitHub user, which includes all associated email addresses. To improve performance, only the first 500 author email addresses in the repository link to GitHub users. The rest will appear as anonymous contributors without associated GitHub user information.
get /repos/{owner}/{repo}/contributors
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
anon |
string | query |
Set to |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/contributors
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/contributors', {
owner: 'octocat',
repo: 'hello-world'
})
Response if repository contains content
Status: 200 OK
[
{
"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,
"contributions": 32
}
]
Response if repository is empty
Status: 204 No Content
Notes
List repository languages
Lists languages for the specified repository. The value shown for each language is the number of bytes of code written in that language.
get /repos/{owner}/{repo}/languages
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/languages
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/languages', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
{
"C": 78769,
"Python": 7769
}
Notes
get /repos/{owner}/{repo}/tags
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/tags
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/tags', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"name": "v0.1",
"commit": {
"sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc",
"url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
},
"zipball_url": "https://github.com/octocat/Hello-World/zipball/v0.1",
"tarball_url": "https://github.com/octocat/Hello-World/tarball/v0.1"
}
]
Notes
get /repos/{owner}/{repo}/teams
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/teams
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/teams', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
Notes
get /repos/{owner}/{repo}/topics
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.mercy-preview+json" \
https://{hostname}/repos/octocat/hello-world/topics
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/topics', {
owner: 'octocat',
repo: 'hello-world',
mediaType: {
previews: [
'mercy'
]
}
})
Default response
Status: 200 OK
{
"names": [
"octocat",
"atom",
"electron",
"api"
]
}
Notes
Preview notice
The topics
property for repositories on GitHub Enterprise Server is currently available for developers to preview. To view the topics
property in calls that return repository results, you must provide a custom media type in the Accept
header:
application/vnd.github.mercy-preview+json
☝️ This header is required.
put /repos/{owner}/{repo}/topics
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
names |
array of strings | body |
Required. An array of topics to add to the repository. Pass one or more topics to replace the set of existing topics. Send an empty array ( |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.mercy-preview+json" \
https://{hostname}/repos/octocat/hello-world/topics \
-d '{"names":["names"]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/topics', {
owner: 'octocat',
repo: 'hello-world',
names: [
'names'
],
mediaType: {
previews: [
'mercy'
]
}
})
Default response
Status: 200 OK
{
"names": [
"octocat",
"atom",
"electron",
"api"
]
}
Notes
Preview notice
The topics
property for repositories on GitHub Enterprise Server is currently available for developers to preview. To view the topics
property in calls that return repository results, you must provide a custom media type in the Accept
header:
application/vnd.github.mercy-preview+json
☝️ This header is required.
Transfer a repository
A transfer request will need to be accepted by the new owner when transferring a personal repository to another user. The response will contain the original owner
, and the transfer will continue asynchronously. For more details on the requirements to transfer personal and organization-owned repositories, see about repository transfers.
post /repos/{owner}/{repo}/transfer
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
new_owner |
string | body |
Required: The username or organization name the repository will be transferred to. |
team_ids |
array of integers | body |
ID of the team or teams to add to the repository. Teams can only be added to organization-owned repositories. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.nightshade-preview+json" \
https://{hostname}/repos/octocat/hello-world/transfer \
-d '{"new_owner":"new_owner"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/transfer', {
owner: 'octocat',
repo: 'hello-world',
new_owner: 'new_owner',
mediaType: {
previews: [
'nightshade'
]
}
})
Default response
Status: 202 Accepted
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
}
Notes
Preview notice
The Repository Transfer API is currently available for developers to preview. To access the API, you must provide a custom media type in the Accept
header:
application/vnd.github.nightshade-preview+json
☝️ This header is required.
Enable vulnerability alerts
Enables dependency alerts and the dependency graph for a repository. The authenticated user must have admin access to the repository. For more information, see "About security alerts for vulnerable dependencies".
put /repos/{owner}/{repo}/vulnerability-alerts
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.dorian-preview+json" \
https://{hostname}/repos/octocat/hello-world/vulnerability-alerts
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/vulnerability-alerts', {
owner: 'octocat',
repo: 'hello-world',
mediaType: {
previews: [
'dorian'
]
}
})
Default Response
Status: 204 No Content
Notes
Preview notice
Enabling and disabling dependency alerts for a repository using the REST API is currently available for developers to preview. To access these new endpoints during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.dorian-preview+json
☝️ This header is required.
Disable vulnerability alerts
Disables dependency alerts and the dependency graph for a repository. The authenticated user must have admin access to the repository. For more information, see "About security alerts for vulnerable dependencies".
delete /repos/{owner}/{repo}/vulnerability-alerts
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.dorian-preview+json" \
https://{hostname}/repos/octocat/hello-world/vulnerability-alerts
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/vulnerability-alerts', {
owner: 'octocat',
repo: 'hello-world',
mediaType: {
previews: [
'dorian'
]
}
})
Default Response
Status: 204 No Content
Notes
Preview notice
Enabling and disabling dependency alerts for a repository using the REST API is currently available for developers to preview. To access these new endpoints during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.dorian-preview+json
☝️ This header is required.
Create a repository using a template
Creates a new repository using a repository template. Use the template_owner
and template_repo
route parameters to specify the repository to use as the template. The authenticated user must own or be a member of an organization that owns the repository. To check if a repository is available to use as a template, get the repository's information using the Get a repository endpoint and check that the is_template
key is true
.
OAuth scope requirements
When using OAuth, authorizations must include:
public_repo
scope orrepo
scope to create a public repositoryrepo
scope to create a private repository
post /repos/{template_owner}/{template_repo}/generate
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
template_owner |
string | path | |
template_repo |
string | path | |
owner |
string | body |
The organization or person who will own the new repository. To create a new repository in an organization, the authenticated user must be a member of the specified organization. |
name |
string | body |
Required. The name of the new repository. |
description |
string | body |
A short description of the new repository. |
private |
boolean | body |
Either |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.baptiste-preview+json" \
https://{hostname}/repos/TEMPLATE_OWNER/TEMPLATE_REPO/generate \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{template_owner}/{template_repo}/generate', {
template_owner: 'template_owner',
template_repo: 'template_repo',
name: 'name',
mediaType: {
previews: [
'baptiste'
]
}
})
Default response
Status: 201 Created
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": false,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
},
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
}
Preview notice
The is_template
and template_repository
keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.baptiste-preview+json
☝️ This header is required.
List public repositories
Lists all public repositories in the order that they were created.
Note: Pagination is powered exclusively by the since
parameter. Use the Link header to get the URL for the next page of repositories.
If you are an authenticated site administrator for your Enterprise appliance, you will be able to list all repositories including private repositories.
get /repositories
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
since |
integer | query |
The integer ID of the last repository that you've seen. |
visibility |
string | query |
To include private repositories as well set to |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repositories
JavaScript (@octokit/core.js)
await octokit.request('GET /repositories')
Default response
Status: 200 OK
[
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}"
}
]
Notes
List repositories for the authenticated user
Lists repositories that the authenticated user has explicit permission (:read
, :write
, or :admin
) to access.
The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.
get /user/repos
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
visibility |
string | query |
Can be one of |
affiliation |
string | query |
Comma-separated list of values. Can include: |
type |
string | query |
Can be one of Will cause a |
sort |
string | query |
Can be one of |
direction |
string | query |
Can be one of |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/repos
JavaScript (@octokit/core.js)
await octokit.request('GET /user/repos')
Response definition missing
Status: 418 I'm A Teapot
Create a repository for the authenticated user
Creates a new repository for the authenticated user.
OAuth scope requirements
When using OAuth, authorizations must include:
public_repo
scope orrepo
scope to create a public repositoryrepo
scope to create a private repository
post /user/repos
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
name |
string | body |
Required. The name of the repository. |
description |
string | body |
A short description of the repository. |
homepage |
string | body |
A URL with more information about the repository. |
private |
boolean | body |
Either |
has_issues |
boolean | body |
Either true
|
has_projects |
boolean | body |
Either true
|
has_wiki |
boolean | body |
Either true
|
is_template |
boolean | body |
Either |
team_id |
integer | body |
The id of the team that will be granted access to this repository. This is only valid when creating a repository in an organization. |
auto_init |
boolean | body |
Pass |
gitignore_template |
string | body |
Desired language or platform .gitignore template to apply. Use the name of the template without the extension. For example, "Haskell". |
license_template |
string | body |
Choose an open source license template that best suits your needs, and then use the license keyword as the |
allow_squash_merge |
boolean | body |
Either true
|
allow_merge_commit |
boolean | body |
Either true
|
allow_rebase_merge |
boolean | body |
Either true
|
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/repos \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /user/repos', {
name: 'name'
})
Default response
Status: 201 Created
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
}
Preview notice
The is_template
and template_repository
keys are currently available for developer to preview. See Create a repository using a template to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.baptiste-preview+json
List repositories for a user
Lists public repositories for the specified user.
get /users/{username}/repos
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path | |
type |
string | query |
Can be one of |
sort |
string | query |
Can be one of |
direction |
string | query |
Can be one of |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/users/USERNAME/repos
JavaScript (@octokit/core.js)
await octokit.request('GET /users/{username}/repos', {
username: 'username'
})
Response definition missing
Status: 418 I'm A Teapot
Notes
Branches
get /repos/{owner}/{repo}/branches
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
protected |
boolean | query |
Setting to |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"name": "master",
"commit": {
"sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc",
"url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
},
"protected": true,
"protection": {
"enabled": true,
"required_status_checks": {
"enforcement_level": "non_admins",
"contexts": [
"ci-test",
"linter"
]
}
},
"protection_url": "https://api.github.com/repos/octocat/hello-world/branches/master/protection"
}
]
Notes
get /repos/{owner}/{repo}/branches/{branch}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default response
Status: 200 OK
{
"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
}
},
"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": {
"enabled": true,
"required_status_checks": {
"enforcement_level": "non_admins",
"contexts": [
"ci-test",
"linter"
]
}
},
"protection_url": "https://api.github.com/repos/octocat/hello-world/branches/master/protection"
}
Notes
Get branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
get /repos/{owner}/{repo}/branches/{branch}/protection
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.luke-cage-preview+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default 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"
},
"enforce_admins": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/enforce_admins",
"enabled": true
},
"required_pull_request_reviews": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_pull_request_reviews",
"dismissal_restrictions": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions",
"users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/users",
"teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/teams",
"users": [
{
"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
}
],
"teams": [
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
},
"dismiss_stale_reviews": true,
"require_code_owner_reviews": true,
"required_approving_review_count": 2
},
"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,
"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
}
],
"teams": [
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
}
]
}
Notes
Preview notice
The Protected Branches API now has a setting for requiring a specified number of approving pull request reviews before merging. This feature is currently available for developers to preview. 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.luke-cage-preview+json
Update branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Protecting a branch requires admin or owner permissions to the repository.
Note: Passing new arrays of users
and teams
replaces their previous values.
Note: The list of users and teams in total is limited to 100 items.
put /repos/{owner}/{repo}/branches/{branch}/protection
Parameters
Name | Type | In | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
||||||||||||
owner |
string | path | |||||||||||||
repo |
string | path | |||||||||||||
branch |
string | path | |||||||||||||
required_status_checks |
object or null | body |
Required. Require status checks to pass before merging. Set to |
||||||||||||
required_status_checks object |
strict (boolean) |
Required. Require branches to be up to date before merging. |
contexts (array of strings) |
Required. The list of status checks to require in order to merge into this branch |
enforce_admins
Required. Enforce all configured restrictions for administrators. Set to true
to enforce required status checks for repository administrators. Set to null
to disable.
required_pull_request_reviews
Required. Require at least one approving review on a pull request, before merging. Set to null
to disable.
Properties of the required_pull_request_reviews
object
required_pull_request_reviews
objectdismissal_restrictions (object) |
Specify which users and teams can dismiss pull request reviews. Pass an empty |
dismiss_stale_reviews (boolean) |
Set to |
require_code_owner_reviews (boolean) |
Blocks merging pull requests until code owners review them. |
required_approving_review_count (integer) |
Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6. |
Properties of the dismissal_restrictions
object
dismissal_restrictions
objectusers (array of strings) |
The list of user |
teams (array of strings) |
The list of team |
restrictions
Required. Restrict who can push to the protected branch. User and team restrictions
are only available for organization-owned repositories. Set to null
to disable.
Properties of the restrictions
object
restrictions
objectusers (array of strings) |
Required. The list of user |
teams (array of strings) |
Required. The list of team |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.luke-cage-preview+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection \
-d '{"required_status_checks":{"strict":true,"contexts":["contexts"]},"enforce_admins":true,"required_pull_request_reviews":{"dismissal_restrictions":{"users":["users"],"teams":["teams"]},"dismiss_stale_reviews":true,"require_code_owner_reviews":true,"required_approving_review_count":42},"restrictions":{"users":["users"],"teams":["teams"]}}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
required_status_checks: {
strict: true,
contexts: [
'contexts'
]
},
enforce_admins: true,
required_pull_request_reviews: {
dismissal_restrictions: {
users: [
'users'
],
teams: [
'teams'
]
},
dismiss_stale_reviews: true,
require_code_owner_reviews: true,
required_approving_review_count: 42
},
restrictions: {
users: [
'users'
],
teams: [
'teams'
]
}
})
Default 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"
},
"enforce_admins": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/enforce_admins",
"enabled": true
},
"required_pull_request_reviews": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_pull_request_reviews",
"dismissal_restrictions": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions",
"users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/users",
"teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/teams",
"users": [
{
"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
}
],
"teams": [
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
},
"dismiss_stale_reviews": true,
"require_code_owner_reviews": true,
"required_approving_review_count": 2
},
"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,
"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
}
],
"teams": [
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
}
]
}
Notes
Preview notice
The Protected Branches API now has a setting for requiring a specified number of approving pull request reviews before merging. This feature is currently available for developers to preview. 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.luke-cage-preview+json
Delete branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
delete /repos/{owner}/{repo}/branches/{branch}/protection
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default Response
Status: 204 No Content
Notes
Get admin branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
get /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/enforce_admins
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/enforce_admins",
"enabled": true
}
Notes
Set admin branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Adding admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
post /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/enforce_admins
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/enforce_admins",
"enabled": true
}
Notes
Delete admin branch protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Removing admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
delete /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/enforce_admins
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Response definition missing
Status: 418 I'm A Teapot
Notes
Get pull request review protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
get /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.luke-cage-preview+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_pull_request_reviews
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_pull_request_reviews",
"dismissal_restrictions": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions",
"users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/users",
"teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/teams",
"users": [
{
"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
}
],
"teams": [
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
},
"dismiss_stale_reviews": true,
"require_code_owner_reviews": true,
"required_approving_review_count": 2
}
Notes
Preview notice
The Protected Branches API now has a setting for requiring a specified number of approving pull request reviews before merging. This feature is currently available for developers to preview. 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.luke-cage-preview+json
Update pull request review protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Updating pull request review enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
Note: Passing new arrays of users
and teams
replaces their previous values.
patch /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews
Parameters
Name | Type | In | Description | ||||
---|---|---|---|---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
||||
owner |
string | path | |||||
repo |
string | path | |||||
branch |
string | path | |||||
dismissal_restrictions |
object | body |
Specify which users and teams can dismiss pull request reviews. Pass an empty |
||||
dismissal_restrictions object |
users (array of strings) |
The list of user |
teams (array of strings) |
The list of team |
dismiss_stale_reviews
Set to true
if you want to automatically dismiss approving reviews when someone pushes a new commit.
require_code_owner_reviews
Blocks merging pull requests until code owners have reviewed.
required_approving_review_count
Specifies the number of reviewers required to approve pull requests. Use a number between 1 and 6.
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.luke-cage-preview+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_pull_request_reviews \
-d '{"dismissal_restrictions":{"users":["users"],"teams":["teams"]}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
dismissal_restrictions: {
users: [
'users'
],
teams: [
'teams'
]
}
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_pull_request_reviews",
"dismissal_restrictions": {
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions",
"users_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/users",
"teams_url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/teams",
"users": [
{
"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
}
],
"teams": [
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
},
"dismiss_stale_reviews": true,
"require_code_owner_reviews": true,
"required_approving_review_count": 2
}
Notes
Preview notice
The Protected Branches API now has a setting for requiring a specified number of approving pull request reviews before merging. This feature is currently available for developers to preview. 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.luke-cage-preview+json
Delete pull request review protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
delete /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_pull_request_reviews
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Response definition missing
Status: 418 I'm A Teapot
Notes
Get commit signature protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
When authenticated with admin or owner permissions to the repository, you can use this endpoint to check whether a branch requires signed commits. An enabled status of true
indicates you must sign commits on this branch. For more information, see Signing commits with GPG in GitHub Help.
Note: You must enable branch protection to require signed commits.
get /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.zzzax-preview+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_signatures
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
mediaType: {
previews: [
'zzzax'
]
}
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_signatures",
"enabled": true
}
Notes
Preview notice
Protected Branches API can now manage a setting for requiring signed commits. This feature is currently available for developers to preview. 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.zzzax-preview+json
☝️ This header is required.
Create commit signature protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
When authenticated with admin or owner permissions to the repository, you can use this endpoint to require signed commits on a branch. You must enable branch protection to require signed commits.
post /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.zzzax-preview+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_signatures
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
mediaType: {
previews: [
'zzzax'
]
}
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_signatures",
"enabled": true
}
Notes
Preview notice
Protected Branches API can now manage a setting for requiring signed commits. This feature is currently available for developers to preview. 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.zzzax-preview+json
☝️ This header is required.
Delete commit signature protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
When authenticated with admin or owner permissions to the repository, you can use this endpoint to disable required signed commits on a branch. You must enable branch protection to require signed commits.
delete /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.zzzax-preview+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_signatures
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
mediaType: {
previews: [
'zzzax'
]
}
})
Response definition missing
Status: 418 I'm A Teapot
Notes
Preview notice
Protected Branches API can now manage a setting for requiring signed commits. This feature is currently available for developers to preview. 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.zzzax-preview+json
☝️ This header is required.
Get status checks protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
get /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default 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"
}
Notes
Update status check potection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Updating required status checks requires admin or owner permissions to the repository and branch protection to be enabled.
patch /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path | |
strict |
boolean | body |
Require branches to be up to date before merging. |
contexts |
array of strings | body |
The list of status checks to require in order to merge into this branch |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks \
-d '{"strict":true}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
strict: true
})
Default 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"
}
Notes
Remove status check protection
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
delete /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Response definition missing
Status: 418 I'm A Teapot
Notes
Get all status check contexts
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
get /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks/contexts
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Response
Status: 200 OK
[
"continuous-integration/travis-ci"
]
Notes
Add status check contexts
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
post /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks/contexts \
-d '{"contexts":["contexts"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
contexts: [
'contexts'
]
})
Response
Status: 200 OK
[
"continuous-integration/travis-ci",
"continuous-integration/jenkins"
]
Notes
Set status check contexts
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
put /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks/contexts \
-d '{"contexts":["contexts"]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
contexts: [
'contexts'
]
})
Response
Status: 200 OK
[
"continuous-integration/travis-ci"
]
Notes
Remove status check contexts
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
delete /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/required_status_checks/contexts \
-d '{"contexts":["contexts"]}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
contexts: [
'contexts'
]
})
Response
Status: 200 OK
[
"continuous-integration/travis-ci"
]
Notes
Get access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Lists who has access to this protected branch.
Note: Users and teams restrictions
are only available for organization-owned repositories.
get /repos/{owner}/{repo}/branches/{branch}/protection/restrictions
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default response
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,
"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
}
],
"teams": [
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
}
Notes
Delete access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Disables the ability to restrict who can push to this branch.
delete /repos/{owner}/{repo}/branches/{branch}/protection/restrictions
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Response definition missing
Status: 418 I'm A Teapot
Notes
Get teams with access to the protected branch
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Lists the teams who have push access to this branch. If you pass the hellcat-preview
media type, the list includes child teams.
get /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/teams
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default response
Status: 200 OK
[
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
Notes
Preview notice
The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept
header:
application/vnd.github.hellcat-preview+json
Add team access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Grants the specified teams push access for this branch. If you pass the hellcat-preview
media type, you can also give push access to child teams.
Type | Description |
---|---|
array | The teams that can have push access. Use the team's slug . Note: The list of users and teams in total is limited to 100 items. |
post /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/teams \
-d '{"teams":["teams"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
teams: [
'teams'
]
})
Default response
Status: 200 OK
[
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
Notes
Preview notice
The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept
header:
application/vnd.github.hellcat-preview+json
Set team access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Replaces the list of teams that have push access to this branch. This removes all teams that previously had push access and grants push access to the new list of teams. If you pass the hellcat-preview
media type, team restrictions include child teams.
Type | Description |
---|---|
array | The teams that can have push access. Use the team's slug . Note: The list of users and teams in total is limited to 100 items. |
put /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/teams \
-d '{"teams":["teams"]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
teams: [
'teams'
]
})
Default response
Status: 200 OK
[
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
Notes
Preview notice
The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept
header:
application/vnd.github.hellcat-preview+json
Remove team access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Removes the ability of a team to push to this branch. If you pass the hellcat-preview
media type, you can also remove push access for child teams.
Type | Description |
---|---|
array | Teams that should no longer have push access. Use the team's slug . Note: The list of users and teams in total is limited to 100 items. |
delete /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/teams \
-d '{"teams":["teams"]}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
teams: [
'teams'
]
})
Default response
Status: 200 OK
[
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
]
Notes
Preview notice
The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept
header:
application/vnd.github.hellcat-preview+json
Get users with access to the protected branch
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Lists the people who have push access to this branch.
get /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/users
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch'
})
Default response
Status: 200 OK
[
{
"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
}
]
Notes
Add user access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Grants the specified people push access for this branch.
Type | Description |
---|---|
array | Usernames for people who can have push access. Note: The list of users and teams in total is limited to 100 items. |
post /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/users \
-d '{"users":["users"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
users: [
'users'
]
})
Default response
Status: 200 OK
[
{
"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
}
]
Notes
Set user access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Replaces the list of people that have push access to this branch. This removes all people that previously had push access and grants push access to the new list of people.
Type | Description |
---|---|
array | Usernames for people who can have push access. Note: The list of users and teams in total is limited to 100 items. |
put /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/users \
-d '{"users":["users"]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
users: [
'users'
]
})
Default response
Status: 200 OK
[
{
"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
}
]
Notes
Remove user access restrictions
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Removes the ability of a user to push to this branch.
Type | Description |
---|---|
array | Usernames of the people who should no longer have push access. Note: The list of users and teams in total is limited to 100 items. |
delete /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
branch |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/branches/BRANCH/protection/restrictions/users \
-d '{"users":["users"]}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users', {
owner: 'octocat',
repo: 'hello-world',
branch: 'branch',
users: [
'users'
]
})
Default response
Status: 200 OK
[
{
"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
}
]
Notes
Collaborators
List repository collaborators
For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners.
If you pass the hellcat-preview
media type, team members will include the members of child teams.
get /repos/{owner}/{repo}/collaborators
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
affiliation |
string | query |
Filter collaborators returned by their affiliation. Can be one of: |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/collaborators
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/collaborators', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"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,
"permissions": {
"pull": true,
"push": true,
"admin": false
}
}
]
Notes
Preview notice
The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept
header:
application/vnd.github.hellcat-preview+json
Check if a user is a repository collaborator
For organization-owned repositories, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners.
If you pass the hellcat-preview
media type, team members will include the members of child teams.
get /repos/{owner}/{repo}/collaborators/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
username |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/collaborators/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/collaborators/{username}', {
owner: 'octocat',
repo: 'hello-world',
username: 'username'
})
Response if user is a collaborator
Status: 204 No Content
Response if user is not a collaborator
Status: 404 Not Found
Notes
Preview notice
The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept
header:
application/vnd.github.hellcat-preview+json
Add a repository collaborator
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" for details.
For more information the permission levels, see "Repository permission levels for an organization".
Note that, if you choose not to pass any parameters, you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP verbs."
put /repos/{owner}/{repo}/collaborators/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
username |
string | path | |
permission |
string | body |
The permission to grant the collaborator. Only valid on organization-owned repositories. Can be one of: push
|
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/collaborators/USERNAME \
-d '{"permission":"permission"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/collaborators/{username}', {
owner: 'octocat',
repo: 'hello-world',
username: 'username',
permission: 'permission'
})
Default Response
Status: 204 No Content
Notes
delete /repos/{owner}/{repo}/collaborators/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
username |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/collaborators/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/collaborators/{username}', {
owner: 'octocat',
repo: 'hello-world',
username: 'username'
})
Default Response
Status: 204 No Content
Notes
Get repository permissions for a user
Checks the repository permission of a collaborator. The possible repository permissions are admin
, write
, read
, and none
.
get /repos/{owner}/{repo}/collaborators/{username}/permission
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
username |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/collaborators/USERNAME/permission
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/collaborators/{username}/permission', {
owner: 'octocat',
repo: 'hello-world',
username: 'username'
})
Response if user has admin permissions
Status: 200 OK
{
"permission": "admin",
"user": {
"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
}
}
Notes
Comments
Custom media types for commit comments
These are the supported media types for commit comments. You can read more about the use of media types in the API here.
application/vnd.github-commitcomment.raw+json
application/vnd.github-commitcomment.text+json
application/vnd.github-commitcomment.html+json
application/vnd.github-commitcomment.full+json
For more information, see "Custom media types."
List commit comments for a repository
Commit Comments use these custom media types. You can read more about the use of media types in the API here.
Comments are ordered by ascending ID.
get /repos/{owner}/{repo}/comments
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/comments
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/comments', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
"url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
"id": 1,
"node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
"body": "Great stuff",
"path": "file1.txt",
"position": 4,
"line": 14,
"commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"user": {
"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
},
"created_at": "2011-04-14T16:00:49Z",
"updated_at": "2011-04-14T16:00:49Z"
}
]
Notes
get /repos/{owner}/{repo}/comments/{comment_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
comment_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/comments/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/comments/{comment_id}', {
owner: 'octocat',
repo: 'hello-world',
comment_id: 42
})
Default response
Status: 200 OK
{
"html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
"url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
"id": 1,
"node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
"body": "Great stuff",
"path": "file1.txt",
"position": 4,
"line": 14,
"commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"user": {
"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
},
"created_at": "2011-04-14T16:00:49Z",
"updated_at": "2011-04-14T16:00:49Z"
}
Notes
patch /repos/{owner}/{repo}/comments/{comment_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
comment_id |
integer | path | |
body |
string | body |
Required. The contents of the comment |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/comments/42 \
-d '{"body":"body"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/comments/{comment_id}', {
owner: 'octocat',
repo: 'hello-world',
comment_id: 42,
body: 'body'
})
Default response
Status: 200 OK
{
"html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
"url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
"id": 1,
"node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
"body": "Nice change",
"path": "file1.txt",
"position": 4,
"line": 14,
"commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"user": {
"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
},
"created_at": "2011-04-14T16:00:49Z",
"updated_at": "2011-04-14T16:00:49Z"
}
Notes
delete /repos/{owner}/{repo}/comments/{comment_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
comment_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/comments/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/comments/{comment_id}', {
owner: 'octocat',
repo: 'hello-world',
comment_id: 42
})
Default Response
Status: 204 No Content
Notes
List commit comments
Use the :commit_sha
to specify the commit that will have its comments listed.
get /repos/{owner}/{repo}/commits/{commit_sha}/comments
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
commit_sha |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/commits/COMMIT_SHA/comments
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/commits/{commit_sha}/comments', {
owner: 'octocat',
repo: 'hello-world',
commit_sha: 'commit_sha'
})
Default response
Status: 200 OK
[
{
"html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
"url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
"id": 1,
"node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
"body": "Great stuff",
"path": "file1.txt",
"position": 4,
"line": 14,
"commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"user": {
"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
},
"created_at": "2011-04-14T16:00:49Z",
"updated_at": "2011-04-14T16:00:49Z"
}
]
Notes
Create a commit comment
Create a comment for a commit using its :commit_sha
.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" for details.
post /repos/{owner}/{repo}/commits/{commit_sha}/comments
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
commit_sha |
string | path | |
body |
string | body |
Required. The contents of the comment. |
path |
string | body |
Relative path of the file to comment on. |
position |
integer | body |
Line index in the diff to comment on. |
line |
integer or null | body |
Deprecated. Use position parameter instead. Line number in the file to comment on. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/commits/COMMIT_SHA/comments \
-d '{"body":"body"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/commits/{commit_sha}/comments', {
owner: 'octocat',
repo: 'hello-world',
commit_sha: 'commit_sha',
body: 'body'
})
Default response
Status: 201 Created
{
"html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e#commitcomment-1",
"url": "https://api.github.com/repos/octocat/Hello-World/comments/1",
"id": 1,
"node_id": "MDEzOkNvbW1pdENvbW1lbnQx",
"body": "Great stuff",
"path": "file1.txt",
"position": 4,
"line": 14,
"commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"user": {
"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
},
"created_at": "2011-04-14T16:00:49Z",
"updated_at": "2011-04-14T16:00:49Z"
}
Notes
Commits
The Repo Commits API supports listing, viewing, and comparing commits in a repository.
List commits
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on her/his account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
get /repos/{owner}/{repo}/commits
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
sha |
string | query |
SHA or branch to start listing commits from. Default: the repository’s default branch (usually |
path |
string | query |
Only commits containing this file path will be returned. |
author |
string | query |
GitHub login or email address by which to filter by commit author. |
since |
string | query |
Only commits after this date will be returned. This is a timestamp in ISO 8601 format: |
until |
string | query |
Only commits before this date will be returned. This is a timestamp in ISO 8601 format: |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/commits
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/commits', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"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": "support@github.com",
"date": "2011-04-14T16:00:49Z"
},
"committer": {
"name": "Monalisa Octocat",
"email": "support@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"
}
]
}
]
Notes
List branches for HEAD commit
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.
Returns all branches where the given commit SHA is the HEAD, or latest commit for the branch.
get /repos/{owner}/{repo}/commits/{commit_sha}/branches-where-head
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
commit_sha |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.groot-preview+json" \
https://{hostname}/repos/octocat/hello-world/commits/COMMIT_SHA/branches-where-head
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/commits/{commit_sha}/branches-where-head', {
owner: 'octocat',
repo: 'hello-world',
commit_sha: 'commit_sha',
mediaType: {
previews: [
'groot'
]
}
})
Default response
Status: 200 OK
[
{
"name": "branch_5",
"commit": {
"sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc",
"url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
},
"protected": false
}
]
Notes
Preview notice
Listing branches or pull requests for a commit in the Commits API is currently available for developers to preview. See the blog post for more details. To access the new endpoints during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.groot-preview+json
☝️ This header is required.
List pull requests associated with a commit
Lists all pull requests containing the provided commit SHA, which can be from any point in the commit history. The results will include open and closed pull requests. Additional preview headers may be required to see certain details for associated pull requests, such as whether a pull request is in a draft state. For more information about previews that might affect this endpoint, see the List pull requests endpoint.
get /repos/{owner}/{repo}/commits/{commit_sha}/pulls
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path | |
commit_sha |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.groot-preview+json" \
https://{hostname}/repos/octocat/hello-world/commits/COMMIT_SHA/pulls
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/commits/{commit_sha}/pulls', {
owner: 'octocat',
repo: 'hello-world',
commit_sha: 'commit_sha',
mediaType: {
previews: [
'groot'
]
}
})
Default response
Status: 200 OK
[
{
"url": "https://api.github.com/repos/octocat/Hello-World/pulls/1347",
"id": 1,
"node_id": "MDExOlB1bGxSZXF1ZXN0MQ==",
"html_url": "https://github.com/octocat/Hello-World/pull/1347",
"diff_url": "https://github.com/octocat/Hello-World/pull/1347.diff",
"patch_url": "https://github.com/octocat/Hello-World/pull/1347.patch",
"issue_url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
"commits_url": "https://api.github.com/repos/octocat/Hello-World/pulls/1347/commits",
"review_comments_url": "https://api.github.com/repos/octocat/Hello-World/pulls/1347/comments",
"review_comment_url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments{/number}",
"comments_url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/comments",
"statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
"number": 1347,
"state": "open",
"locked": true,
"title": "Amazing new feature",
"user": {
"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
},
"body": "Please pull these awesome changes in!",
"labels": [
{
"id": 208045946,
"node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
"url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
"name": "bug",
"description": "Something isn't working",
"color": "f29513",
"default": true
}
],
"milestone": {
"url": "https://api.github.com/repos/octocat/Hello-World/milestones/1",
"html_url": "https://github.com/octocat/Hello-World/milestones/v1.0",
"labels_url": "https://api.github.com/repos/octocat/Hello-World/milestones/1/labels",
"id": 1002604,
"node_id": "MDk6TWlsZXN0b25lMTAwMjYwNA==",
"number": 1,
"state": "open",
"title": "v1.0",
"description": "Tracking milestone for version 1.0",
"creator": {
"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
},
"open_issues": 4,
"closed_issues": 8,
"created_at": "2011-04-10T20:09:31Z",
"updated_at": "2014-03-03T18:58:10Z",
"closed_at": "2013-02-12T13:22:01Z",
"due_on": "2012-10-09T23:39:01Z"
},
"active_lock_reason": "too heated",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:01:12Z",
"closed_at": "2011-01-26T19:01:12Z",
"merged_at": "2011-01-26T19:01:12Z",
"merge_commit_sha": "e5bd3914e2e596debea16f433f57875b5b90bcd6",
"assignee": {
"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
},
"assignees": [
{
"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
},
{
"login": "hubot",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/hubot_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/hubot",
"html_url": "https://github.com/hubot",
"followers_url": "https://api.github.com/users/hubot/followers",
"following_url": "https://api.github.com/users/hubot/following{/other_user}",
"gists_url": "https://api.github.com/users/hubot/gists{/gist_id}",
"starred_url": "https://api.github.com/users/hubot/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/hubot/subscriptions",
"organizations_url": "https://api.github.com/users/hubot/orgs",
"repos_url": "https://api.github.com/users/hubot/repos",
"events_url": "https://api.github.com/users/hubot/events{/privacy}",
"received_events_url": "https://api.github.com/users/hubot/received_events",
"type": "User",
"site_admin": true
}
],
"requested_reviewers": [
{
"login": "other_user",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/other_user_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/other_user",
"html_url": "https://github.com/other_user",
"followers_url": "https://api.github.com/users/other_user/followers",
"following_url": "https://api.github.com/users/other_user/following{/other_user}",
"gists_url": "https://api.github.com/users/other_user/gists{/gist_id}",
"starred_url": "https://api.github.com/users/other_user/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/other_user/subscriptions",
"organizations_url": "https://api.github.com/users/other_user/orgs",
"repos_url": "https://api.github.com/users/other_user/repos",
"events_url": "https://api.github.com/users/other_user/events{/privacy}",
"received_events_url": "https://api.github.com/users/other_user/received_events",
"type": "User",
"site_admin": false
}
],
"requested_teams": [
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://api.github.com/teams/justice-league",
"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",
"parent": null
}
],
"head": {
"label": "octocat:new-topic",
"ref": "new-topic",
"sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"user": {
"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
},
"repo": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
}
},
"base": {
"label": "octocat:master",
"ref": "master",
"sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"user": {
"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
},
"repo": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
}
},
"_links": {
"self": {
"href": "https://api.github.com/repos/octocat/Hello-World/pulls/1347"
},
"html": {
"href": "https://github.com/octocat/Hello-World/pull/1347"
},
"issue": {
"href": "https://api.github.com/repos/octocat/Hello-World/issues/1347"
},
"comments": {
"href": "https://api.github.com/repos/octocat/Hello-World/issues/1347/comments"
},
"review_comments": {
"href": "https://api.github.com/repos/octocat/Hello-World/pulls/1347/comments"
},
"review_comment": {
"href": "https://api.github.com/repos/octocat/Hello-World/pulls/comments{/number}"
},
"commits": {
"href": "https://api.github.com/repos/octocat/Hello-World/pulls/1347/commits"
},
"statuses": {
"href": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e"
}
},
"author_association": "OWNER",
"draft": false
}
]
Notes
Preview notice
Listing branches or pull requests for a commit in the Commits API is currently available for developers to preview. See the blog post for more details. To access the new endpoints during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.groot-preview+json
☝️ This header is required.
Get a commit
Returns the contents of a single commit reference. You must have read
access for the repository to use this endpoint.
You can pass the appropriate media type to fetch diff
and patch
formats. Diffs with binary data will have no patch
property.
To return only the SHA-1 hash of the commit reference, you can provide the sha
custom media type in the Accept
header. You can use this endpoint to check if a remote reference's SHA-1 hash is the same as your local reference's SHA-1 hash by providing the local SHA-1 reference as the ETag.
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on her/his account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
get /repos/{owner}/{repo}/commits/{ref}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
ref |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/commits/REF
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/commits/{ref}', {
owner: 'octocat',
repo: 'hello-world',
ref: 'ref'
})
Default response
Status: 200 OK
{
"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": "support@github.com",
"date": "2011-04-14T16:00:49Z"
},
"committer": {
"name": "Monalisa Octocat",
"email": "support@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....."
}
]
}
Notes
Compare two commits
Both :base
and :head
must be branch names in :repo
. To compare branches across other repositories in the same network as :repo
, use the format <USERNAME>:branch
.
The response from the API is equivalent to running the git log base..head
command; however, commits are returned in chronological order. Pass the appropriate media type to fetch diff and patch formats.
The response also includes details on the files that were changed between the two commits. This includes the status of the change (for example, if a file was added, removed, modified, or renamed), and details of the change itself. For example, files with a renamed
status have a previous_filename
field showing the previous filename of the file, and files with a modified
status have a patch
field showing the changes made to the file.
Working with large comparisons
The response will include a comparison of up to 250 commits. If you are working with a larger commit range, you can use the List commits to enumerate all commits in the range.
For comparisons with extremely large diffs, you may receive an error response indicating that the diff took too long to generate. You can typically resolve this error by using a smaller commit range.
Signature verification object
The response will include a verification
object that describes the result of verifying the commit's signature. The following fields are included in the verification
object:
These are the possible values for reason
in the verification
object:
Value | Description |
---|---|
expired_key | The key that made the signature is expired. |
not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error | There was an error communicating with the signature verification service. |
gpgverify_unavailable | The signature verification service is currently unavailable. |
unsigned | The object does not include a signature. |
unknown_signature_type | A non-PGP signature was found in the commit. |
no_user | No user was associated with the committer email address in the commit. |
unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on her/his account. |
bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key | The key that made the signature has not been registered with any user's account. |
malformed_signature | There was an error parsing the signature. |
invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid | None of the above errors applied, so the signature is considered to be verified. |
get /repos/{owner}/{repo}/compare/{base}...{head}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
base |
string | path | |
head |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/compare/BASE...HEAD
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/compare/{base}...{head}', {
owner: 'octocat',
repo: 'hello-world',
base: 'base',
head: 'head'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/compare/master...topic",
"html_url": "https://github.com/octocat/Hello-World/compare/master...topic",
"permalink_url": "https://github.com/octocat/Hello-World/compare/octocat:bbcd538c8e72b8c175046e27cc8f907076331401...octocat:0328041d1152db8ae77652d1618a02e57f745f17",
"diff_url": "https://github.com/octocat/Hello-World/compare/master...topic.diff",
"patch_url": "https://github.com/octocat/Hello-World/compare/master...topic.patch",
"base_commit": {
"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": "support@github.com",
"date": "2011-04-14T16:00:49Z"
},
"committer": {
"name": "Monalisa Octocat",
"email": "support@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"
}
]
},
"merge_base_commit": {
"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": "support@github.com",
"date": "2011-04-14T16:00:49Z"
},
"committer": {
"name": "Monalisa Octocat",
"email": "support@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"
}
]
},
"status": "behind",
"ahead_by": 1,
"behind_by": 2,
"total_commits": 1,
"commits": [
{
"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": "support@github.com",
"date": "2011-04-14T16:00:49Z"
},
"committer": {
"name": "Monalisa Octocat",
"email": "support@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"
}
]
}
],
"files": [
{
"sha": "bbcd538c8e72b8c175046e27cc8f907076331401",
"filename": "file1.txt",
"status": "added",
"additions": 103,
"deletions": 21,
"changes": 124,
"blob_url": "https://github.com/octocat/Hello-World/blob/6dcb09b5b57875f334f61aebed695e2e4193db5e/file1.txt",
"raw_url": "https://github.com/octocat/Hello-World/raw/6dcb09b5b57875f334f61aebed695e2e4193db5e/file1.txt",
"contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/file1.txt?ref=6dcb09b5b57875f334f61aebed695e2e4193db5e",
"patch": "@@ -132,7 +132,7 @@ module Test @@ -1000,7 +1000,7 @@ module Test"
}
]
}
Notes
Community
Contents
These API endpoints let you create, modify, and delete Base64 encoded content in a repository. To request the raw format or rendered HTML (when supported), use custom media types for repository contents.
Custom media types for repository contents
READMEs, files, and symlinks support the following custom media types:
application/vnd.github.VERSION.raw
application/vnd.github.VERSION.html
Use the .raw
media type to retrieve the contents of the file.
For markup files such as Markdown or AsciiDoc, you can retrieve the rendered HTML using the .html
media type. Markup languages are rendered to HTML using our open-source Markup library.
All objects support the following custom media type:
application/vnd.github.VERSION.object
Use the object
media type parameter to retrieve the contents in a consistent object format regardless of the content type. For example, instead of an array of objects
for a directory, the response will be an object with an entries
attribute containing the array of objects.
You can read more about the use of media types in the API here.
Get repository content
Gets the contents of a file or directory in a repository. Specify the file path or directory in :path
. If you omit
:path
, you will receive the contents of all files in the repository.
Files and symlinks support a custom media type for retrieving the raw content or rendered HTML (when supported). All content types support a custom media type to ensure the content is returned in a consistent object format.
Note:
- To get a repository's contents recursively, you can recursively get the tree.
- This API has an upper limit of 1,000 files for a directory. If you need to retrieve more files, use the Git Trees API.
- This API supports files up to 1 megabyte in size.
If the content is a directory
The response will be an array of objects, one object for each item in the directory. When listing the contents of a directory, submodules have their "type" specified as "file". Logically, the value should be "submodule". This behavior exists in API v3 for backwards compatibility purposes. In the next major version of the API, the type will be returned as "submodule".
If the content is a symlink
If the requested :path
points to a symlink, and the symlink's target is a normal file in the repository, then the
API responds with the content of the file (in the format shown in the example. Otherwise, the API responds with an object
describing the symlink itself.
If the content is a submodule
The submodule_git_url
identifies the location of the submodule repository, and the sha
identifies a specific
commit within the submodule repository. Git uses the given URL when cloning the submodule repository, and checks out
the submodule at that specific commit.
If the submodule repository is not hosted on github.com, the Git URLs (git_url
and _links["git"]
) and the
github.com URLs (html_url
and _links["html"]
) will have null values.
get /repos/{owner}/{repo}/contents/{path}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
path |
string | path | |
ref |
string | query |
The name of the commit/branch/tag. Default: the repository’s default branch (usually |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/contents/PATH
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/contents/{path}', {
owner: 'octocat',
repo: 'hello-world',
path: 'path'
})
Response if content is a file
Status: 200 OK
{
"type": "file",
"encoding": "base64",
"size": 5362,
"name": "README.md",
"path": "README.md",
"content": "encoded content ...",
"sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
"url": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
"git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
"html_url": "https://github.com/octokit/octokit.rb/blob/master/README.md",
"download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/README.md",
"_links": {
"git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
"self": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
"html": "https://github.com/octokit/octokit.rb/blob/master/README.md"
}
}
Response if content is a directory
Status: 200 OK
[
{
"type": "file",
"size": 625,
"name": "octokit.rb",
"path": "lib/octokit.rb",
"sha": "fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
"url": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit.rb",
"git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
"html_url": "https://github.com/octokit/octokit.rb/blob/master/lib/octokit.rb",
"download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/lib/octokit.rb",
"_links": {
"self": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit.rb",
"git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
"html": "https://github.com/octokit/octokit.rb/blob/master/lib/octokit.rb"
}
},
{
"type": "dir",
"size": 0,
"name": "octokit",
"path": "lib/octokit",
"sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
"url": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit",
"git_url": "https://api.github.com/repos/octokit/octokit.rb/git/trees/a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
"html_url": "https://github.com/octokit/octokit.rb/tree/master/lib/octokit",
"download_url": null,
"_links": {
"self": "https://api.github.com/repos/octokit/octokit.rb/contents/lib/octokit",
"git": "https://api.github.com/repos/octokit/octokit.rb/git/trees/a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
"html": "https://github.com/octokit/octokit.rb/tree/master/lib/octokit"
}
}
]
Response if content is a symlink
Status: 200 OK
{
"type": "symlink",
"target": "/path/to/symlink/target",
"size": 23,
"name": "some-symlink",
"path": "bin/some-symlink",
"sha": "452a98979c88e093d682cab404a3ec82babebb48",
"url": "https://api.github.com/repos/octokit/octokit.rb/contents/bin/some-symlink",
"git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/452a98979c88e093d682cab404a3ec82babebb48",
"html_url": "https://github.com/octokit/octokit.rb/blob/master/bin/some-symlink",
"download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/bin/some-symlink",
"_links": {
"git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/452a98979c88e093d682cab404a3ec82babebb48",
"self": "https://api.github.com/repos/octokit/octokit.rb/contents/bin/some-symlink",
"html": "https://github.com/octokit/octokit.rb/blob/master/bin/some-symlink"
}
}
Response if content is a submodule
Status: 200 OK
{
"type": "submodule",
"submodule_git_url": "git://github.com/jquery/qunit.git",
"size": 0,
"name": "qunit",
"path": "test/qunit",
"sha": "6ca3721222109997540bd6d9ccd396902e0ad2f9",
"url": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
"git_url": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
"html_url": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
"download_url": null,
"_links": {
"git": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
"self": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
"html": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
}
}
Notes
Create or update file contents
Creates a new file or replaces an existing file in a repository.
put /repos/{owner}/{repo}/contents/{path}
Parameters
Name | Type | In | Description | ||||
---|---|---|---|---|---|---|---|
accept |
string | header |
Setting to |
||||
owner |
string | path | |||||
repo |
string | path | |||||
path |
string | path | |||||
message |
string | body |
Required. The commit message. |
||||
content |
string | body |
Required. The new file content, using Base64 encoding. |
||||
sha |
string | body |
Required if you are updating a file. The blob SHA of the file being replaced. |
||||
branch |
string | body |
The branch name. Default: the repository’s default branch (usually |
||||
committer |
object | body |
The person that committed the file. Default: the authenticated user. |
||||
committer object |
name (string) |
Required. The name of the author or committer of the commit. You'll receive a |
email (string) |
Required. The email of the author or committer of the commit. You'll receive a |
author
The author of the file. Default: The committer
or the authenticated user if you omit committer
.
Properties of the author
object
author
objectname (string) |
Required. The name of the author or committer of the commit. You'll receive a |
email (string) |
Required. The email of the author or committer of the commit. You'll receive a |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/contents/PATH \
-d '{"message":"message","content":"content"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/contents/{path}', {
owner: 'octocat',
repo: 'hello-world',
path: 'path',
message: 'message',
content: 'content'
})
Example for updating a file
Status: 200 OK
{
"content": {
"name": "hello.txt",
"path": "notes/hello.txt",
"sha": "a56507ed892d05a37c6d6128c260937ea4d287bd",
"size": 9,
"url": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt",
"html_url": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt",
"git_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/a56507ed892d05a37c6d6128c260937ea4d287bd",
"download_url": "https://raw.githubusercontent.com/octocat/HelloWorld/master/notes/hello.txt",
"type": "file",
"_links": {
"self": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt",
"git": "https://api.github.com/repos/octocat/Hello-World/git/blobs/a56507ed892d05a37c6d6128c260937ea4d287bd",
"html": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt"
}
},
"commit": {
"sha": "18a43cd8e1e3a79c786e3d808a73d23b6d212b16",
"node_id": "MDY6Q29tbWl0MThhNDNjZDhlMWUzYTc5Yzc4NmUzZDgwOGE3M2QyM2I2ZDIxMmIxNg==",
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/18a43cd8e1e3a79c786e3d808a73d23b6d212b16",
"html_url": "https://github.com/octocat/Hello-World/git/commit/18a43cd8e1e3a79c786e3d808a73d23b6d212b16",
"author": {
"date": "2014-11-07T22:01:45Z",
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"committer": {
"date": "2014-11-07T22:01:45Z",
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"message": "my commit message",
"tree": {
"url": "https://api.github.com/repos/octocat/Hello-World/git/trees/9a21f8e2018f42ffcf369b24d2cd20bc25c9e66f",
"sha": "9a21f8e2018f42ffcf369b24d2cd20bc25c9e66f"
},
"parents": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/da5a433788da5c255edad7979b328b67d79f53f6",
"html_url": "https://github.com/octocat/Hello-World/git/commit/da5a433788da5c255edad7979b328b67d79f53f6",
"sha": "da5a433788da5c255edad7979b328b67d79f53f6"
}
],
"verification": {
"verified": false,
"reason": "unsigned",
"signature": null,
"payload": null
}
}
}
Example for creating a file
Status: 201 Created
{
"content": {
"name": "hello.txt",
"path": "notes/hello.txt",
"sha": "95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
"size": 9,
"url": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt",
"html_url": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt",
"git_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
"download_url": "https://raw.githubusercontent.com/octocat/HelloWorld/master/notes/hello.txt",
"type": "file",
"_links": {
"self": "https://api.github.com/repos/octocat/Hello-World/contents/notes/hello.txt",
"git": "https://api.github.com/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
"html": "https://github.com/octocat/Hello-World/blob/master/notes/hello.txt"
}
},
"commit": {
"sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
"node_id": "MDY6Q29tbWl0NzYzODQxN2RiNmQ1OWYzYzQzMWQzZTFmMjYxY2M2MzcxNTU2ODRjZA==",
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd",
"html_url": "https://github.com/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd",
"author": {
"date": "2014-11-07T22:01:45Z",
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"committer": {
"date": "2014-11-07T22:01:45Z",
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"message": "my commit message",
"tree": {
"url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
"sha": "691272480426f78a0138979dd3ce63b77f706feb"
},
"parents": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5",
"html_url": "https://github.com/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5",
"sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5"
}
],
"verification": {
"verified": false,
"reason": "unsigned",
"signature": null,
"payload": null
}
}
}
Notes
Delete a file
Deletes a file in a repository.
You can provide an additional committer
parameter, which is an object containing information about the committer. Or, you can provide an author
parameter, which is an object containing information about the author.
The author
section is optional and is filled in with the committer
information if omitted. If the committer
information is omitted, the authenticated user's information is used.
You must provide values for both name
and email
, whether you choose to use author
or committer
. Otherwise, you'll receive a 422
status code.
delete /repos/{owner}/{repo}/contents/{path}
Parameters
Name | Type | In | Description | ||||
---|---|---|---|---|---|---|---|
accept |
string | header |
Setting to |
||||
owner |
string | path | |||||
repo |
string | path | |||||
path |
string | path | |||||
message |
string | body |
Required. The commit message. |
||||
sha |
string | body |
Required. The blob SHA of the file being replaced. |
||||
branch |
string | body |
The branch name. Default: the repository’s default branch (usually |
||||
committer |
object | body |
object containing information about the committer. |
||||
committer object |
name (string) |
The name of the author (or committer) of the commit |
email (string) |
The email of the author (or committer) of the commit |
author
object containing information about the author.
Properties of the author
object
author
objectname (string) |
The name of the author (or committer) of the commit |
email (string) |
The email of the author (or committer) of the commit |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/contents/PATH \
-d '{"message":"message","sha":"sha"}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/contents/{path}', {
owner: 'octocat',
repo: 'hello-world',
path: 'path',
message: 'message',
sha: 'sha'
})
Default response
Status: 200 OK
{
"content": null,
"commit": {
"sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
"node_id": "MDY6Q29tbWl0NzYzODQxN2RiNmQ1OWYzYzQzMWQzZTFmMjYxY2M2MzcxNTU2ODRjZA==",
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd",
"html_url": "https://github.com/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd",
"author": {
"date": "2014-11-07T22:01:45Z",
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"committer": {
"date": "2014-11-07T22:01:45Z",
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"message": "my commit message",
"tree": {
"url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
"sha": "691272480426f78a0138979dd3ce63b77f706feb"
},
"parents": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5",
"html_url": "https://github.com/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5",
"sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5"
}
],
"verification": {
"verified": false,
"reason": "unsigned",
"signature": null,
"payload": null
}
}
}
Notes
Get a repository README
Gets the preferred README for a repository.
READMEs support custom media types for retrieving the raw content or rendered HTML.
get /repos/{owner}/{repo}/readme
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
ref |
string | query |
The name of the commit/branch/tag. Default: the repository’s default branch (usually |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/readme
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/readme', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
{
"type": "file",
"encoding": "base64",
"size": 5362,
"name": "README.md",
"path": "README.md",
"content": "encoded content ...",
"sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
"url": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
"git_url": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
"html_url": "https://github.com/octokit/octokit.rb/blob/master/README.md",
"download_url": "https://raw.githubusercontent.com/octokit/octokit.rb/master/README.md",
"_links": {
"git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
"self": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
"html": "https://github.com/octokit/octokit.rb/blob/master/README.md"
}
}
Notes
Download a repository archive
Gets a redirect URL to download an archive for a repository. The :archive_format
can be either tarball
or
zipball
. The :ref
must be a valid Git reference. If you omit :ref
, the repository’s default branch (usually
master
) will be used. Please make sure your HTTP framework is configured to follow redirects or you will need to use
the Location
header to make a second GET
request.
Note: For private repositories, these links are temporary and expire after five minutes.
get /repos/{owner}/{repo}/{archive_format}/{ref}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
archive_format |
string | path | |
ref |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/ARCHIVE_FORMAT/REF
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/{archive_format}/{ref}', {
owner: 'octocat',
repo: 'hello-world',
archive_format: 'archive_format',
ref: 'ref'
})
Response
Status: 302 Found
Notes
Deploy keys
You can launch projects from a GitHub Enterprise repository to your server by using a deploy key, which is an SSH key that grants access to a single repository. GitHub Enterprise attaches the public part of the key directly to your repository instead of a personal user account, and the private part of the key remains on your server. For more information, see "Delivering deployments."
Deploy keys can either be setup using the following API endpoints, or by using GitHub. To learn how to set deploy keys up in GitHub, see "Managing deploy keys."
get /repos/{owner}/{repo}/keys
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/keys
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/keys', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"id": 1,
"key": "ssh-rsa AAA...",
"url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
"title": "octocat@octomac",
"verified": true,
"created_at": "2014-12-10T15:53:42Z",
"read_only": true
}
]
Notes
Create a deploy key
You can create a read-only deploy key.
post /repos/{owner}/{repo}/keys
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
title |
string | body |
A name for the key. |
key |
string | body |
Required. The contents of the key. |
read_only |
boolean | body |
If Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see "Repository permission levels for an organization" and "Permission levels for a user account repository." |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/keys \
-d '{"key":"key"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/keys', {
owner: 'octocat',
repo: 'hello-world',
key: 'key'
})
Default response
Status: 201 Created
{
"id": 1,
"key": "ssh-rsa AAA...",
"url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
"title": "octocat@octomac",
"verified": true,
"created_at": "2014-12-10T15:53:42Z",
"read_only": true
}
Notes
get /repos/{owner}/{repo}/keys/{key_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
key_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/keys/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {
owner: 'octocat',
repo: 'hello-world',
key_id: 42
})
Default response
Status: 200 OK
{
"id": 1,
"key": "ssh-rsa AAA...",
"url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
"title": "octocat@octomac",
"verified": true,
"created_at": "2014-12-10T15:53:42Z",
"read_only": true
}
Notes
Delete a deploy key
Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
delete /repos/{owner}/{repo}/keys/{key_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
key_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/keys/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {
owner: 'octocat',
repo: 'hello-world',
key_id: 42
})
Default Response
Status: 204 No Content
Notes
Deployments
Deployments are requests to deploy a specific ref (branch, SHA, tag). GitHub dispatches a deployment
event that external services can listen for and act on when new deployments are created. Deployments enable developers and organizations to build loosely coupled tooling around deployments, without having to worry about the implementation details of delivering different types of applications (e.g., web, native).
Deployment statuses allow external services to mark deployments with an error
, failure
, pending
, in_progress
, queued
, or success
state that systems listening to deployment_status
events can consume.
Deployment statuses can also include an optional description
and log_url
, which are highly recommended because they make deployment statuses more useful. The log_url
is the full URL to the deployment output, and
the description
is a high-level summary of what happened with the deployment.
GitHub dispatches deployment
and deployment_status
events when new deployments and deployment statuses are created. These events allows third-party integrations to receive respond to deployment requests and update the status of a deployment as progress is made.
Below is a simple sequence diagram for how these interactions would work.
+---------+ +--------+ +-----------+ +-------------+
| Tooling | | GitHub | | 3rd Party | | Your Server |
+---------+ +--------+ +-----------+ +-------------+
| | | |
| Create Deployment | | |
|--------------------->| | |
| | | |
| Deployment Created | | |
|<---------------------| | |
| | | |
| | Deployment Event | |
| |---------------------->| |
| | | SSH+Deploys |
| | |-------------------->|
| | | |
| | Deployment Status | |
| |<----------------------| |
| | | |
| | | Deploy Completed |
| | |<--------------------|
| | | |
| | Deployment Status | |
| |<----------------------| |
| | | |
Keep in mind that GitHub is never actually accessing your servers. It's up to your third-party integration to interact with deployment events. Multiple systems can listen for deployment events, and it's up to each of those systems to decide whether they're responsible for pushing the code out to your servers, building native code, etc.
Note that the repo_deployment
OAuth scope grants targeted access to deployments and deployment statuses without granting access to repository code, while the public_repo
and repo
scopes grant permission to code as well.
Inactive deployments
When you set the state of a deployment to success
, then all prior non-transient, non-production environment deployments in the same repository will become inactive
. To avoid this, you can set auto_inactive
to false
when creating the deployment status.
You can communicate that a transient environment no longer exists by setting its state
to inactive
. Setting the state
to inactive
shows the deployment as destroyed
in GitHub and removes access to it.
List deployments
Simple filtering of deployments is available via query parameters:
get /repos/{owner}/{repo}/deployments
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
sha |
string | query |
The SHA recorded at creation time. |
ref |
string | query |
The name of the ref. This can be a branch, tag, or SHA. |
task |
string | query |
The name of the task for the deployment (e.g., |
environment |
string | query |
The name of the environment that was deployed to (e.g., |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/deployments
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/deployments', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"url": "https://api.github.com/repos/octocat/example/deployments/1",
"id": 1,
"node_id": "MDEwOkRlcGxveW1lbnQx",
"sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
"ref": "topic-branch",
"task": "deploy",
"payload": {
"deploy": "migrate"
},
"original_environment": "staging",
"environment": "production",
"description": "Deploy request from hubot",
"creator": {
"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
},
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses",
"repository_url": "https://api.github.com/repos/octocat/example",
"transient_environment": false,
"production_environment": true
}
]
Notes
Preview notice
The inactive
state and the log_url
, environment_url
, and auto_inactive
parameters are currently available for developers to preview. 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.ant-man-preview+json
Create a deployment
Deployments offer a few configurable parameters with certain defaults.
The ref
parameter can be any named branch, tag, or SHA. At GitHub we often deploy branches and verify them
before we merge a pull request.
The environment
parameter allows deployments to be issued to different runtime environments. Teams often have
multiple environments for verifying their applications, such as production
, staging
, and qa
. This parameter
makes it easier to track which environments have requested deployments. The default environment is production
.
The auto_merge
parameter is used to ensure that the requested ref is not behind the repository's default branch.
If the ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge
succeeds, the API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the
API will return a failure response.
By default, commit statuses for every submitted context must be in a
success
state. The required_contexts
parameter allows you to specify a subset of contexts that must be
success
, or to specify contexts that have not yet been submitted. You are not required to use commit statuses to
deploy. If you do not require any contexts or create any commit statuses, the deployment will always succeed.
The payload
parameter is available for any extra information that a deployment system might need. It is a JSON
text field that will be passed on when a deployment event is dispatched.
The task
parameter is used by the deployment system to allow different execution paths. In the web world this
might be deploy:migrations
to run schema changes on the system. In the compiled world this could be a flag to
compile an application with debugging enabled.
Users with repo
or repo_deployment
scopes can create a deployment for a given ref.
Merged branch response
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating a deployment. This auto-merge happens when:
- Auto-merge option is enabled in the repository
- Topic branch does not include the latest changes on the base branch, which is
master
in the response example - There are no merge conflicts
If there are no new commits in the base branch, a new request to create a deployment should give a successful response.
Merge conflict response
This error happens when the auto_merge
option is enabled and when the default branch (in this case master
),
can't be merged into the branch that's being deployed (in this case topic-branch
), due to merge conflicts.
Failed commit status checks
This error happens when the required_contexts
parameter indicates that one or more contexts need to have a
success
status for the commit to be deployed, but one or more of the required contexts do not have a state of
success
.
post /repos/{owner}/{repo}/deployments
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
ref |
string | body |
Required. The ref to deploy. This can be a branch, tag, or SHA. |
task |
string | body |
Specifies a task to execute (e.g., deploy
|
auto_merge |
boolean | body |
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch. Default:true
|
required_contexts |
array of strings | body |
The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts. |
payload |
body |
JSON payload with extra information about the deployment. |
|
environment |
string | body |
Name for the target deployment environment (e.g., production
|
description |
string | body |
Short description of the deployment. |
transient_environment |
boolean | body |
Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. |
production_environment |
boolean | body |
Specifies if the given environment is one that end-users directly interact with. Default: |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/deployments \
-d '{"ref":"ref"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/deployments', {
owner: 'octocat',
repo: 'hello-world',
ref: 'ref'
})
Simple example
Status: 201 Created
{
"url": "https://api.github.com/repos/octocat/example/deployments/1",
"id": 1,
"node_id": "MDEwOkRlcGxveW1lbnQx",
"sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
"ref": "topic-branch",
"task": "deploy",
"payload": {
"deploy": "migrate"
},
"original_environment": "staging",
"environment": "production",
"description": "Deploy request from hubot",
"creator": {
"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
},
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses",
"repository_url": "https://api.github.com/repos/octocat/example",
"transient_environment": false,
"production_environment": true
}
Advanced example
Status: 201 Created
{
"url": "https://api.github.com/repos/octocat/example/deployments/1",
"id": 1,
"node_id": "MDEwOkRlcGxveW1lbnQx",
"sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
"ref": "topic-branch",
"task": "deploy",
"payload": {
"deploy": "migrate"
},
"original_environment": "staging",
"environment": "production",
"description": "Deploy request from hubot",
"creator": {
"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
},
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses",
"repository_url": "https://api.github.com/repos/octocat/example",
"transient_environment": false,
"production_environment": true
}
Merged branch response
Status: 202 Accepted
{
"message": "Auto-merged master into topic-branch on deployment."
}
Merge conflict response
Status: 409 Conflict
{
"message": "Conflict merging master into topic-branch"
}
Failed commit status checks
Status: 409 Conflict
{
"message": "Conflict: Commit status checks failed for topic-branch."
}
Notes
Preview notice
The inactive
state and the log_url
, environment_url
, and auto_inactive
parameters are currently available for developers to preview. 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.ant-man-preview+json
get /repos/{owner}/{repo}/deployments/{deployment_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
deployment_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/deployments/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {
owner: 'octocat',
repo: 'hello-world',
deployment_id: 42
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/example/deployments/1",
"id": 1,
"node_id": "MDEwOkRlcGxveW1lbnQx",
"sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
"ref": "topic-branch",
"task": "deploy",
"payload": {
"deploy": "migrate"
},
"original_environment": "staging",
"environment": "production",
"description": "Deploy request from hubot",
"creator": {
"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
},
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses",
"repository_url": "https://api.github.com/repos/octocat/example",
"transient_environment": false,
"production_environment": true
}
Notes
Preview notice
The inactive
state and the log_url
, environment_url
, and auto_inactive
parameters are currently available for developers to preview. 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.ant-man-preview+json
List deployment statuses
Users with pull access can view deployment statuses for a deployment:
get /repos/{owner}/{repo}/deployments/{deployment_id}/statuses
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
deployment_id |
integer | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/deployments/42/statuses
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}/statuses', {
owner: 'octocat',
repo: 'hello-world',
deployment_id: 42
})
Default response
Status: 200 OK
[
{
"url": "https://api.github.com/repos/octocat/example/deployments/42/statuses/1",
"id": 1,
"node_id": "MDE2OkRlcGxveW1lbnRTdGF0dXMx",
"state": "success",
"creator": {
"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
},
"description": "Deployment finished successfully.",
"environment": "production",
"target_url": "https://example.com/deployment/42/output",
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"deployment_url": "https://api.github.com/repos/octocat/example/deployments/42",
"repository_url": "https://api.github.com/repos/octocat/example",
"environment_url": "",
"log_url": "https://example.com/deployment/42/output"
}
]
Notes
Preview notices
New features in the Deployments API on GitHub Enterprise Server are currently available during a public beta. Please see the blog post for full details.
To access the new environment
parameter, the two new values for the state
parameter (in_progress
and queued
), and use auto_inactive
on production deployments during the public beta period, you must provide the following custom media type in the Accept
header:
application/vnd.github.flash-preview+json
The inactive
state and the log_url
, environment_url
, and auto_inactive
parameters are currently available for developers to preview. 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.ant-man-preview+json
Create a deployment status
Users with push
access can create deployment statuses for a given deployment.
GitHub Apps require read & write
access to "Deployments" and read-only
access to "Repo contents" (for private repos). OAuth Apps require the repo_deployment
scope.
post /repos/{owner}/{repo}/deployments/{deployment_id}/statuses
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
deployment_id |
integer | path | |
state |
string | body |
Required. The state of the status. Can be one of |
target_url |
string | body |
The target URL to associate with this status. This URL should contain output to keep the user updated while the task is running or serve as historical information for what happened in the deployment. Note: It's recommended to use the |
log_url |
string | body |
The full URL of the deployment's output. This parameter replaces |
description |
string | body |
A short description of the status. The maximum description length is 140 characters. |
environment |
string | body |
Name for the target deployment environment, which can be changed when setting a deploy status. For example, |
environment_url |
string | body |
Sets the URL for accessing your environment. |
auto_inactive |
boolean | body |
Adds a new true
|
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/deployments/42/statuses \
-d '{"state":"state"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/deployments/{deployment_id}/statuses', {
owner: 'octocat',
repo: 'hello-world',
deployment_id: 42,
state: 'state'
})
Default response
Status: 201 Created
{
"url": "https://api.github.com/repos/octocat/example/deployments/42/statuses/1",
"id": 1,
"node_id": "MDE2OkRlcGxveW1lbnRTdGF0dXMx",
"state": "success",
"creator": {
"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
},
"description": "Deployment finished successfully.",
"environment": "production",
"target_url": "https://example.com/deployment/42/output",
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"deployment_url": "https://api.github.com/repos/octocat/example/deployments/42",
"repository_url": "https://api.github.com/repos/octocat/example",
"environment_url": "",
"log_url": "https://example.com/deployment/42/output"
}
Notes
Preview notices
New features in the Deployments API on GitHub Enterprise Server are currently available during a public beta. Please see the blog post for full details.
To access the new environment
parameter, the two new values for the state
parameter (in_progress
and queued
), and use auto_inactive
on production deployments during the public beta period, you must provide the following custom media type in the Accept
header:
application/vnd.github.flash-preview+json
The inactive
state and the log_url
, environment_url
, and auto_inactive
parameters are currently available for developers to preview. 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.ant-man-preview+json
Get a deployment status
Users with pull access can view a deployment status for a deployment:
get /repos/{owner}/{repo}/deployments/{deployment_id}/statuses/{status_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
deployment_id |
integer | path | |
status_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/deployments/42/statuses/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}/statuses/{status_id}', {
owner: 'octocat',
repo: 'hello-world',
deployment_id: 42,
status_id: 42
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/example/deployments/42/statuses/1",
"id": 1,
"node_id": "MDE2OkRlcGxveW1lbnRTdGF0dXMx",
"state": "success",
"creator": {
"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
},
"description": "Deployment finished successfully.",
"environment": "production",
"target_url": "https://example.com/deployment/42/output",
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"deployment_url": "https://api.github.com/repos/octocat/example/deployments/42",
"repository_url": "https://api.github.com/repos/octocat/example",
"environment_url": "",
"log_url": "https://example.com/deployment/42/output"
}
Notes
Preview notices
New features in the Deployments API on GitHub Enterprise Server are currently available during a public beta. Please see the blog post for full details.
To access the new environment
parameter, the two new values for the state
parameter (in_progress
and queued
), and use auto_inactive
on production deployments during the public beta period, you must provide the following custom media type in the Accept
header:
application/vnd.github.flash-preview+json
The inactive
state and the log_url
, environment_url
, and auto_inactive
parameters are currently available for developers to preview. 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.ant-man-preview+json
Forks
get /repos/{owner}/{repo}/forks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
sort |
string | query |
The sort order. Can be either |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/forks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/forks', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": true,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"template_repository": null,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false,
"license": {
"key": "mit",
"name": "MIT License",
"spdx_id": "MIT",
"url": "https://api.github.com/licenses/mit",
"node_id": "MDc6TGljZW5zZW1pdA=="
}
}
]
Notes
Create a fork
Create a fork for the authenticated user.
Note: Forking a Repository happens asynchronously. You may have to wait a short period of time before you can access the git objects. If this takes longer than 5 minutes, be sure to contact your GitHub Enterprise site administrator.
post /repos/{owner}/{repo}/forks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
organization |
string | body |
Optional parameter to specify the organization name if forking into an organization. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/forks \
-d '{"organization":"organization"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/forks', {
owner: 'octocat',
repo: 'hello-world',
organization: 'organization'
})
Default response
Status: 202 Accepted
{
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": true,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
},
"allow_rebase_merge": true,
"template_repository": null,
"allow_squash_merge": true,
"allow_merge_commit": true,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false
}
Notes
Invitations
The Repository Invitations API allows users or external services to invite other users to collaborate on a repo. The invited users (or external services on behalf of invited users) can choose to accept or decline the invitations.
Note that the repo:invite
OAuth scope grants targeted
access to invitations without also granting access to repository code, while the
repo
scope grants permission to code as well as invitations.
Invite a user to a repository
Use the API endpoint for adding a collaborator. For more information, see "Add a repository collaborator."
List repository invitations
When authenticating as a user with admin rights to a repository, this endpoint will list all currently open repository invitations.
get /repos/{owner}/{repo}/invitations
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/invitations
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/invitations', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"id": 1,
"repository": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}"
},
"invitee": {
"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
},
"inviter": {
"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
},
"permissions": "write",
"created_at": "2016-06-13T14:52:50-05:00",
"url": "https://api.github.com/user/repository_invitations/1296269",
"html_url": "https://github.com/octocat/Hello-World/invitations"
}
]
Notes
patch /repos/{owner}/{repo}/invitations/{invitation_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
invitation_id |
integer | path | |
permissions |
string | body |
The permissions that the associated user will have on the repository. Valid values are |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/invitations/42 \
-d '{"permissions":"permissions"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/invitations/{invitation_id}', {
owner: 'octocat',
repo: 'hello-world',
invitation_id: 42,
permissions: 'permissions'
})
Default response
Status: 200 OK
{
"id": 1,
"repository": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}"
},
"invitee": {
"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
},
"inviter": {
"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
},
"permissions": "write",
"created_at": "2016-06-13T14:52:50-05:00",
"url": "https://api.github.com/user/repository_invitations/1296269",
"html_url": "https://github.com/octocat/Hello-World/invitations"
}
Notes
delete /repos/{owner}/{repo}/invitations/{invitation_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
invitation_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/invitations/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/invitations/{invitation_id}', {
owner: 'octocat',
repo: 'hello-world',
invitation_id: 42
})
Default Response
Status: 204 No Content
Notes
List repository invitations for the authenticated user
When authenticating as a user, this endpoint will list all currently open repository invitations for that user.
get /user/repository_invitations
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/repository_invitations
JavaScript (@octokit/core.js)
await octokit.request('GET /user/repository_invitations')
Default response
Status: 200 OK
[
{
"id": 1,
"repository": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}"
},
"invitee": {
"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
},
"inviter": {
"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
},
"permissions": "write",
"created_at": "2016-06-13T14:52:50-05:00",
"url": "https://api.github.com/user/repository_invitations/1296269",
"html_url": "https://github.com/octocat/Hello-World/invitations"
}
]
patch /user/repository_invitations/{invitation_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
invitation_id |
integer | path |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/repository_invitations/42
JavaScript (@octokit/core.js)
await octokit.request('PATCH /user/repository_invitations/{invitation_id}', {
invitation_id: 42
})
Default Response
Status: 204 No Content
delete /user/repository_invitations/{invitation_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
invitation_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/repository_invitations/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /user/repository_invitations/{invitation_id}', {
invitation_id: 42
})
Default Response
Status: 204 No Content
Merging
The Repo Merging API supports merging branches in a repository. This accomplishes essentially the same thing as merging one branch into another in a local repository and then pushing to GitHub Enterprise. The benefit is that the merge is done on the server side and a local repository is not needed. This makes it more appropriate for automation and other tools where maintaining local repositories would be cumbersome and inefficient.
The authenticated user will be the author of any merges done through this endpoint.
post /repos/{owner}/{repo}/merges
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
base |
string | body |
Required. The name of the base branch that the head will be merged into. |
head |
string | body |
Required. The head to merge. This can be a branch name or a commit SHA1. |
commit_message |
string | body |
Commit message to use for the merge commit. If omitted, a default message will be used. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/merges \
-d '{"base":"base","head":"head"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/merges', {
owner: 'octocat',
repo: 'hello-world',
base: 'base',
head: 'head'
})
Default response
Status: 201 Created
{
"sha": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
"node_id": "MDY6Q29tbWl0N2ZkMWE2MGIwMWY5MWIzMTRmNTk5NTVhNGU0ZDRlODBkOGVkZjExZA==",
"commit": {
"author": {
"name": "The Octocat",
"date": "2012-03-06T15:06:50-08:00",
"email": "octocat@nowhere.com"
},
"committer": {
"name": "The Octocat",
"date": "2012-03-06T15:06:50-08:00",
"email": "octocat@nowhere.com"
},
"message": "Shipped cool_feature!",
"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": 0,
"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": 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": [
{
"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"
}
]
}
Missing base response
Status: 404 Not Found
{
"message": "Base does not exist"
}
Missing head response
Status: 404 Not Found
{
"message": "Head does not exist"
}
Merge conflict response
Status: 409 Conflict
{
"message": "Merge Conflict"
}
Notes
Pages
The GitHub Pages API retrieves information about your GitHub Pages configuration, and the statuses of your builds. Information about the site and the builds can only be accessed by authenticated owners, even though the websites are public. For more information, see "About GitHub Pages."
In GitHub Pages API endpoints with a status
key in their response, the value can be one of:
null
: The site has yet to be built.queued
: The build has been requested but not yet begun.building
:The build is in progress.built
: The site has been built.errored
: Indicates an error occurred during the build.
In GitHub Pages API endpoints that support the mister-fantastic-preview
and return GitHub Pages site information, the JSON responses include these fields:
html_url
: The absolute URL (including scheme) of the rendered Pages site. For example,https://username.github.io
.source
: An object that contains the source branch and directory for the rendered Pages site. This includes:branch
: The repository branch used to publish your site's source files. For example, master or gh-pages.path
: The repository directory from which the site publishes. Will be either/
or/docs
.
get /repos/{owner}/{repo}/pages
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/pages
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pages', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/github/developer.github.com/pages",
"status": "built",
"cname": "developer.github.com",
"custom_404": false,
"html_url": "https://developer.github.com",
"source": {
"branch": "master",
"directory": "/"
}
}
Notes
Preview notice
The GitHub Pages API contains two additional fields in responses, which developers can preview: html_url
and source
. To see these two new fields, you must provide a custom media type in the Accept
header:
application/vnd.github.mister-fantastic-preview+json
Create a GitHub Pages site
Configures a GitHub Enterprise Server Pages site. For more information, see "About GitHub Pages."
post /repos/{owner}/{repo}/pages
Parameters
Name | Type | In | Description | ||||
---|---|---|---|---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notices. |
||||
owner |
string | path | |||||
repo |
string | path | |||||
source |
object | body |
Required. The source branch and directory used to publish your Pages site. |
||||
source object |
branch (string) |
Required. The repository branch used to publish your site's source files. Can be either |
path (string) |
The repository directory that includes the source files for the Pages site. When |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.switcheroo-preview+json" \
https://{hostname}/repos/octocat/hello-world/pages \
-d '{"source":{"branch":"branch","path":"path"}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/pages', {
owner: 'octocat',
repo: 'hello-world',
source: {
branch: 'branch',
path: 'path'
},
mediaType: {
previews: [
'switcheroo'
]
}
})
Default response
Status: 201 Created
{
"url": "https://api.github.com/repos/github/developer.github.com/pages",
"status": "built",
"cname": "developer.github.com",
"custom_404": false,
"html_url": "https://developer.github.com",
"source": {
"branch": "master",
"directory": "/"
}
}
Notes
Preview notices
Enabling and disabling Pages in the Pages API is currently available for developers to preview. See the blog post preview for more details. To access the new endpoints during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.switcheroo-preview+json
☝️ This header is required.
The GitHub Pages API contains two additional fields in responses, which developers can preview: html_url
and source
. To see these two new fields, you must provide a custom media type in the Accept
header:
application/vnd.github.mister-fantastic-preview+json
Update information about a GitHub Pages site
Updates information for a GitHub Enterprise Server Pages site. For more information, see "About GitHub Pages.
put /repos/{owner}/{repo}/pages
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
source |
string | body |
Update the source for the repository. Must include the branch name, and may optionally specify the subdirectory |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/pages \
-d '{"source":"source"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /repos/{owner}/{repo}/pages', {
owner: 'octocat',
repo: 'hello-world',
source: 'source'
})
Default Response
Status: 204 No Content
Notes
Preview notice
The GitHub Pages API contains two additional fields in responses, which developers can preview: html_url
and source
. To see these two new fields, you must provide a custom media type in the Accept
header:
application/vnd.github.mister-fantastic-preview+json
delete /repos/{owner}/{repo}/pages
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.switcheroo-preview+json" \
https://{hostname}/repos/octocat/hello-world/pages
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/pages', {
owner: 'octocat',
repo: 'hello-world',
mediaType: {
previews: [
'switcheroo'
]
}
})
Default Response
Status: 204 No Content
Notes
Preview notice
Enabling and disabling Pages in the Pages API is currently available for developers to preview. See the blog post preview for more details. To access the new endpoints during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.switcheroo-preview+json
☝️ This header is required.
get /repos/{owner}/{repo}/pages/builds
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/pages/builds
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pages/builds', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
"status": "built",
"error": {
"message": null
},
"pusher": {
"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
},
"commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
"duration": 2104,
"created_at": "2014-02-10T19:00:49Z",
"updated_at": "2014-02-10T19:00:51Z"
}
]
Notes
Request a GitHub Pages build
You can request that your site be built from the latest revision on the default branch. This has the same effect as pushing a commit to your default branch, but does not require an additional commit. Manually triggering page builds can be helpful when diagnosing build warnings and failures.
Build requests are limited to one concurrent build per repository and one concurrent build per requester. If you request a build while another is still in progress, the second request will be queued until the first completes.
post /repos/{owner}/{repo}/pages/builds
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.mister-fantastic-preview+json" \
https://{hostname}/repos/octocat/hello-world/pages/builds
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/pages/builds', {
owner: 'octocat',
repo: 'hello-world',
mediaType: {
previews: [
'mister-fantastic'
]
}
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/github/developer.github.com/pages/builds/latest",
"status": "queued"
}
Notes
Preview notice
The GitHub Pages API contains two additional fields in responses, which developers can preview: html_url
and source
. To see these two new fields, you must provide a custom media type in the Accept
header:
application/vnd.github.mister-fantastic-preview+json
☝️ This header is required.
get /repos/{owner}/{repo}/pages/builds/latest
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/pages/builds/latest
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pages/builds/latest', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
"status": "built",
"error": {
"message": null
},
"pusher": {
"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
},
"commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
"duration": 2104,
"created_at": "2014-02-10T19:00:49Z",
"updated_at": "2014-02-10T19:00:51Z"
}
Notes
get /repos/{owner}/{repo}/pages/builds/{build_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
build_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/pages/builds/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pages/builds/{build_id}', {
owner: 'octocat',
repo: 'hello-world',
build_id: 42
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
"status": "built",
"error": {
"message": null
},
"pusher": {
"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
},
"commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
"duration": 2104,
"created_at": "2014-02-10T19:00:49Z",
"updated_at": "2014-02-10T19:00:51Z"
}
Notes
Releases
Note: The Releases API replaces the Downloads API. You can retrieve the download count and browser download URL from the endpoints in this API that return releases and release assets.
List releases
This returns a list of releases, which does not include regular Git tags that have not been associated with a release. To get a list of Git tags, use the Repository Tags API.
Information about published releases are available to everyone. Only users with push access will receive listings for draft releases.
get /repos/{owner}/{repo}/releases
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/releases', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/1",
"html_url": "https://github.com/octocat/Hello-World/releases/v1.0.0",
"assets_url": "https://api.github.com/repos/octocat/Hello-World/releases/1/assets",
"upload_url": "https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
"tarball_url": "https://api.github.com/repos/octocat/Hello-World/tarball/v1.0.0",
"zipball_url": "https://api.github.com/repos/octocat/Hello-World/zipball/v1.0.0",
"id": 1,
"node_id": "MDc6UmVsZWFzZTE=",
"tag_name": "v1.0.0",
"target_commitish": "master",
"name": "v1.0.0",
"body": "Description of the release",
"draft": false,
"prerelease": false,
"created_at": "2013-02-27T19:35:32Z",
"published_at": "2013-02-27T19:35:32Z",
"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
},
"assets": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
]
}
]
Notes
Create a release
Users with push access to the repository can create a release.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" for details.
post /repos/{owner}/{repo}/releases
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
tag_name |
string | body |
Required. The name of the tag. |
target_commitish |
string | body |
Specifies the commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. Unused if the Git tag already exists. Default: the repository's default branch (usually |
name |
string | body |
The name of the release. |
body |
string | body |
Text describing the contents of the tag. |
draft |
boolean | body |
|
prerelease |
boolean | body |
|
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases \
-d '{"tag_name":"tag_name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/releases', {
owner: 'octocat',
repo: 'hello-world',
tag_name: 'tag_name'
})
Default response
Status: 201 Created
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/1",
"html_url": "https://github.com/octocat/Hello-World/releases/v1.0.0",
"assets_url": "https://api.github.com/repos/octocat/Hello-World/releases/1/assets",
"upload_url": "https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
"tarball_url": "https://api.github.com/repos/octocat/Hello-World/tarball/v1.0.0",
"zipball_url": "https://api.github.com/repos/octocat/Hello-World/zipball/v1.0.0",
"id": 1,
"node_id": "MDc6UmVsZWFzZTE=",
"tag_name": "v1.0.0",
"target_commitish": "master",
"name": "v1.0.0",
"body": "Description of the release",
"draft": false,
"prerelease": false,
"created_at": "2013-02-27T19:35:32Z",
"published_at": "2013-02-27T19:35:32Z",
"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
},
"assets": []
}
Notes
Get a release asset
To download the asset's binary content, set the Accept
header of the request to application/octet-stream
. The API will either redirect the client to the location, or stream it directly if possible. API clients should handle both a 200
or 302
response.
get /repos/{owner}/{repo}/releases/assets/{asset_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
asset_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/assets/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/releases/assets/{asset_id}', {
owner: 'octocat',
repo: 'hello-world',
asset_id: 42
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
Notes
Update a release asset
Users with push access to the repository can edit a release asset.
patch /repos/{owner}/{repo}/releases/assets/{asset_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
asset_id |
integer | path | |
name |
string | body |
The file name of the asset. |
label |
string | body |
An alternate short description of the asset. Used in place of the filename. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/assets/42 \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/releases/assets/{asset_id}', {
owner: 'octocat',
repo: 'hello-world',
asset_id: 42,
name: 'name'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
Notes
delete /repos/{owner}/{repo}/releases/assets/{asset_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
asset_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/assets/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/releases/assets/{asset_id}', {
owner: 'octocat',
repo: 'hello-world',
asset_id: 42
})
Default Response
Status: 204 No Content
Notes
Get the latest release
View the latest published full release for the repository.
The latest release is the most recent non-prerelease, non-draft release, sorted by the created_at
attribute. The created_at
attribute is the date of the commit used for the release, and not the date when the release was drafted or published.
get /repos/{owner}/{repo}/releases/latest
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/latest
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/releases/latest', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/1",
"html_url": "https://github.com/octocat/Hello-World/releases/v1.0.0",
"assets_url": "https://api.github.com/repos/octocat/Hello-World/releases/1/assets",
"upload_url": "https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
"tarball_url": "https://api.github.com/repos/octocat/Hello-World/tarball/v1.0.0",
"zipball_url": "https://api.github.com/repos/octocat/Hello-World/zipball/v1.0.0",
"id": 1,
"node_id": "MDc6UmVsZWFzZTE=",
"tag_name": "v1.0.0",
"target_commitish": "master",
"name": "v1.0.0",
"body": "Description of the release",
"draft": false,
"prerelease": false,
"created_at": "2013-02-27T19:35:32Z",
"published_at": "2013-02-27T19:35:32Z",
"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
},
"assets": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
]
}
Notes
Get a release by tag name
Get a published release with the specified tag.
get /repos/{owner}/{repo}/releases/tags/{tag}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
tag |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/tags/TAG
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/releases/tags/{tag}', {
owner: 'octocat',
repo: 'hello-world',
tag: 'tag'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/1",
"html_url": "https://github.com/octocat/Hello-World/releases/v1.0.0",
"assets_url": "https://api.github.com/repos/octocat/Hello-World/releases/1/assets",
"upload_url": "https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
"tarball_url": "https://api.github.com/repos/octocat/Hello-World/tarball/v1.0.0",
"zipball_url": "https://api.github.com/repos/octocat/Hello-World/zipball/v1.0.0",
"id": 1,
"node_id": "MDc6UmVsZWFzZTE=",
"tag_name": "v1.0.0",
"target_commitish": "master",
"name": "v1.0.0",
"body": "Description of the release",
"draft": false,
"prerelease": false,
"created_at": "2013-02-27T19:35:32Z",
"published_at": "2013-02-27T19:35:32Z",
"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
},
"assets": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
]
}
Notes
Get a release
Note: This returns an upload_url
key corresponding to the endpoint for uploading release assets. This key is a hypermedia resource.
get /repos/{owner}/{repo}/releases/{release_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
release_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/releases/{release_id}', {
owner: 'octocat',
repo: 'hello-world',
release_id: 42
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/1",
"html_url": "https://github.com/octocat/Hello-World/releases/v1.0.0",
"assets_url": "https://api.github.com/repos/octocat/Hello-World/releases/1/assets",
"upload_url": "https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
"tarball_url": "https://api.github.com/repos/octocat/Hello-World/tarball/v1.0.0",
"zipball_url": "https://api.github.com/repos/octocat/Hello-World/zipball/v1.0.0",
"id": 1,
"node_id": "MDc6UmVsZWFzZTE=",
"tag_name": "v1.0.0",
"target_commitish": "master",
"name": "v1.0.0",
"body": "Description of the release",
"draft": false,
"prerelease": false,
"created_at": "2013-02-27T19:35:32Z",
"published_at": "2013-02-27T19:35:32Z",
"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
},
"assets": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
]
}
Notes
Update a release
Users with push access to the repository can edit a release.
patch /repos/{owner}/{repo}/releases/{release_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
release_id |
integer | path | |
tag_name |
string | body |
The name of the tag. |
target_commitish |
string | body |
Specifies the commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. Unused if the Git tag already exists. Default: the repository's default branch (usually |
name |
string | body |
The name of the release. |
body |
string | body |
Text describing the contents of the tag. |
draft |
boolean | body |
|
prerelease |
boolean | body |
|
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/42 \
-d '{"tag_name":"tag_name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/releases/{release_id}', {
owner: 'octocat',
repo: 'hello-world',
release_id: 42,
tag_name: 'tag_name'
})
Default response
Status: 200 OK
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/1",
"html_url": "https://github.com/octocat/Hello-World/releases/v1.0.0",
"assets_url": "https://api.github.com/repos/octocat/Hello-World/releases/1/assets",
"upload_url": "https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
"tarball_url": "https://api.github.com/repos/octocat/Hello-World/tarball/v1.0.0",
"zipball_url": "https://api.github.com/repos/octocat/Hello-World/zipball/v1.0.0",
"id": 1,
"node_id": "MDc6UmVsZWFzZTE=",
"tag_name": "v1.0.0",
"target_commitish": "master",
"name": "v1.0.0",
"body": "Description of the release",
"draft": false,
"prerelease": false,
"created_at": "2013-02-27T19:35:32Z",
"published_at": "2013-02-27T19:35:32Z",
"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
},
"assets": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
]
}
Notes
Delete a release
Users with push access to the repository can delete a release.
delete /repos/{owner}/{repo}/releases/{release_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
release_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/releases/{release_id}', {
owner: 'octocat',
repo: 'hello-world',
release_id: 42
})
Default Response
Status: 204 No Content
Notes
get /repos/{owner}/{repo}/releases/{release_id}/assets
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
release_id |
integer | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/42/assets
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/releases/{release_id}/assets', {
owner: 'octocat',
repo: 'hello-world',
release_id: 42
})
Default response
Status: 200 OK
[
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
]
Notes
Upload a release asset
This endpoint makes use of a Hypermedia relation to determine which URL to access. The endpoint you call to upload release assets is specific to your release. Use the upload_url
returned in the response of the Create a release endpoint to upload a release asset.
You need to use an HTTP client which supports SNI to make calls to this endpoint.
Most libraries will set the required Content-Length
header automatically. Use the required Content-Type
header to provide the media type of the asset. For a list of media types, see Media Types. For example:
application/zip
GitHub expects the asset data in its raw binary form, rather than JSON. You will send the raw binary content of the asset as the request body. Everything else about the endpoint is the same as the rest of the API. For example, you'll still need to pass your authentication to be able to upload an asset.
When an upstream failure occurs, you will receive a 502 Bad Gateway
status. This may leave an empty asset with a state of starter
. It can be safely deleted.
Notes:
- GitHub renames asset filenames that have special characters, non-alphanumeric characters, and leading or trailing periods. The "List assets for a release" endpoint lists the renamed filenames. For more information and help, contact GitHub Support.
- If you upload an asset with the same filename as another uploaded asset, you'll receive an error and must delete the old file before you can re-upload the new asset.
post /repos/{owner}/{repo}/releases/{release_id}/assets
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
content-length |
string | header |
Size of the asset in bytes. Most libraries will calculate the header automatically |
content-type |
string | header |
Media Type of the asset. For a list of media types, see https://www.iana.org/assignments/media-types/media-types.xhtml |
owner |
string | path |
owner parameter |
repo |
string | path |
repo parameter |
release_id |
integer | path |
release_id parameter |
name |
string | query |
name parameter |
label |
string | query |
label parameter |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/releases/42/assets
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/releases/{release_id}/assets', {
owner: 'octocat',
repo: 'hello-world',
release_id: 42
})
Response for successful upload
Status: 201 Created
{
"url": "https://api.github.com/repos/octocat/Hello-World/releases/assets/1",
"browser_download_url": "https://github.com/octocat/Hello-World/releases/download/v1.0.0/example.zip",
"id": 1,
"node_id": "MDEyOlJlbGVhc2VBc3NldDE=",
"name": "example.zip",
"label": "short description",
"state": "uploaded",
"content_type": "application/zip",
"size": 1024,
"download_count": 42,
"created_at": "2013-02-27T19:35:32Z",
"updated_at": "2013-02-27T19:35:32Z",
"uploader": {
"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
}
}
Notes
Statistics
The Repository Statistics API allows you to fetch the data that GitHub Enterprise uses for visualizing different types of repository activity.
A word about caching
Computing repository statistics is an expensive operation, so we try to return cached
data whenever possible. If the data hasn't been cached when you query a repository's
statistics, you'll receive a 202
response; a background job is also fired to
start compiling these statistics. Give the job a few moments to complete, and
then submit the request again. If the job has completed, that request will receive a
200
response with the statistics in the response body.
Repository statistics are cached by the SHA of the repository's default branch, which is usually master; pushing to the default branch resets the statistics cache.
Statistics exclude some types of commits
The statistics exposed by the API match the statistics shown by different repository graphs.
To summarize:
- All statistics exclude merge commits.
- Contributor statistics also exclude empty commits.
Get the weekly commit activity
Returns a weekly aggregate of the number of additions and deletions pushed to a repository.
get /repos/{owner}/{repo}/stats/code_frequency
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/stats/code_frequency
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/stats/code_frequency', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
[
1302998400,
1124,
-435
]
]
Notes
Get the last year of commit activity
Returns the last year of commit activity grouped by week. The days
array is a group of commits per day, starting on Sunday
.
get /repos/{owner}/{repo}/stats/commit_activity
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/stats/commit_activity
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/stats/commit_activity', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"days": [
0,
3,
26,
20,
39,
1,
0
],
"total": 89,
"week": 1336280400
}
]
Notes
Get all contributor commit activity
Returns the total
number of commits authored by the contributor. In addition, the response includes a Weekly Hash (weeks
array) with the following information:
w
- Start of the week, given as a Unix timestamp.a
- Number of additionsd
- Number of deletionsc
- Number of commits
get /repos/{owner}/{repo}/stats/contributors
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/stats/contributors
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/stats/contributors', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"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
},
"total": 135,
"weeks": [
{
"w": "1367712000",
"a": 6898,
"d": 77,
"c": 10
}
]
}
]
Notes
Get the weekly commit count
Returns the total commit counts for the owner
and total commit counts in all
. all
is everyone combined, including the owner
in the last 52 weeks. If you'd like to get the commit counts for non-owners, you can subtract owner
from all
.
The array order is oldest week (index 0) to most recent week.
get /repos/{owner}/{repo}/stats/participation
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/stats/participation
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/stats/participation', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
{
"all": [
11,
21,
15,
2,
8,
1,
8,
23,
17,
21,
11,
10,
33,
91,
38,
34,
22,
23,
32,
3,
43,
87,
71,
18,
13,
5,
13,
16,
66,
27,
12,
45,
110,
117,
13,
8,
18,
9,
19,
26,
39,
12,
20,
31,
46,
91,
45,
10,
24,
9,
29,
7
],
"owner": [
3,
2,
3,
0,
2,
0,
5,
14,
7,
9,
1,
5,
0,
48,
19,
2,
0,
1,
10,
2,
23,
40,
35,
8,
8,
2,
10,
6,
30,
0,
2,
9,
53,
104,
3,
3,
10,
4,
7,
11,
21,
4,
4,
22,
26,
63,
11,
2,
14,
1,
10,
3
]
}
Notes
Get the hourly commit count for each day
Each array contains the day number, hour number, and number of commits:
0-6
: Sunday - Saturday0-23
: Hour of day- Number of commits
For example, [2, 14, 25]
indicates that there were 25 total commits, during the 2:00pm hour on Tuesdays. All times are based on the time zone of individual commits.
get /repos/{owner}/{repo}/stats/punch_card
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/stats/punch_card
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/stats/punch_card', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
[
0,
0,
5
],
[
0,
1,
43
],
[
0,
2,
21
]
]
Notes
Statuses
The status API allows external services to mark commits with an error
,
failure
, pending
, or success
state, which is then reflected in pull requests
involving those commits.
Statuses can also include an optional description
and target_url
, and
we highly recommend providing them as they make statuses much more
useful in the GitHub UI.
As an example, one common use is for continuous integration
services to mark commits as passing or failing builds using status. The
target_url
would be the full URL to the build output, and the
description
would be the high level summary of what happened with the
build.
Statuses can include a context
to indicate what service is providing that status.
For example, you may have your continuous integration service push statuses with a context of ci
, and a security audit tool push statuses with a context of security
. You can
then use the Get the combined status for a specific reference to retrieve the whole status for a commit.
Note that the repo:status
OAuth scope grants targeted access to statuses without also granting access to repository code, while the
repo
scope grants permission to code as well as statuses.
If you are developing a GitHub App and want to provide more detailed information about an external service, you may want to use the Checks API.
Get the combined status for a specific reference
Users with pull access in a repository can access a combined view of commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name.
The most recent status for each context is returned, up to 100. This field paginates if there are over 100 contexts.
Additionally, a combined state
is returned. The state
is one of:
- failure if any of the contexts report as
error
orfailure
- pending if there are no statuses or a context is
pending
- success if the latest status for all contexts is
success
get /repos/{owner}/{repo}/commits/{ref}/status
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
ref |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/commits/REF/status
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/commits/{ref}/status', {
owner: 'octocat',
repo: 'hello-world',
ref: 'ref'
})
Default response
Status: 200 OK
{
"state": "success",
"statuses": [
{
"url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
"avatar_url": "https://github.com/images/error/hubot_happy.gif",
"id": 1,
"node_id": "MDY6U3RhdHVzMQ==",
"state": "success",
"description": "Build has completed successfully",
"target_url": "https://ci.example.com/1000/output",
"context": "continuous-integration/jenkins",
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z"
},
{
"url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
"avatar_url": "https://github.com/images/error/other_user_happy.gif",
"id": 2,
"node_id": "MDY6U3RhdHVzMg==",
"state": "success",
"description": "Testing has completed successfully",
"target_url": "https://ci.example.com/2000/output",
"context": "security/brakeman",
"created_at": "2012-08-20T01:19:13Z",
"updated_at": "2012-08-20T01:19:13Z"
}
],
"sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
"total_count": 2,
"repository": {
"id": 1296269,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}"
},
"commit_url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e",
"url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e/status"
}
Notes
List commit statuses for a reference
Users with pull access in a repository can view commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name. Statuses are returned in reverse chronological order. The first status in the list will be the latest one.
This resource is also available via a legacy route: GET /repos/:owner/:repo/statuses/:ref
.
get /repos/{owner}/{repo}/commits/{ref}/statuses
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
ref |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/commits/REF/statuses
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/commits/{ref}/statuses', {
owner: 'octocat',
repo: 'hello-world',
ref: 'ref'
})
Default response
Status: 200 OK
[
{
"url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
"avatar_url": "https://github.com/images/error/hubot_happy.gif",
"id": 1,
"node_id": "MDY6U3RhdHVzMQ==",
"state": "success",
"description": "Build has completed successfully",
"target_url": "https://ci.example.com/1000/output",
"context": "continuous-integration/jenkins",
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"creator": {
"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
}
}
]
Notes
Create a commit status
Users with push access in a repository can create commit statuses for a given SHA.
Note: there is a limit of 1000 statuses per sha
and context
within a repository. Attempts to create more than 1000 statuses will result in a validation error.
post /repos/{owner}/{repo}/statuses/{sha}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
sha |
string | path | |
state |
string | body |
Required. The state of the status. Can be one of |
target_url |
string | body |
The target URL to associate with this status. This URL will be linked from the GitHub Enterprise UI to allow users to easily see the source of the status. |
description |
string | body |
A short description of the status. |
context |
string | body |
A string label to differentiate this status from the status of other systems. Default:default
|
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/statuses/SHA \
-d '{"state":"state"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/statuses/{sha}', {
owner: 'octocat',
repo: 'hello-world',
sha: 'sha',
state: 'state'
})
Default response
Status: 201 Created
{
"url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
"avatar_url": "https://github.com/images/error/hubot_happy.gif",
"id": 1,
"node_id": "MDY6U3RhdHVzMQ==",
"state": "success",
"description": "Build has completed successfully",
"target_url": "https://ci.example.com/1000/output",
"context": "continuous-integration/jenkins",
"created_at": "2012-07-20T01:19:13Z",
"updated_at": "2012-07-20T01:19:13Z",
"creator": {
"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
}
}
Notes
Traffic
For repositories that you have push access to, the traffic API provides access to the information provided in your repository graph. For more information, see "Viewing traffic to a repository."
Webhooks
The Repository Webhooks API allows repository admins to manage the post-receive hooks for a repository. Webhooks can be managed using the JSON HTTP API, or the PubSubHubbub API.
If you would like to set up a single webhook to receive events from all of your organization's repositories, see our API documentation for Organization Webhooks.
get /repos/{owner}/{repo}/hooks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/hooks', {
owner: 'octocat',
repo: 'hello-world'
})
Default response
Status: 200 OK
[
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
]
Notes
Create a repository webhook
Repositories can have multiple webhooks installed. Each webhook should have a unique config
. Multiple webhooks can share the same config
as long as those webhooks do not have any events
that overlap.
Note: GitHub Enterprise release 2.17 and higher no longer allows admins to install new GitHub Services, and existing services will stop working in GitHub Enterprise release 2.20 and higher. You can use the Replacing GitHub Services guide to help you update your services to webhooks.
Here's how you can create a hook that posts payloads in JSON format:
post /repos/{owner}/{repo}/hooks
Parameters
Name | Type | In | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
Setting to |
||||||||
owner |
string | path | |||||||||
repo |
string | path | |||||||||
name |
string | body |
Use web
|
||||||||
config |
object | body |
Required. Key/value pairs to provide settings for this webhook. These are defined below. |
||||||||
config object |
url (string) |
Required. The URL to which the payloads will be delivered. |
content_type (string) |
The media type used to serialize the payloads. Supported values include |
secret (string) |
If provided, the |
insecure_ssl (string) |
Determines whether the SSL certificate of the host for |
events
Determines what events the hook is triggered for.
Default:push
active
Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
true
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/hooks \
-d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks', {
owner: 'octocat',
repo: 'hello-world',
config: {
url: 'url',
content_type: 'content_type',
secret: 'secret',
insecure_ssl: 'insecure_ssl'
}
})
Default response
Status: 201 Created
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Notes
get /repos/{owner}/{repo}/hooks/{hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Default response
Status: 200 OK
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Notes
Update a repository webhook
Note: GitHub Enterprise release 2.17 and higher no longer allows admins to install new GitHub Services, and existing services will stop working in GitHub Enterprise release 2.20 and higher. You can use the Replacing GitHub Services guide to help you update your services to webhooks.
patch /repos/{owner}/{repo}/hooks/{hook_id}
Parameters
Name | Type | In | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
Setting to |
||||||||
owner |
string | path | |||||||||
repo |
string | path | |||||||||
hook_id |
integer | path | |||||||||
config |
object | body |
Key/value pairs to provide settings for this webhook. These are defined below. |
||||||||
config object |
url (string) |
Required. The URL to which the payloads will be delivered. |
content_type (string) |
The media type used to serialize the payloads. Supported values include |
secret (string) |
If provided, the |
insecure_ssl (string) |
Determines whether the SSL certificate of the host for |
events
Determines what events the hook is triggered for. This replaces the entire array of events.
Default:push
add_events
Determines a list of events to be added to the list of events that the Hook triggers for.
remove_events
Determines a list of events to be removed from the list of events that the Hook triggers for.
active
Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
true
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/hooks/42 \
-d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42,
config: {
url: 'url',
content_type: 'content_type',
secret: 'secret',
insecure_ssl: 'insecure_ssl'
}
})
Default response
Status: 200 OK
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Notes
delete /repos/{owner}/{repo}/hooks/{hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Default Response
Status: 204 No Content
Notes
Ping a repository webhook
Note: GitHub Enterprise release 2.17 and higher no longer allows admins to install new GitHub Services, and existing services will stop working in GitHub Enterprise release 2.20 and higher. You can use the Replacing GitHub Services guide to help you update your services to webhooks.
This will trigger a ping event to be sent to the hook.
post /repos/{owner}/{repo}/hooks/{hook_id}/pings
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/hooks/42/pings
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/pings', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Default Response
Status: 204 No Content
Notes
Test the push repository webhook
Note: GitHub Enterprise release 2.17 and higher no longer allows admins to install new GitHub Services, and existing services will stop working in GitHub Enterprise release 2.20 and higher. You can use the Replacing GitHub Services guide to help you update your services to webhooks.
This will trigger the hook with the latest push to the current repository if the hook is subscribed to push
events. If the hook is not subscribed to push
events, the server will respond with 204 but no test POST will be generated.
Note: Previously /repos/:owner/:repo/hooks/:hook_id/test
post /repos/{owner}/{repo}/hooks/{hook_id}/tests
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/repos/octocat/hello-world/hooks/42/tests
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/tests', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Default Response
Status: 204 No Content
Notes
Receiving Webhooks
In order for GitHub Enterprise to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.
Webhook headers
GitHub Enterprise will send along several HTTP headers to differentiate between event types and payload identifiers. See webhook headers for details.
PubSubHubbub
GitHub can also serve as a PubSubHubbub hub for all repositories. PSHB is a simple publish/subscribe protocol that lets servers register to receive updates when a topic is updated. The updates are sent with an HTTP POST request to a callback URL. Topic URLs for a GitHub repository's pushes are in this format:
https://github.com/{owner}/{repo}/events/{event}
The event can be any available webhook event. For more information, see "Webhook events and payloads."
Response format
The default format is what existing post-receive hooks should expect: A JSON body sent as the payload
parameter in a POST. You can also specify to receive the raw JSON body with either an Accept
header, or a .json
extension.
Accept: application/json
https://github.com/{owner}/{repo}/events/push.json
Callback URLs
Callback URLs can use the http://
protocol. You can also github://
callbacks to specify a GitHub service.
Note: GitHub Enterprise release 2.17 and higher no longer allows admins to install new GitHub Services, and existing services will stop working in GitHub Enterprise release 2.20 and higher. You can use the Replacing GitHub Services guide to help you update your services to webhooks.
# Send updates to postbin.org
http://postbin.org/123
# Send updates to Campfire
github://campfire?subdomain=github&room=Commits&token=abc123
Subscribing
The GitHub PubSubHubbub endpoint is: http(s)://[hostname]/api/v3/hub
. A successful request with curl looks like:
curl -u "user" -i \
http(s)://[hostname]/api/v3/hub \
-F "hub.mode=subscribe" \
-F "hub.topic=https://github.com/{owner}/{repo}/events/push" \
-F "hub.callback=http://postbin.org/123"
PubSubHubbub requests can be sent multiple times. If the hook already exists, it will be modified according to the request.
Parameters
Name | Type | Description |
---|---|---|
hub.mode | string | Required. Either subscribe or unsubscribe . |
hub.topic | string | Required. The URI of the GitHub repository to subscribe to. The path must be in the format of /{owner}/{repo}/events/{event} . |
hub.callback | string | The URI to receive the updates to the topic. |
hub.secret | string | A shared secret key that generates a SHA1 HMAC of the outgoing body content. You can verify a push came from GitHub by comparing the raw request body with the contents of the X-Hub-Signature header. You can see the PubSubHubbub documentation for more details. |