Deployments

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 an error, failure, pending, or success 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 webhooks 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.

+---------+             +--------+            +-----------+        +-------------+
| Tooling |             | GitHub |            | 3rd Party |        | Your Server |
+---------+             +--------+            +-----------+        +-------------+
     |                      |                       |                     |
     |  Create Deployment   |                       |                     |
     |--------------------->|                       |                     |
     |                      |                       |                     |
     |  Deployment Created  |                       |                     |
     |<---------------------|                       |                     |
     |                      |                       |                     |
     |                      |   Deployment Event    |                     |
     |                      |---------------------->|                     |
     |                      |                       |     SSH+Deploys     |
     |                      |                       |-------------------->|
     |                      |                       |                     |
     |                      |   Deployment Status   |                     |
     |                      |<----------------------|                     |
     |                      |                       |                     |
     |                      |                       |   Deploy Completed  |
     |                      |                       |<--------------------|
     |                      |                       |                     |
     |                      |   Deployment Status   |                     |
     |                      |<----------------------|                     |
     |                      |                       |                     |

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 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 grants targeted access to deployments and deployment statuses without granting access to repository code, while the repo scope grants permission to code as well.

List deployments

Simple filtering of deployments is available via query parameters:

GET /repos/:owner/:repo/deployments
Name Type Description
sha string The SHA that was recorded at creation time. Default: none
ref string The name of the ref. This can be a branch, tag, or SHA. Default: none
task string The name of the task for the deployment (e.g., deploy or deploy:migrations). Default: none
environment string The name of the environment that was deployed to (e.g., staging or production). Default: none

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "url": "https://api.github.com/repos/octocat/example/deployments/1",
    "id": 1,
    "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
    "ref": "master",
    "task": "deploy",
    "payload": {
      "task": "deploy:migrate"
    },
    "environment": "production",
    "description": "Deploy request from hubot",
    "creator": {
      "login": "octocat",
      "id": 1,
      "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"
  }
]

Get a single deployment

GET /repos/:owner/:repo/deployments/:deployment_id

Response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/example/deployments/1",
  "id": 1,
  "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
  "ref": "master",
  "task": "deploy",
  "payload": {
    "task": "deploy:migrate"
  },
  "environment": "production",
  "description": "Deploy request from hubot",
  "creator": {
    "login": "octocat",
    "id": 1,
    "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"
}

Deployments created by users via integrations

Note: An additional performed_via_integration object in the issue payload is currently available for developers to preview. For more information, see the related blog post.

To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.machine-man-preview

Note: If a user created a deployment via a GitHub App, the performed_via_github_app key will contain information on that GitHub App.

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Create a deployment

Deployments offer a few configurable parameters with sane 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 allows for easy tracking of which environments had deployments requested. 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.

Users with repo or repo_deployment scopes can create a deployment for a given ref:

POST /repos/:owner/:repo/deployments

Parameters

Name Type Description
ref string Required. The ref to deploy. This can be a branch, tag, or SHA.
task string Specifies a task to execute (e.g., deploy or deploy:migrations). Default: deploy
auto_merge boolean Attempts to automatically merge the default branch into the requested ref, if it is behind the default branch. Default: true
required_contexts Array The status contexts to verify against commit status checks. If this parameter is omitted, 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 JSON payload with extra information about the deployment. Default: ""
environment string Name for the target deployment environment (e.g., production, staging, qa). Default: production
description string Short description of the deployment. Default: ""
transient_environment boolean Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false This parameter requires a custom media type to be specified. Please see more in the alert below.
production_environment boolean Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise. This parameter requires a custom media type to be specified. Please see more in the alert below.

The new transient_environment and production_environment parameters are currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.ant-man-preview+json

Simple example

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

{
  "ref": "topic-branch",
  "payload": "{\"user\":\"atmos\",\"room_id\":123456}",
  "description": "Deploying my sweet branch"
}

Successful response

