ownerstringrequired
repostringrequired
pathstringrequired
path parameter
Create or update file contents
Creates a new file or replaces an existing file in a repository.
put
http://HOSTNAME/api/v3/repos/{owner}/{repo}/contents/{path}
Path Parameters
Body
application/json
Body
application/json
messagestringrequired
The commit message.
contentstringrequired
The new file content, using Base64 encoding.
shastring
Required if you are updating a file. The blob SHA of the file being replaced.
branchstring
The branch name. Default: the repository’s default branch (usually master)
committerobject
The person that committed the file. Default: the authenticated user.
Show Child Parameters
authorobject
The author of the file. Default: The committer or the authenticated user if you omit committer.
Show Child Parameters
Response
application/json
Response
application/json
Response
File Commit
File Commit
contentobject | nullrequired
Show Child Parameters
commitobjectrequired
Show Child Parameters
put/repos/{owner}/{repo}/contents/{path}
Path Parameters
Body
{
"message": "my commit message",
"committer": {
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"content": "bXkgbmV3IGZpbGUgY29udGVudHM="
}
application/json
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
http://HOSTNAME/api/v3/repos/{owner}/{repo}/contents/{path}
Path Parameters
ownerstringrequired
repostringrequired
pathstringrequired
path parameter
Body
application/json
Body
application/json
messagestringrequired
The commit message.
shastringrequired
The blob SHA of the file being replaced.
branchstring
The branch name. Default: the repository’s default branch (usually master)
committerobject
object containing information about the committer.
Show Child Parameters
authorobject
object containing information about the author.
Show Child Parameters
Response
application/json
Response
application/json
Response
File Commit
File Commit
contentobject | nullrequired
Show Child Parameters
commitobjectrequired
Show Child Parameters
delete/repos/{owner}/{repo}/contents/{path}
Path Parameters
Body
{
"message": "my commit message",
"committer": {
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"sha": "329688480d39049927147c162b9d2deaf885005f"
}
application/json
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
http://HOSTNAME/api/v3/repos/{owner}/{repo}/contributors
Query Parameters
anonstring
Set to 1 or true to include anonymous contributors in results.
per_pageinteger
Results per page (max 100)
Default:30
pageinteger
Page number of the results to fetch.
Default:1
Path Parameters
ownerstringrequired
repostringrequired
Response
application/json
Response
application/json
if repository contains content
Contributor
loginstring
idinteger
node_idstring
avatar_urlstring(uri)
gravatar_idstring | null
urlstring(uri)
html_urlstring(uri)
followers_urlstring(uri)
following_urlstring
gists_urlstring
starred_urlstring
subscriptions_urlstring(uri)
organizations_urlstring(uri)
repos_urlstring(uri)
events_urlstring
received_events_urlstring(uri)
typestringrequired
site_adminboolean
contributionsintegerrequired
emailstring
namestring
get/repos/{owner}/{repo}/contributors
Path Parameters
Query Parameters
application/json
List deployments
Simple filtering of deployments is available via query parameters:
get
http://HOSTNAME/api/v3/repos/{owner}/{repo}/deployments
Query Parameters
shastring
The SHA recorded at creation time.
Default:none
refstring
The name of the ref. This can be a branch, tag, or SHA.
Default:none
taskstring
The name of the task for the deployment (e.g., deploy or deploy:migrations).
Default:none
environmentstring | null
The name of the environment that was deployed to (e.g., staging or production).
Default:none
per_pageinteger
Results per page (max 100)
Default:30
pageinteger
Page number of the results to fetch.
Default:1
Path Parameters
ownerstringrequired
repostringrequired
Response
200 application/json
Response
200 application/json
Response
A request for a specific ref(branch,sha,tag) to be deployed
urlstring(uri)required
Example:https://api.github.com/repos/octocat/example/deployments/1
idintegerrequired
Unique identifier of the deployment
Example:42
node_idstringrequired
Example:MDEwOkRlcGxveW1lbnQx
shastringrequired
Example:a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d
refstringrequired
The ref to deploy. This can be a branch, tag, or sha.
Example:topic-branch
taskstringrequired
Parameter to specify a task to execute
Example:deploy
payload
One Ofrequired
Variant 1object
* Additional properties are allowed.
original_environmentstring
Example:staging
environmentstringrequired
Name for the target deployment environment.
Example:production
descriptionstring | nullrequired
Example:Deploy request from hubot
creatorobject | nullrequired
Simple User
Show Child Parameters
created_atstring(date-time)required
Example:2012-07-20T01:19:13Z
updated_atstring(date-time)required
Example:2012-07-20T01:19:13Z
statuses_urlstring(uri)required
Example:https://api.github.com/repos/octocat/example/deployments/1/statuses
repository_urlstring(uri)required
Example:https://api.github.com/repos/octocat/example
transient_environmentboolean
Specifies if the given environment is will no longer exist at some point in the future. Default: false.
Example:true
production_environmentboolean
Specifies if the given environment is one that end-users directly interact with. Default: false.
Example:true
performed_via_github_appobject | null
GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.
Show Child Parameters
get/repos/{owner}/{repo}/deployments
Path Parameters
Query Parameters
200 application/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 Enterprise Server 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
masterin 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
http://HOSTNAME/api/v3/repos/{owner}/{repo}/deployments
Path Parameters
ownerstringrequired
repostringrequired
Body
application/json
Body
application/json
refstringrequired
The ref to deploy. This can be a branch, tag, or SHA.
taskstring
Specifies a task to execute (e.g., deploy or deploy:migrations).
Default:deploy
auto_mergeboolean
Attempts to automatically merge the default branch into the requested ref, if it’s behind the default branch.
Default:true
required_contextsarray[string]
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
One OfVariant 1object
* Additional properties are allowed.
environmentstring
Name for the target deployment environment (e.g., production, staging, qa).
Default:production
descriptionstring | null
Short description of the deployment.
Default:
transient_environmentboolean
Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Default:false
production_environmentboolean
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
Note: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Response
application/json
Response
application/json
Response
Deployment
A request for a specific ref(branch,sha,tag) to be deployed
urlstring(uri)required
Example:https://api.github.com/repos/octocat/example/deployments/1
idintegerrequired
Unique identifier of the deployment
Example:42
node_idstringrequired
Example:MDEwOkRlcGxveW1lbnQx
shastringrequired
Example:a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d
refstringrequired
The ref to deploy. This can be a branch, tag, or sha.
Example:topic-branch
taskstringrequired
Parameter to specify a task to execute
Example:deploy
payload
One Ofrequired
Variant 1object
* Additional properties are allowed.
original_environmentstring
Example:staging
environmentstringrequired
Name for the target deployment environment.
Example:production
descriptionstring | nullrequired
Example:Deploy request from hubot
creatorobject | nullrequired
Simple User
Show Child Parameters
created_atstring(date-time)required
Example:2012-07-20T01:19:13Z
updated_atstring(date-time)required
Example:2012-07-20T01:19:13Z
statuses_urlstring(uri)required
Example:https://api.github.com/repos/octocat/example/deployments/1/statuses
repository_urlstring(uri)required
Example:https://api.github.com/repos/octocat/example
transient_environmentboolean
Specifies if the given environment is will no longer exist at some point in the future. Default: false.
Example:true
production_environmentboolean
Specifies if the given environment is one that end-users directly interact with. Default: false.
Example:true
performed_via_github_appobject | null
GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.
Show Child Parameters
post/repos/{owner}/{repo}/deployments
Path Parameters
Body
{
"ref": "topic-branch",
"payload": "{ \"deploy\": \"migrate\" }",
"description": "Deploy request from hubot"
}
application/json