The REST API is now versioned. For more information, see "About API versioning."

REST API endpoints for deployment statuses

Use the REST API to manage deployment statuses.

About deployment statuses

Deployment statuses allow external services to mark deployments with an error, failure, inactive, in_progress, queued, pending, or success state. Systems listening to deployment_status events can consume and respond to these statuses. A deployment status can also include an optional description and log_url.

A deployment can accumulate multiple statuses over time as it progresses, for example from pending to in_progress to success. GitHub tracks the most recent status for each deployment and uses it to display the deployment's current state.

Data retention

GitHub retains records of previous deployment statuses for 90 days. Previous statuses older than 90 days are automatically deleted and are no longer returned by the REST API or GraphQL API.

This retention policy applies to all deployment status endpoints, including List deployment statuses and Get a deployment status. The current status of a deployment is not affected, because it is stored on the deployment itself and remains available regardless of the deployment's age.

List deployment statuses

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

Fine-grained access tokens for "List deployment statuses"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Deployments" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "List deployment statuses"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.
`deployment_id` integer Required deployment_id parameter

Query parameters
Name, Type, Description
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

HTTP response status codes for "List deployment statuses"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "List deployment statuses"

Request example

get/repos/{owner}/{repo}/deployments/{deployment_id}/statuses

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/deployments/DEPLOYMENT_ID/statuses

Response

Status: 200

[
  {
    "url": "https://HOSTNAME/repos/octocat/example/deployments/42/statuses/1",
    "id": 1,
    "node_id": "MDE2OkRlcGxveW1lbnRTdGF0dXMx",
    "state": "success",
    "creator": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://HOSTNAME/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://HOSTNAME/users/octocat/followers",
      "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
      "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
      "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
      "organizations_url": "https://HOSTNAME/users/octocat/orgs",
      "repos_url": "https://HOSTNAME/users/octocat/repos",
      "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
      "received_events_url": "https://HOSTNAME/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "description": "Deployment finished successfully.",
    "environment": "production",
    "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://HOSTNAME/repos/octocat/example/deployments/42",
    "repository_url": "https://HOSTNAME/repos/octocat/example",
    "environment_url": "https://test-branch.lab.acme.com",
    "log_url": "https://example.com/deployment/42/output"
  }
]

Create a deployment status

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

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

Fine-grained access tokens for "Create a deployment status"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Deployments" repository permissions (write)

Parameters for "Create a deployment status"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.
`deployment_id` integer Required deployment_id parameter

Body parameters
Name, Type, Description
`state` string Required The state of the status. When you set a transient deployment to `inactive`, the deployment will be shown as `destroyed` in GitHub. Can be one of: `error`, `failure`, `inactive`, `in_progress`, `queued`, `pending`, `success`
`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. Note It's recommended to use the `log_url` parameter, which replaces `target_url`. Default: `""`
`log_url` string The full URL of the deployment's output. This parameter replaces `target_url`. We will continue to accept `target_url` to support legacy uses, but we recommend replacing `target_url` with `log_url`. Setting `log_url` will automatically set `target_url` to the same value. Default: `""` Default: `""`
`description` string A short description of the status. The maximum description length is 140 characters. Default: `""`
`environment` string Name for the target deployment environment, which can be changed when setting a deploy status. For example, `production`, `staging`, or `qa`. If not defined, the environment of the previous status on the deployment will be used, if it exists. Otherwise, the environment of the deployment will be used.
`environment_url` string Sets the URL for accessing your environment. Default: `""` Default: `""`
`auto_inactive` boolean Adds a new `inactive` status to all prior non-transient, non-production environment deployments with the same repository and `environment` name as the created status's deployment. An `inactive` status is only added to deployments that had a `success` state. Default: `true`

HTTP response status codes for "Create a deployment status"

Status code	Description
`201`	Created
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Create a deployment status"

Request example

post/repos/{owner}/{repo}/deployments/{deployment_id}/statuses

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/deployments/DEPLOYMENT_ID/statuses \
  -d '{"environment":"production","state":"success","log_url":"https://example.com/deployment/42/output","description":"Deployment finished successfully."}'

Response

Status: 201

{
  "url": "https://HOSTNAME/repos/octocat/example/deployments/42/statuses/1",
  "id": 1,
  "node_id": "MDE2OkRlcGxveW1lbnRTdGF0dXMx",
  "state": "success",
  "creator": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://HOSTNAME/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://HOSTNAME/users/octocat/followers",
    "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
    "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
    "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
    "organizations_url": "https://HOSTNAME/users/octocat/orgs",
    "repos_url": "https://HOSTNAME/users/octocat/repos",
    "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
    "received_events_url": "https://HOSTNAME/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "description": "Deployment finished successfully.",
  "environment": "production",
  "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://HOSTNAME/repos/octocat/example/deployments/42",
  "repository_url": "https://HOSTNAME/repos/octocat/example",
  "environment_url": "https://test-branch.lab.acme.com",
  "log_url": "https://example.com/deployment/42/output"
}

Get a deployment status

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

Fine-grained access tokens for "Get a deployment status"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Deployments" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "Get a deployment status"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.
`deployment_id` integer Required deployment_id parameter
`status_id` integer Required

HTTP response status codes for "Get a deployment status"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "Get a deployment status"

Request example

get/repos/{owner}/{repo}/deployments/{deployment_id}/statuses/{status_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/deployments/DEPLOYMENT_ID/statuses/STATUS_ID

Response

Status: 200

{
  "url": "https://HOSTNAME/repos/octocat/example/deployments/42/statuses/1",
  "id": 1,
  "node_id": "MDE2OkRlcGxveW1lbnRTdGF0dXMx",
  "state": "success",
  "creator": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://HOSTNAME/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://HOSTNAME/users/octocat/followers",
    "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
    "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
    "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
    "organizations_url": "https://HOSTNAME/users/octocat/orgs",
    "repos_url": "https://HOSTNAME/users/octocat/repos",
    "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
    "received_events_url": "https://HOSTNAME/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "description": "Deployment finished successfully.",
  "environment": "production",
  "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://HOSTNAME/repos/octocat/example/deployments/42",
  "repository_url": "https://HOSTNAME/repos/octocat/example",
  "environment_url": "https://test-branch.lab.acme.com",
  "log_url": "https://example.com/deployment/42/output"
}