Skip to content
forgit api docs

Create a deployment status

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

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.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

The account owner of the repository. The name is not case sensitive.

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

deployment_id
required
integer

Deployment_id parameter

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
state
required

The state of the status. When you set a transient deployment to inactive, the deployment will be shown as destroyed in GitHub.

string
Allowed values: error failure inactive in_progress queued pending success
target_url

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.

string
""
log_url

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

string
""
description

A short description of the status. The maximum description length is 140 characters.

string
""
environment

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.

string
environment_url

Sets the URL for accessing your environment. Default: ""

string
""
auto_inactive

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

boolean
Examples
Example default 
{
  "environment": "production",
  "state": "success",
  "log_url": "https://example.com/deployment/42/output",
  "description": "Deployment finished successfully."
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
Deployment Status

The status of a deployment.

object
url
required
string format: uri
id
required
integer format: int64
node_id
required
string
state
required

The state of the status.

string
Allowed values: error failure inactive pending success queued in_progress
creator
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
description
required

A short description of the status.

string
"" <= 140 characters
environment

The environment of the deployment that the status is for.

string
""
target_url
required

Closing down notice: the URL to associate with this status.

string format: uri
""
created_at
required
string format: date-time
updated_at
required
string format: date-time
deployment_url
required
string format: uri
repository_url
required
string format: uri
environment_url

The URL for accessing your environment.

string format: uri
""
log_url

The URL to associate with this status.

string format: uri
""
performed_via_github_app
GitHub app

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.

object
id
required

Unique identifier of the GitHub app

integer
slug

The slug name of the GitHub app

string
node_id
required
string
client_id
string
owner
required
One of:
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
name
required

The name of the GitHub app

string
description
required
string
nullable
external_url
required
string format: uri
html_url
required
string format: uri
created_at
required
string format: date-time
updated_at
required
string format: date-time
permissions
required

The set of permissions for the GitHub app

object
issues
string
checks
string
metadata
string
contents
string
deployments
string
key
additional properties
string
events
required

The list of events for the GitHub app. Note that the installation_target, security_advisory, and meta events are not included because they are global events and not specific to an installation.

Array<string>
installations_count

The number of installations associated with the GitHub app. Only returned when the integration is requesting details about itself.

integer
Examples
Example default 
{
  "url": "https://api.github.com/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://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.",
  "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://api.github.com/repos/octocat/example/deployments/42",
  "repository_url": "https://api.github.com/repos/octocat/example",
  "environment_url": "https://test-branch.lab.acme.com",
  "log_url": "https://example.com/deployment/42/output"
}

Headers

Section titled “ Headers ”
Location
string
Example 
https://api.github.com/repos/octocat/example/deployments/42/statuses/1

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error

Validation Error

object
message
required
string
documentation_url
required
string
errors
Array<object>
object
resource
string
field
string
message
string
code
required
string
index
integer
value
One of:
string
nullable
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}