# Create a commit status

From **GitHub v3 REST API**.

`POST /repos/{owner}/{repo}/statuses/{sha}`

Users with push access in a repository can create commit statuses for a given SHA.

Note: there is a limit of 1000 statuses per `sha` and `context` within a repository. Attempts to create more than 1000 statuses will result in a validation error.

## Parameters

### `owner`

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

### `repo`

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

### `sha`

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

## Request body

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

- Type: `object`

```json
{
  "context": "continuous-integration/jenkins",
  "description": "The build succeeded!",
  "state": "success",
  "target_url": "https://example.com/build/status"
}
```

```json
{"properties":{"context":{"default":"default","description":"A string label to differentiate this status from the status of other systems. This field is case-insensitive.","type":"string"},"description":{"description":"A short description of the status.","type":"string"},"state":{"description":"The state of the status. Can be one of `error`, `failure`, `pending`, or `success`.","enum":["error","failure","pending","success"],"type":"string"},"target_url":{"description":"The target URL to associate with this status. This URL will be linked from the GitHub UI to allow users to easily see the source of the status.  \nFor example, if your continuous integration system is posting build status, you would want to provide the deep link for the build output for this specific SHA:  \n`http://ci.example.com/user/repo/build/sha`","type":"string"}},"required":["state"],"type":"object"}
```

## Responses

### `201`

Response

#### Headers

##### `Location`

- Type: `string`

- Example: `https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e`

### `application/json`

- Type: `object`

The status of a commit.

```json
{
  "avatar_url": "https://github.com/images/error/hubot_happy.gif",
  "context": "continuous-integration/jenkins",
  "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"
  },
  "description": "Build has completed successfully",
  "id": 1,
  "node_id": "MDY6U3RhdHVzMQ==",
  "state": "success",
  "target_url": "https://ci.example.com/1000/output",
  "updated_at": "2012-07-20T01:19:13Z",
  "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e"
}
```

```json
{"description":"The status of a commit.","properties":{"avatar_url":{"nullable":true,"type":"string"},"context":{"type":"string"},"created_at":{"type":"string"},"creator":{"$ref":"#/components/schemas/nullable-simple-user"},"description":{"type":"string"},"id":{"type":"integer"},"node_id":{"type":"string"},"state":{"type":"string"},"target_url":{"type":"string"},"updated_at":{"type":"string"},"url":{"type":"string"}},"required":["url","avatar_url","id","node_id","state","description","target_url","context","created_at","updated_at","creator"],"title":"Status","type":"object"}
```

## Request examples

### cURL

```shell
curl --request POST \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/statuses/{sha} \
  --header 'content-type: application/json' \
  --data '{
  "context": "continuous-integration/jenkins",
  "description": "The build succeeded!",
  "state": "success",
  "target_url": "https://example.com/build/status"
}'
```