---
title: "Create or update a commit pipeline status"
method: POST
path: "/api/v4/projects/{id}/statuses/{sha}"
tags: ["commit_statuses"]
---

# Create or update a commit pipeline status

`POST /api/v4/projects/{id}/statuses/{sha}`

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/projects/{id}/statuses/{sha}`
- Auth: none declared

Creates or updates the status of a commit represented by a job in an `external` stage. If the commit is associated with a merge request, target the commit in the merge request source branch.

## Path parameters

- `id` string, required
- `sha` string, required

## Request body

- PostApiV4ProjectsIdStatusesSha: Create or update a commit pipeline status
  - `state` 'pending' | 'running' | 'success' | 'failed' | 'canceled' | 'skipped', required: The state of the status
  - `ref` string: The ref
  - `target_url` string: The target URL to associate with this status
  - `description` string: A short description of the status
  - `name` string: A string label to differentiate this status from the status of other systems
  - `context` string: A string label to differentiate this status from the status of other systems
  - `coverage` number, float: The total code coverage
  - `pipeline_id` integer: An existing pipeline ID, when multiple pipelines on the same commit SHA have been triggered

## Response `200`

Create or update a commit pipeline status

- APIEntitiesCommitStatus: API_Entities_CommitStatus model
  - `id` integer, required
  - `sha` string, required
  - `ref` string, required
  - `status` string, required
  - `name` string, required
  - `target_url` string, required
  - `description` string, required
  - `created_at` string, date-time, required
  - `started_at` string, date-time, required
  - `finished_at` string, date-time, required
  - `allow_failure` boolean, required
  - `coverage` number, float, required
  - `pipeline_id` integer, required
  - `author` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Another update to this commit status is in progress

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)