GitHub API (unofficial showcase)
POST/repos/{owner}/{repo}/deployments

Create a deployment

Creates a deployment for a repository ref, such as a branch, tag, or commit SHA. Supply ref and configure the target environment, commit status checks, or deployment payload as needed; omitted settings use the documented defaults. A 202 response indicates that the default branch was merged into the requested ref instead of creating a deployment.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 9 body fields
ownerstringrequired
The account that owns the repository. The name is not case-sensitive.
repostringrequired
The repository name without the `.git` extension. The name is not case-sensitive.

Configuration for the deployment. ref is required; other fields control the task, environment, status checks, and deployment metadata.

refstringrequired
The ref to deploy. This can be a branch, tag, or SHA.
taskstringoptional
Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).
Default:deploy
auto_mergebooleanoptional
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
Default:true
required_contextsarray<string>optional
The [status](https://docs.github.com/rest/commits/statuses) 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.
payloadobjectoptional
Additional deployment information as a JSON object or JSON text. Defaults to an empty string when omitted.
environmentstringoptional
Name for the target deployment environment (e.g., `production`, `staging`, `qa`).
Default:production
descriptionstringoptional
Short description of the deployment.
Default:
transient_environmentbooleanoptional
Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: `false`
Default:false
production_environmentbooleanoptional
Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise.

4 status codes
201Returns the created deployment object, including its identifier, ref, environment, task, payload, creator, and timestamps.
urlstringrequired
idintegerrequired
Unique identifier of the deployment
node_idstringrequired
shastringrequired
refstringrequired
The ref to deploy. This can be a branch, tag, or sha.
taskstringrequired
Parameter to specify a task to execute
payloadobjectrequired
original_environmentstringoptional
environmentstringrequired
Name for the target deployment environment.
descriptionstringrequired
creatorobjectrequired
A GitHub user.
created_atstringrequired
updated_atstringrequired
statuses_urlstringrequired
repository_urlstringrequired
transient_environmentbooleanoptional
Specifies if the given environment is will no longer exist at some point in the future. Default: false.
production_environmentbooleanoptional
Specifies if the given environment is one that end-users directly interact with. Default: false.
performed_via_github_appobjectoptional
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.
202Returns a message indicating that the default branch was merged into the requested ref instead of creating a deployment.
messagestringoptional
409Returned when merging the default branch into the requested ref causes a conflict, or when required commit status checks have not succeeded.
422Returned when the request fails validation or the endpoint has been spammed.
messagestringrequired
documentation_urlstringrequired
errorsarray<object>optional

Error handling

A 409 is returned when merging the default branch causes a conflict or required commit status checks have not succeeded. A 422 is returned when validation fails or the endpoint has been spammed. ref is required and must identify a branch, tag, or SHA; environment defaults to production, and required_contexts defaults to all unique status contexts.