Use this API to list the statuses recorded against a commit, and to add or update the status that an external CI/CD job reports for a commit.

List all commit statuses

GET /api/v4/projects/{id}/repository/commits/{sha}/statuses

Lists all commit statuses for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
sha
Path, required		StringHash of the commit
Example: 18f3e63d05582537db6d183d9d557be09e1f90c8
ref
Query		StringName of the branch or tag. Default is the default branch
Example: develop
stage
Query		StringFilter statuses by build stage
Example: test
name
Query		StringFilter statuses by job name
Example: bundler:audit
pipeline_id
Query		IntegerFilter statuses by pipeline ID
Example: 1234
all
Query		BooleanInclude all statuses instead of latest only. Default is false
order_by
Query		StringValues for sorting statuses. Valid values are id and pipeline_id. Default is id
Allowed values: id, pipeline_id
Default: id
sort
Query		StringSort statuses in ascending or descending order. Valid values are asc and desc. Default is asc
Allowed values: asc, desc
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesCommitStatus
400Bad Request—
401Unauthorized—
403Forbidden—
404Not found—

Create or update a commit pipeline status

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

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.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
sha
Path, required		StringThe commit hash
Example: 18f3e63d05582537db6d183d9d557be09e1f90c8

Request body (application/json)

PropertyTypeDescription
contextStringA string label to differentiate this status from the status of other systems
Example: coverage
coverageNumberThe total code coverage
Example: 100
descriptionStringA short description of the status
nameStringA string label to differentiate this status from the status of other systems
Example: coverage
pipeline_idIntegerAn existing pipeline ID, when multiple pipelines on the same commit SHA have been triggered
refStringThe ref
Example: develop
state
Required		StringThe state of the status
Allowed values: pending, running, success, failed, canceled, skipped
Minimum length: 1
target_urlStringThe target URL to associate with this status
Example: https://gitlab.example.com/janedoe/gitlab-foss/builds/91

Responses

CodeDescriptionSchema
200OKAPIEntitiesCommitStatus
400Bad request—
401Unauthorized—
403Forbidden—
404Not found—
409Another update to this commit status is in progress—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCommitStatus

PropertyTypeDescription
allow_failureBooleanExample: false
authorAPIEntitiesUserBasic—
coverageNumber (float)Example: 98.29
created_atString (date-time)Example: 2016-01-19T09:05:50.355Z
descriptionString—
finished_atString (date-time)Example: 2016-01-21T08:40:25.832Z
idInteger (int64)Example: 93
nameStringExample: default
pipeline_idInteger (int64)Example: 101
refStringExample: develop
shaStringExample: 18f3e63d05582537db6d183d9d557be09e1f90c8
started_atString (date-time)Example: 2016-01-20T08:40:25.832Z
statusStringExample: success
target_urlStringExample: https://gitlab.example.com/janedoe/gitlab-foss/builds/91

APIEntitiesCustomAttribute

PropertyTypeDescription
keyStringExample: foo
valueStringExample: bar

APIEntitiesUserBasic

PropertyTypeDescription
avatar_pathStringExample: /user/avatar/28/The-Big-Lebowski-400-400.png
avatar_urlStringExample: https://gravatar.com/avatar/1
custom_attributesArray of APIEntitiesCustomAttribute—
idInteger (int64)Example: 1
lockedBoolean—
nameStringExample: Administrator
public_emailStringExample: john@example.com
stateStringExample: active
usernameStringExample: admin
web_urlStringExample: https://gitlab.example.com/root
←
REST API / Codeowners
REST API / Commits
→