kind:change

title:Improved CI support for the Deployments API

created_at:2014-06-11

author_name:atmos

Today we're making a few minor changes to the[Deployments API preview][2]. With the introduction of[combined statuses][4] in a[recent update][3], we noticed a few inconsistencies with the API that we'd like to remedy.

We're introducing a new parameter called`required_contexts`. This parameter accepts an array of named[commit status][5] contexts that are ensured to be in a "success" state before the deployment is created. This allows you to verify that more than one system verified your code before you deploy it.

We've removed support for the`force` parameter. The force parameter existed to bypass both the auto-merge and commit status checks. The same behavior can now be accomplished by setting`auto_merge` and`required_contexts` appropriately.

We're also setting a context for all[commit statuses][5]. If a commit status is created without a context, we'll now set it to the string "default".

If you have any questions or concerns,[drop us a line][1].

[1]:https://github.com/contact?form[subject]=Deployments+API

[2]:https://developer.github.com/changes/2014-01-09-preview-the-new-deployments-api/

[3]:https://developer.github.com/changes/2014-04-10-deployment-api-preview-extension/

[4]:https://developer.github.com/changes/2014-03-27-combined-status-api/

[5]:https://developer.github.com/v3/repos/statuses/

If your repository is taking advantage of[commit statuses](/v3/repos/statuses),

the API will reject requests that do not have a successful[combined

status.](/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref) (Your

repository is not required to use commit statuses. If no commit statuses are

present, the deployment will always be created.)

The`force` parameter can be used when you really just need a deployment to go

out. In these cases, all checks are bypassed, and the deployment is created for

the ref.

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](/v3/repos/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.

Name | Type | Description

-----|------|--------------

`ref`|`string`|**Required**. The ref to deploy. This can be a branch, tag, or sha.

`force`|`boolean`| Optional parameter to bypass any ahead/behind checks or commit status checks. Default:`false`

`auto_merge`|`boolean`| Optional parameter to merge the default branch into the requested ref if it is behind the default branch. Default:`true`

`required_contexts`|`Array`| Optional array of status contexts verified against commit status checks. If this parameter is omitted from the parameters then all unique contexts will be verified before a deployment is created. To bypass checking entirely pass an empty array. Defaults to all unique contexts.

`payload`|`string` | Optional JSON payload with extra information about the deployment. Default:`""`

`environment`|`string` | Optional name for the target deployment environment (e.g., production, staging, qa). Default:`"production"`

`auto_merge`|`boolean`| Optional parameter to merge the default branch into the requested deployment branch if necessary. Default:`false`

`description`|`string` | Optional short description. Default:`""`

A simple example putting the user and room into the payload to notify back to

chat networks.

<%= json\

:ref => "topic-branch",

'https://api.github.com/repos/octocat/example/deployments/1' %>

<%= json:deployment %>

A more advanced example specifying required commit statuses and bypassing auto-merging.

<%= json\

:ref => "topic-branch",

:auto_merge => false,

:payload => "{\"user\":\"atmos\",\"room_id\":123456}",

:description => "Deploying my sweet branch",

:required_contexts =>["ci/janky", "security/brakeman"]

%>

<%= headers 201,

:Location =>

'https://api.github.com/repos/octocat/example/deployments/2' %>

<%= json:deployment %>

Once a deployment is created, it cannot be updated. Information relating to the

`state`|`string` |**Required**. The state of the status. Can be one of`pending`,`success`,`error`, or`failure`.

`target_url`|`string` | The target URL to associate with this status. This URL will be linked from the GitHub UI to allow users to easily see the 'source' of the Status.<br/>For example, if your Continuous Integration system is posting build status, you would want to provide the deep link for the build output for this specific SHA:<br/>`http://ci.example.com/user/repo/build/sha`.

`description`|`string` | A short description of the status.

`context`|`string` | A string label to differentiate this status from the status of other systems.

`context`|`string` | A string label to differentiate this status from the status of other systems. Default:`"default"`

Filters issues based on date of creation, or when they were last updated.

Filters pull requests based on the date when they were merged.

Filters issues based on the date when they were closed.

Filters issues based on the quantity of comments.

*[`user` or`repo`](https://help.github.com/articles/searching-issues#users-organizations-and-repositories)