kind:change

title:Preview the New Deployments API

created_at:2014-01-09

author_name:atmos

Today we're excited to announce a[Deployments API][docs]. We ship a lot of

software at GitHub: web, mobile, and native. For the last few years, we've been

driving our deployments from our[ChatOps tooling][chatops] and we've learned a

lot. The Deployments API is a generalization of the approach that we've been

taking, and we're really excited to see what our users and integrations start

building around it.

Deployments are a new model in the GitHub ecosystem. We don't have any UI

components currently, and deployments are intended to be used exclusively by

tooling. If you're familiar with the Status API, you know that it allows

various tools to report on the status of a commit (e.g., the progress of an

attempt to perform a build at a particular commit). The Status API doesn't

perform the build; it just reports the results. Much like the Status API, we

won't be doing actual deployments for you. Instead, the API provides a way for

you to track the status of your deployments. We're hoping to provide

consistency across the various type of release processes, regardless of the

underlying steps involved with getting your code built or shipped to your

servers.

The system can auto-merge the default branch for the repository if the

requested deployment ref is behind the default branch. On active projects it's

easy to fall behind, so let automation watch your back.

By default, the system rejects deployment requests for repositories that have

commit statuses but don't have a green build for the deployment ref. This can

be bypassed, but is useful in cases where continuous integration is being used.

Sometimes the world crashes down on you, and you need to just get the code out

the door. Forced deployments bypass any commit status checks or ahead/behind

checks in the repository.

Different deployment systems can update the status of a deployment to be

`pending`,`success`,`failure`, or`error`. There's also a field for linking

to deployment output.

Both Deployments and Deployment Statuses trigger events on GitHub. 3rd party

integrations can listen for these events via[webhooks][hooks] and choose

whether or not to actually deploy the repository that the event was created for.

We're making this new API available today for developers to

[preview][preview-mode]. We think developers and existing integrations are

going to love it, but we want to[get your feedback][contact] before we declare

the Deployments API "final" and "unchangeable." We expect the preview period to

last for roughly 60-90 days.

As we discover opportunities to improve the API during the preview period, we

may ship changes that break clients using the preview version of the API. We

want to iterate quickly. To do so, we will announce any changes here (on the

developer blog), but we will not provide any advance notice.

At the end of preview period, the Deployments API will become an official

component of GitHub API v3. At that point, the new Deployments API will be

stable and suitable for production use.

[docs]:/v3/repos/deployments/

[hooks]:/v3/repos/hooks/

[preview-mode]:/v3/repos/deployments/#preview-mode

[chatops]:https://speakerdeck.com/jnewland/chatops

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

title:Deployments | GitHub API

* TOC

{:toc}

<divclass="alert">

<p>

</p>

<p>

</p>

</div>

Deployments are a request for a specific ref(branch,sha,tag) to be deployed.

GitHub then dispatches deployment events that external services can listen for

and act on. This enables developers and organizations to build loosely-coupled

tooling around deployments, without having to worry about implementation

details of delivering different types of applications (e.g., web, native).

Deployment Statuses allow external services to mark deployments with a

'success', 'failure', 'error', or 'pending' state, which can then be consumed

by any system listening for`deployment_status` events.

Deployment Statuses can also include an optional`description` and`target_url`, and

we highly recommend providing them as they make deployment statuses much more

useful. The`target_url` would be the full URL to the deployment output, and

the`description` would be the high level summary of what happened with the

deployment.

Deployments and Deployment Statuses both have associated repository events when

they're created. This allows web hooks and 3rd party integrations to respond to

deployment requests as well as update the status of a deployment as progress is

made.

Below is a simple sequence diagram for how these interactions would work.

<pre>

+---------+ +--------+ +-----------+ +-------------+

| Tooling | | GitHub | | 3rd Party | | Your Server |

+---------+ +--------+ +-----------+ +-------------+

| | | |

| Create Deployment | | |

|--------------------->| | |

| | | |

| Deployment Created | | |

|<---------------------| | |

| | | |

| | Deployment Event | |

| |---------------------->| |

| | | SSH+Deploys |

| | |-------------------->|

| | | |

| | Deployment Status | |

| |<----------------------| |

| | | |

| | | Deploy Completed |

| | |<--------------------|

| | | |

| | Deployment Status | |

| |<----------------------| |

| | | |

</pre>

Keep in mind that GitHub is never actually accessing your servers. It's up to

your 3rd party integration to interact with deployment events.

This allows for[github-services](https://github.com/github/github-services)

integrations as well as running your own systems depending on your use case.

Multiple systems can listen for deployment events, and it's up to each of

those systems to decide whether or not they're responsible for pushing the code

out to your servers, building native code, etc.

Note that the`repo:deployment`[OAuth scope](/v3/oauth/#scopes) grants

targeted access to Deployments and Deployment Statuses**without**

granting access to repository code, while the`repo` scope grants permission to code

as well.

Users with pull access can view deployments for a repository:

<%= headers 200,:pagination => default_pagination_rels %>

<%= json(:deployment) { |h|[h] } %>

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

the API will reject requests that do not have a success status. (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.

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.

Users with push access can create a deployment for a given ref:

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`

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

`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:`""`

<%= json\

:ref => "topic-branch",

:payload => "{\"environment\":\"production\",\"deploy_user\":\"atmos\",\"room_id\":123456}",

:description => "Deploying my sweet branch"

%>

<%= headers 201,

:Location =>

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

<%= json:deployment %>

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

success or failure of a deployment is handled through Deployment Statuses.

Users with pull access can view deployment statuses for a deployment:

Name | Type | Description

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

`id` |`integer`|**Required**. The Deployment ID to list the statuses from.

<%= headers 200,:pagination => default_pagination_rels %>

<%= json(:deployment_status) { |h|[h] } %>

Users with push access can create deployment statuses for a given deployment:

Name | Type | Description

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

`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 should contain output to keep the user updated while the task is running or serve as historical information for what happened in the deployment. Default:`""`

`description`|`string` | A short description of the status. Default:`""`

<%= json\

:state => "success",

:target_url => "https://example.com/deployment/42/output",

:description => "Deployment finished successfully."

%>

<%= headers 201,

:Location =>

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

<%= json:deployment_status %>

<%= json\

:state => "success",

:target_url=> "https://example.com/build/status",

:target_url => "https://example.com/build/status",

:description => "The build succeeded!"

%>

<li><ahref="/v3/repos/commits/">Commits</a></li>

<li><ahref="/v3/repos/contents/">Contents</a></li>

<li><ahref="/v3/repos/keys/">Deploy Keys</a></li>

<li><ahref="/v3/repos/deployments/">Deployments</a></li>

<li><ahref="/v3/repos/downloads/">Downloads</a></li>

<li><ahref="/v3/repos/forks/">Forks</a></li>

<li><ahref="/v3/repos/hooks/">Hooks</a></li>

"title":"Contents",

"section":"API/Repositories"

},

{

"url":"/v3/repos/deployments/",

"title":"Deployments",

"section":"API/Repositories"

},

{

"url":"/v3/repos/downloads/",

"title":"Downloads",