# Create a deployment status

From **GitHub v3 REST API**.

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

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

GitHub Apps require `read & write` access to "Deployments" and `read-only` access to "Repo contents" (for private repos). OAuth Apps require the `repo_deployment` scope.

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

### `deployment_id`

- Location: path
- Required: true
- Type: `integer`

deployment_id parameter

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{
  "description": "Deployment finished successfully.",
  "environment": "production",
  "log_url": "https://example.com/deployment/42/output",
  "state": "success"
}
```

```json
{"properties":{"auto_inactive":{"description":"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` \n**Note:** This parameter requires you to use the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/enterprise-server@3.0/rest/overview/api-previews#enhanced-deployments) custom media type.","type":"boolean"},"description":{"default":"","description":"A short description of the status. The maximum description length is 140 characters.","type":"string"},"environment":{"description":"Name for the target deployment environment, which can be changed when setting a deploy status. For example, `production`, `staging`, or `qa`.","enum":["production","staging","qa"],"type":"string"},"environment_url":{"default":"","description":"Sets the URL for accessing your environment. Default: `\"\"`  \n**Note:** This parameter requires you to use the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/enterprise-server@3.0/rest/overview/api-previews#enhanced-deployments) custom media type.","type":"string"},"log_url":{"default":"","description":"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: `\"\"`  \n**Note:** This parameter requires you to use the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/enterprise-server@3.0/rest/overview/api-previews#enhanced-deployments) custom media type.","type":"string"},"state":{"description":"The state of the status. Can be one of `error`, `failure`, `inactive`, `in_progress`, `queued`, `pending`, or `success`. **Note:** To use the `inactive` state, you must provide the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/enterprise-server@3.0/rest/overview/api-previews#enhanced-deployments) custom media type. When you set a transient deployment to `inactive`, the deployment will be shown as `destroyed` in GitHub.","enum":["error","failure","inactive","in_progress","queued","pending","success"],"type":"string"},"target_url":{"default":"","description":"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`.","type":"string"}},"required":["state"],"type":"object"}
```

## Responses

### `201`

Response

#### Headers

##### `Location`

- Type: `string`

- Example: `https://api.github.com/repos/octocat/example/deployments/42/statuses/1`

### `application/json`

- Type: `object`

The status of a deployment.

```json
{
  "created_at": "2012-07-20T01:19:13Z",
  "creator": {
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "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}",
    "gravatar_id": "",
    "html_url": "https://github.com/octocat",
    "id": 1,
    "login": "octocat",
    "node_id": "MDQ6VXNlcjE=",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "site_admin": false,
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "type": "User",
    "url": "https://api.github.com/users/octocat"
  },
  "deployment_url": "https://api.github.com/repos/octocat/example/deployments/42",
  "description": "Deployment finished successfully.",
  "environment": "production",
  "environment_url": "https://test-branch.lab.acme.com",
  "id": 1,
  "log_url": "https://example.com/deployment/42/output",
  "node_id": "MDE2OkRlcGxveW1lbnRTdGF0dXMx",
  "repository_url": "https://api.github.com/repos/octocat/example",
  "state": "success",
  "target_url": "https://example.com/deployment/42/output",
  "updated_at": "2012-07-20T01:19:13Z",
  "url": "https://api.github.com/repos/octocat/example/deployments/42/statuses/1"
}
```

```json
{"description":"The status of a deployment.","properties":{"created_at":{"example":"2012-07-20T01:19:13Z","format":"date-time","type":"string"},"creator":{"$ref":"#/components/schemas/nullable-simple-user"},"deployment_url":{"example":"https://api.github.com/repos/octocat/example/deployments/42","format":"uri","type":"string"},"description":{"default":"","description":"A short description of the status.","example":"Deployment finished successfully.","maxLength":140,"type":"string"},"environment":{"default":"","description":"The environment of the deployment that the status is for.","example":"production","type":"string"},"environment_url":{"default":"","description":"The URL for accessing your environment.","example":"https://staging.example.com/","format":"uri","type":"string"},"id":{"example":1,"type":"integer"},"log_url":{"default":"","description":"The URL to associate with this status.","example":"https://example.com/deployment/42/output","format":"uri","type":"string"},"node_id":{"example":"MDE2OkRlcGxveW1lbnRTdGF0dXMx","type":"string"},"performed_via_github_app":{"$ref":"#/components/schemas/nullable-integration"},"repository_url":{"example":"https://api.github.com/repos/octocat/example","format":"uri","type":"string"},"state":{"description":"The state of the status.","enum":["error","failure","inactive","pending","success","queued","in_progress"],"example":"success","type":"string"},"target_url":{"default":"","description":"Deprecated: the URL to associate with this status.","example":"https://example.com/deployment/42/output","format":"uri","type":"string"},"updated_at":{"example":"2012-07-20T01:19:13Z","format":"date-time","type":"string"},"url":{"example":"https://api.github.com/repos/octocat/example/deployments/42/statuses/1","format":"uri","type":"string"}},"required":["id","node_id","state","creator","description","deployment_url","target_url","repository_url","url","created_at","updated_at"],"title":"Deployment Status","type":"object"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

```shell
curl --request POST \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/deployments/{deployment_id}/statuses \
  --header 'content-type: application/json' \
  --data '{
  "description": "Deployment finished successfully.",
  "environment": "production",
  "log_url": "https://example.com/deployment/42/output",
  "state": "success"
}'
```