Sample - GitHub REST API
POST/repos/{owner}/{repo}/deployments

Create a deployment

Creates a deployment for a repository reference such as a branch, tag, or SHA. Supply ref and use environment, task, required_contexts, and merge settings to control how the deployment is prepared and validated. A deployment can trigger an automatic merge or return a merged-branch response when the requested reference is behind the default branch.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 parameters · 9 body fields
ownerstringrequired
The account owner of the repository; the name is not case sensitive.
repostringrequired
The repository name without the `.git` extension; the name is not case sensitive.

Deployment details. ref is required; omitted optional fields use their documented defaults.

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 represented as a JSON object or JSON text. Defaults to an empty value 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, reference, task, environment, creator, payload, status URL, repository URL, 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 when the default branch was merged into the requested reference instead of creating a deployment.
messagestringoptional
409Returned when automatic merging encounters a merge conflict or one or more required commit status checks are not successful.
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 automatic merging encounters a conflict or required commit status checks do not succeed. A 422 is returned when validation fails or the endpoint has been spammed. ref is required; environment defaults to production, task defaults to deploy, and auto_merge defaults to true when omitted.

Was this helpful?