Status: 201 Created
Location: https://api.github.com/repos/octocat/example/deployments/1
{
  "url": "https://api.github.com/repos/octocat/example/deployments/1",
  "id": 1,
  "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
  "ref": "master",
  "task": "deploy",
  "payload": {
    "task": "deploy:migrate"
  },
  "environment": "production",
  "description": "Deploy request from hubot",
  "creator": {
    "login": "octocat",
    "id": 1,
    "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"
}

Advanced example

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

{
  "ref": "topic-branch",
  "auto_merge": false,
  "payload": "{\"user\":\"atmos\",\"room_id\":123456}",
  "description": "Deploying my sweet branch",
  "required_contexts": [
    "ci/janky",
    "security/brakeman"
  ]
}

Successful response

Status: 201 Created
Location: https://api.github.com/repos/octocat/example/deployments/1
{
  "url": "https://api.github.com/repos/octocat/example/deployments/1",
  "id": 1,
  "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
  "ref": "master",
  "task": "deploy",
  "payload": {
    "task": "deploy:migrate"
  },
  "environment": "production",
  "description": "Deploy request from hubot",
  "creator": {
    "login": "octocat",
    "id": 1,
    "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"
}

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.

Status: 409 Conflict
{
  "message": "Conflict merging master into topic-branch"
}

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.

Status: 409 Conflict
{
  "message": "Conflict: Commit status checks failed for topic-branch."
}

Update a 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.

List deployment statuses

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

GET /repos/:owner/:repo/deployments/:id/statuses

Parameters

Name Type Description
id integer Required. The deployment ID to list the statuses from.

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "url": "https://api.github.com/repos/octocat/example/deployments/42/statuses/1",
    "id": 1,
    "state": "success",
    "creator": {
      "login": "octocat",
      "id": 1,
      "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
    },
    "description": "Deployment finished successfully.",
    "target_url": "https://example.com/deployment/42/output",
    "created_at": "2012-07-20T01:19:13Z",
    "updated_at": "2012-07-20T01:19:13Z",
    "deployment_url": "https://api.github.com/repos/octocat/example/deployments/42",
    "repository_url": "https://api.github.com/repos/octocat/example"
  }
]

Get a single deployment status

This endpoint is part of the deployment and deployment status enhancement. During the preview period, the API may change without advance notice. Please see the blog post for full details.

To access the API during the Early Access period, you must provide a custom media type in the Accept header:

  application/vnd.github.ant-man-preview+json

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

GET /repos/:owner/:repo/deployments/:id/statuses/:status_id

Parameters

Name Type Description
id integer Required. The deployment ID to list the statuses from.
status_id integer Required. The deployment status ID.

Response

Status: 200 OK
{
  "url": "https://api.github.com/repos/octocat/example/deployments/42/statuses/1",
  "id": 1,
  "state": "success",
  "creator": {
    "login": "octocat",
    "id": 1,
    "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
  },
  "description": "Deployment finished successfully.",
  "target_url": "https://example.com/deployment/42/output",
  "created_at": "2012-07-20T01:19:13Z",
  "updated_at": "2012-07-20T01:19:13Z",
  "deployment_url": "https://api.github.com/repos/octocat/example/deployments/42",
  "repository_url": "https://api.github.com/repos/octocat/example"
}

Deployment statuses created by users via integrations

Note: An additional performed_via_integration object in the issue payload is currently available for developers to preview. For more information, see the related blog post.

To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.machine-man-preview

Note: If a user created a deployment status via a GitHub App, the performed_via_github_app key will contain information on that GitHub App.

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Create a deployment status

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

POST /repos/:owner/:repo/deployments/:id/statuses

Parameters

Name Type Description
state string Required. The state of the status. Can be one of error, failure, inactive, pending, or success. The inactive state requires a custom media type to be specified. Please see more in the alert below.
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: ""
log_url string This is functionally equivalent to target_url. We will continue accept target_url to support legacy uses, but we recommend modifying this to the new name to avoid confusion. Default: "" This parameter requires a custom media type to be specified. Please see more in the alert below.
description string A short description of the status. Maximum length of 140 characters. Default: ""
environment_url string Sets the URL for accessing your environment. Default: "" This parameter requires a custom media type to be specified. Please see more in the alert below.
auto_inactive boolean Adds a new inactive status to all non-transient, non-production environment deployments with the same repository and environment name as the created status's deployment. Default: true This parameter requires a custom media type to be specified. Please see more in the alert below.

The new inactive state, rename of the target_url parameter to log_url, and new environment_url and auto_inactive parameters are currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.ant-man-preview+json

Example

{
  "state": "success",
  "target_url": "https://example.com/deployment/42/output",
  "description": "Deployment finished successfully."
}

Response

Status: 201 Created
Location: https://api.github.com/repos/octocat/example/deployments/42/statuses/1
{
  "url": "https://api.github.com/repos/octocat/example/deployments/42/statuses/1",
  "id": 1,
  "state": "success",
  "creator": {
    "login": "octocat",
    "id": 1,
    "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
  },
  "description": "Deployment finished successfully.",
  "target_url": "https://example.com/deployment/42/output",
  "created_at": "2012-07-20T01:19:13Z",
  "updated_at": "2012-07-20T01:19:13Z",
  "deployment_url": "https://api.github.com/repos/octocat/example/deployments/42",
  "repository_url": "https://api.github.com/repos/octocat/example"
}