Create a deployment

POST

/repos/{owner}/{repo}/deployments

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.

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.

OAuth app tokens and personal access tokens (classic) need the repo or repo_deployment scope to use this endpoint.

API method documentation

Parameters

Path Parameters

owner

required

string

The account owner of the repository. The name is not case sensitive.

repo

required

string

The name of the repository without the .git extension. The name is not case sensitive.

Request Body^required

application/json

object

ref

required

The ref to deploy. This can be a branch, tag, or SHA.

string

task

Specifies a task to execute (e.g., deploy or deploy:migrations).

string

default: deploy

auto_merge

Attempts to automatically merge the default branch into the requested ref, if it’s behind the default branch.

boolean

default: true

required_contexts

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.

Array<string>

payload

One of:

object
string

object

key

additional properties

any

environment

Name for the target deployment environment (e.g., production, staging, qa).

string

default: production

description

Short description of the deployment.

string

"" nullable

transient_environment

Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false

boolean

production_environment

Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.

boolean

Examples

Simple example

{
  "ref": "topic-branch",
  "payload": "{ \"deploy\": \"migrate\" }",
  "description": "Deploy request from hubot"
}

Advanced example

{
  "ref": "topic-branch",
  "auto_merge": false,
  "payload": "{ \"deploy\": \"migrate\" }",
  "description": "Deploy request from hubot",
  "required_contexts": [
    "ci/janky",
    "security/brakeman"
  ]
}

Responses

201

Response

application/json

Deployment

A request for a specific ref(branch,sha,tag) to be deployed

object

url

required

string format: uri

required

Unique identifier of the deployment

integer format: int64

node_id

required

string

sha

required

string

ref

required

The ref to deploy. This can be a branch, tag, or sha.

string

task

required

Parameter to specify a task to execute

string

payload

required

One of:

object
string

object

key

additional properties

any

original_environment

string

environment

required

Name for the target deployment environment.

string

description

required

string

nullable

creator

required

Simple User

A GitHub user.

object

name

string

nullable

email

string

nullable

login

required

string

required

integer format: int64

node_id

required

string

avatar_url

required

string format: uri

gravatar_id

required

string

nullable

url

required

string format: uri

html_url

required

string format: uri

followers_url

required

string format: uri

following_url

required

string

gists_url

required

string

starred_url

required

string

subscriptions_url

required

string format: uri

organizations_url

required

string format: uri

repos_url

required

string format: uri

events_url

required

string

received_events_url

required

string format: uri

type

required

string

site_admin

required

boolean

starred_at

string

user_view_type

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

statuses_url

required

string format: uri

repository_url

required

string format: uri

transient_environment

Specifies if the given environment is will no longer exist at some point in the future. Default: false.

boolean

production_environment

Specifies if the given environment is one that end-users directly interact with. Default: false.

boolean

performed_via_github_app

GitHub app

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.

object

required

Unique identifier of the GitHub app

integer

slug

The slug name of the GitHub app

string

node_id

required

string

client_id

string

owner

required

One of:

Simple User
Enterprise

Simple User

A GitHub user.

object

name

string

nullable

email

string

nullable

login

required

string

required

integer format: int64

node_id

required

string

avatar_url

required

string format: uri

gravatar_id

required

string

nullable

url

required

string format: uri

html_url

required

string format: uri

followers_url

required

string format: uri

following_url

required

string

gists_url

required

string

starred_url

required

string

subscriptions_url

required

string format: uri

organizations_url

required

string format: uri

repos_url

required

string format: uri

events_url

required

string

received_events_url

required

string format: uri

type

required

string

site_admin

required

boolean

starred_at

string

user_view_type

string

name

required

The name of the GitHub app

string

description

required

string

nullable

external_url

required

string format: uri

html_url

required

string format: uri

created_at

required

string format: date-time

updated_at

required

string format: date-time

permissions

required

The set of permissions for the GitHub app

object

issues

string

checks

string

metadata

string

contents

string

deployments

string

key

additional properties

string

events

required

The list of events for the GitHub app. Note that the installation_target, security_advisory, and meta events are not included because they are global events and not specific to an installation.

Array<string>

installations_count

The number of installations associated with the GitHub app. Only returned when the integration is requesting details about itself.

integer

Examples

simple-example

Simple example

{
  "url": "https://api.github.com/repos/octocat/example/deployments/1",
  "id": 1,
  "node_id": "MDEwOkRlcGxveW1lbnQx",
  "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
  "ref": "topic-branch",
  "task": "deploy",
  "payload": {},
  "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
}

202

Merged branch response

application/json

object

message

string

Examples

merged-branch-response

{
  "message": "Auto-merged master into topic-branch on deployment."
}

409

Conflict when there is a merge conflict or the commit’s status checks failed

422

Validation failed, or the endpoint has been spammed.

application/json

Validation Error

Validation Error

object

message

required

string

documentation_url

required

string

errors

Array<object>

object

resource

string

field

string

message

string

code

required

string

index

integer

value

One of:

string

nullable

Example ^generated

{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}

Create a deployment

Parameters

Path Parameters

Request Body required

Examples

Responses

201

Examples

202

Examples

409

422

Example generated

Request Body^required

Example ^generated