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](https://docs.github.com/[email protected]/rest/reference/commits#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 `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`.
/repos/{owner}/{repo}/deployments- Source
github-v3-rest.json- Revision
f5f067c1e6f6- Active snapshot
85e53e3d0d65
Request
Path Parameters
- owner stringrequired
- repo stringrequired
Body Params
requiredAttempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
Short description of the deployment.
Name for the target deployment environment (e.g., `production`, `staging`, `qa`).
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`](https://docs.github.com/[email protected]/rest/overview/api-previews#enhanced-deployments) custom media type.
The ref to deploy. This can be a branch, tag, or SHA.
The [status](https://docs.github.com/[email protected]/rest/reference/commits#commit-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.
Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).
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`](https://docs.github.com/[email protected]/rest/overview/api-previews#enhanced-deployments) custom media type.
Responses
Response
Example: 2012-07-20T01:19:13Z
creator Simple User objectrequirednullable Simple User
Simple User
Example: https://github.com/images/error/octocat_happy.gif
Example: https://api.github.com/users/octocat/events{/privacy}
Example: https://api.github.com/users/octocat/followers
Example: https://api.github.com/users/octocat/following{/other_user}
Example: https://api.github.com/users/octocat/gists{/gist_id}
Example: 41d064eb2195891e12d0413f63227ea7
Example: https://github.com/octocat
Example: 1
Example: octocat
Example: MDQ6VXNlcjE=
Example: https://api.github.com/users/octocat/orgs
Example: https://api.github.com/users/octocat/received_events
Example: https://api.github.com/users/octocat/repos
Example: "2020-07-09T00:17:55Z"
Example: https://api.github.com/users/octocat/starred{/owner}{/repo}
Example: https://api.github.com/users/octocat/subscriptions
Example: User
Example: https://api.github.com/users/octocat
Example: Deploy request from hubot
Name for the target deployment environment.
Example: production
Unique identifier of the deployment
Example: 42
Example: MDEwOkRlcGxveW1lbnQx
Example: staging
performed_via_github_app GitHub app objectoptionalnullable 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.
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.
Example: "Iv1.25b5d1e65ffc4022"
Example: "1d4b2097ac622ba702d19de498f005747a8b21d3"
Example: 2017-07-08T16:18:44-04:00
Example: The description of the app.
The list of events for the GitHub app
[
"label",
"deployment"
]Example: https://example.com
Example: https://github.com/apps/super-ci
Unique identifier of the GitHub app
Example: 37
The number of installations associated with the GitHub app
Example: 5
The name of the GitHub app
Example: Probot Owners
Example: MDExOkludGVncmF0aW9uMQ==
owner Simple User objectrequirednullable Simple User
Simple User
Example: https://github.com/images/error/octocat_happy.gif
Example: https://api.github.com/users/octocat/events{/privacy}
Example: https://api.github.com/users/octocat/followers
Example: https://api.github.com/users/octocat/following{/other_user}
Example: https://api.github.com/users/octocat/gists{/gist_id}
Example: 41d064eb2195891e12d0413f63227ea7
Example: https://github.com/octocat
Example: 1
Example: octocat
Example: MDQ6VXNlcjE=
Example: https://api.github.com/users/octocat/orgs
Example: https://api.github.com/users/octocat/received_events
Example: https://api.github.com/users/octocat/repos
Example: "2020-07-09T00:17:55Z"
Example: https://api.github.com/users/octocat/starred{/owner}{/repo}
Example: https://api.github.com/users/octocat/subscriptions
Example: User
Example: https://api.github.com/users/octocat
"-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEArYxrNYD/iT5CZVpRJu4rBKmmze3PVmT/gCo2ATUvDvZTPTey\nxcGJ3vvrJXazKk06pN05TN29o98jrYz4cengG3YGsXPNEpKsIrEl8NhbnxapEnM9\nJCMRe0P5JcPsfZlX6hmiT7136GRWiGOUba2X9+HKh8QJVLG5rM007TBER9/z9mWm\nrJuNh+m5l320oBQY/Qq3A7wzdEfZw8qm/mIN0FCeoXH1L6B8xXWaAYBwhTEh6SSn\nZHlO1Xu1JWDmAvBCi0RO5aRSKM8q9QEkvvHP4yweAtK3N8+aAbZ7ovaDhyGz8r6r\nzhU1b8Uo0Z2ysf503WqzQgIajr7Fry7/kUwpgQIDAQABAoIBADwJp80Ko1xHPZDy\nfcCKBDfIuPvkmSW6KumbsLMaQv1aGdHDwwTGv3t0ixSay8CGlxMRtRDyZPib6SvQ\n6OH/lpfpbMdW2ErkksgtoIKBVrDilfrcAvrNZu7NxRNbhCSvN8q0s4ICecjbbVQh\nnueSdlA6vGXbW58BHMq68uRbHkP+k+mM9U0mDJ1HMch67wlg5GbayVRt63H7R2+r\nVxcna7B80J/lCEjIYZznawgiTvp3MSanTglqAYi+m1EcSsP14bJIB9vgaxS79kTu\noiSo93leJbBvuGo8QEiUqTwMw4tDksmkLsoqNKQ1q9P7LZ9DGcujtPy4EZsamSJT\ny8OJt0ECgYEA2lxOxJsQk2kI325JgKFjo92mQeUObIvPfSNWUIZQDTjniOI6Gv63\nGLWVFrZcvQBWjMEQraJA9xjPbblV8PtfO87MiJGLWCHFxmPz2dzoedN+2Coxom8m\nV95CLz8QUShuao6u/RYcvUaZEoYs5bHcTmy5sBK80JyEmafJPtCQVxMCgYEAy3ar\nZr3yv4xRPEPMat4rseswmuMooSaK3SKub19WFI5IAtB/e7qR1Rj9JhOGcZz+OQrl\nT78O2OFYlgOIkJPvRMrPpK5V9lslc7tz1FSh3BZMRGq5jSyD7ETSOQ0c8T2O/s7v\nbeEPbVbDe4mwvM24XByH0GnWveVxaDl51ABD65sCgYB3ZAspUkOA5egVCh8kNpnd\nSd6SnuQBE3ySRlT2WEnCwP9Ph6oPgn+oAfiPX4xbRqkL8q/k0BdHQ4h+zNwhk7+h\nWtPYRAP1Xxnc/F+jGjb+DVaIaKGU18MWPg7f+FI6nampl3Q0KvfxwX0GdNhtio8T\nTj1E+SnFwh56SRQuxSh2gwKBgHKjlIO5NtNSflsUYFM+hyQiPiqnHzddfhSG+/3o\nm5nNaSmczJesUYreH5San7/YEy2UxAugvP7aSY2MxB+iGsiJ9WD2kZzTUlDZJ7RV\nUzWsoqBR+eZfVJ2FUWWvy8TpSG6trh4dFxImNtKejCR1TREpSiTV3Zb1dmahK9GV\nrK9NAoGAbBxRLoC01xfxCTgt5BDiBcFVh4fp5yYKwavJPLzHSpuDOrrI9jDn1oKN\nonq5sDU1i391zfQvdrbX4Ova48BN+B7p63FocP/MK5tyyBoT8zQEk2+vWDOw7H/Z\nu5dTCPxTIsoIwUw1I+7yIxqJzLPFgR2gVBwY1ra/8iAqCj+zeBw=\n-----END RSA PRIVATE KEY-----\n" permissions objectrequiredThe set of permissions for the GitHub app
Example:{
"deployments": "write",
"issues": "read"
}
The set of permissions for the GitHub app
{
"deployments": "write",
"issues": "read"
}The slug name of the GitHub app
Example: probot-owners
Example: 2017-07-08T16:18:44-04:00
Example: "6fba8f2fc8a7e8f2cca5577eddd82ca7586b3b6b"
Specifies if the given environment is one that end-users directly interact with. Default: false.
Example: true
The ref to deploy. This can be a branch, tag, or sha.
Example: topic-branch
Example: https://api.github.com/repos/octocat/example
Example: a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d
Example: https://api.github.com/repos/octocat/example/deployments/1/statuses
Parameter to specify a task to execute
Example: deploy
Specifies if the given environment is will no longer exist at some point in the future. Default: false.
Example: true
Example: 2012-07-20T01:19:13Z
Example: https://api.github.com/repos/octocat/example/deployments/1
Merged branch response
Conflict when there is a merge conflict or the commit's status checks failed
Validation failed