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		StringCommit SHA
Example: 18f3e63d05582537db6d183d9d557be09e1f90c8
ref
Query		StringName of the branch or tag. Defaults to the default branch
Example: develop
stage
Query		StringFilter statuses by build stage. For example, test
Example: test
name
Query		StringFilter statuses by job name
Example: bundler:audit
pipeline_id
Query		IntegerFilter statuses by pipeline ID
Example: 1234
all
Query		BooleanIf true, includes all statuses instead of only the latest
order_by
Query		StringSort results by the specified field
Allowed values: id, pipeline_id
Default: id
sort
Query		StringSort statuses in ascending or descending order. Defaults to asc
Allowed values: asc, desc
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesCommitStatus
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		StringCommit SHA
Example: 18f3e63d05582537db6d183d9d557be09e1f90c8

Request body (application/json)

PropertyTypeDescription
contextStringString label to differentiate this status from the status of other systems
Example: coverage
coverageNumberTotal code coverage
Example: 100
descriptionStringShort description of the status. Must be 255 characters or fewer
nameStringString label to differentiate this status from the status of other systems
Example: coverage
pipeline_idIntegerID of the pipeline to set the status for. Use when multiple pipelines exist for the same commit SHA
refStringBranch or tag that the status refers to. Must be 255 characters or fewer
Example: develop
state
Required		StringState of the status
Allowed values: pending, running, success, failed, canceled, skipped
Minimum length: 1
target_urlStringTarget URL to associate with this status. Must be 255 characters or fewer
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
→