Simple filtering of deployments is available via query parameters:
The SHA recorded at creation time.
Default:none
The name of the ref. This can be a branch, tag, or SHA.
Default:none
The name of the task for the deployment (e.g., deploy or deploy:migrations).
Default:none
The name of the environment that was deployed to (e.g., staging or production).
Default:none
Results per page (max 100)
Default:30
Page number of the results to fetch.
Default:1
Response
A request for a specific ref(branch,sha,tag) to be deployed
Example:https://api.github.com/repos/octocat/example/deployments/1
Unique identifier of the deployment
Example:42
Example:MDEwOkRlcGxveW1lbnQx
Example:a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d
The ref to deploy. This can be a branch, tag, or sha.
Example:topic-branch
Parameter to specify a task to execute
Example:deploy
One OfExample:staging
Name for the target deployment environment.
Example:production
Example:Deploy request from hubot
Simple User
Example:2012-07-20T01:19:13Z
Example:2012-07-20T01:19:13Z
Example:https://api.github.com/repos/octocat/example/deployments/1/statuses
Example:https://api.github.com/repos/octocat/example
Specifies if the given environment is will no longer exist at some point in the future. Default: false.
Example:true
Specifies if the given environment is one that end-users directly interact with. Default: false.
Example:true
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.
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.
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:
master in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful
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.
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.
The ref to deploy. This can be a branch, tag, or SHA.
Specifies a task to execute (e.g., deploy or deploy:migrations).
Default:deploy
Attempts to automatically merge the default branch into the requested ref, if it’s behind the default branch.
Default:true
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.
One OfName for the target deployment environment (e.g., production, staging, qa).
Default:production
Short description of the deployment.
Default:
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
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
A request for a specific ref(branch,sha,tag) to be deployed
Example:https://api.github.com/repos/octocat/example/deployments/1
Unique identifier of the deployment
Example:42
Example:MDEwOkRlcGxveW1lbnQx
Example:a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d
The ref to deploy. This can be a branch, tag, or sha.
Example:topic-branch
Parameter to specify a task to execute
Example:deploy
One OfExample:staging
Name for the target deployment environment.
Example:production
Example:Deploy request from hubot
Simple User
Example:2012-07-20T01:19:13Z
Example:2012-07-20T01:19:13Z
Example:https://api.github.com/repos/octocat/example/deployments/1/statuses
Example:https://api.github.com/repos/octocat/example
Specifies if the given environment is will no longer exist at some point in the future. Default: false.
Example:true
Specifies if the given environment is one that end-users directly interact with. Default: false.
Example:true
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.
deployment_id parameter
Response
A request for a specific ref(branch,sha,tag) to be deployed
Example:https://api.github.com/repos/octocat/example/deployments/1
Unique identifier of the deployment
Example:42
Example:MDEwOkRlcGxveW1lbnQx
Example:a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d
The ref to deploy. This can be a branch, tag, or sha.
Example:topic-branch
Parameter to specify a task to execute
Example:deploy
One OfExample:staging
Name for the target deployment environment.
Example:production
Example:Deploy request from hubot
Simple User
Example:2012-07-20T01:19:13Z
Example:2012-07-20T01:19:13Z
Example:https://api.github.com/repos/octocat/example/deployments/1/statuses
Example:https://api.github.com/repos/octocat/example
Specifies if the given environment is will no longer exist at some point in the future. Default: false.
Example:true
Specifies if the given environment is one that end-users directly interact with. Default: false.
Example:true
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.
If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
For more information, see “Create a deployment” and “Create a deployment status.”
deployment_id parameter
Response
Users with pull access can view deployment statuses for a deployment:
Results per page (max 100)
Default:30
Page number of the results to fetch.
Default:1
deployment_id parameter
Response
The status of a deployment.
Example:https://api.github.com/repos/octocat/example/deployments/42/statuses/1
Example:1
Example:MDE2OkRlcGxveW1lbnRTdGF0dXMx
The state of the status.
Allowed values:errorfailureinactivependingsuccessqueuedin_progress
Example:success
Simple User
A short description of the status.
Default:
<= 140 characters
Example:Deployment finished successfully.
The environment of the deployment that the status is for.
Default:
Example:production
Deprecated: the URL to associate with this status.
Default:
Example:https://example.com/deployment/42/output
Example:2012-07-20T01:19:13Z
Example:2012-07-20T01:19:13Z
Example:https://api.github.com/repos/octocat/example/deployments/42
Example:https://api.github.com/repos/octocat/example
The URL for accessing your environment.
Default:
Example:https://staging.example.com/
The URL to associate with this status.
Default:
Example:https://example.com/deployment/42/output
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.