Use this API to manage CI/CD pipelines and the jobs they run.
List pipelines triggered by the authenticated user
GET /api/v4/pipelines
Lists recently created pipelines across all projects that were triggered by the authenticated user. By default, child pipelines are not included in the results. To return child pipelines, set source to parent_pipeline. This endpoint only supports keyset pagination.
Parameters
| Name | Type | Description |
|---|---|---|
sourceQuery | String | The source of pipelines Allowed values: unknown,push,web,trigger,schedule,api,external,pipeline,chat,webide,merge_,external_,parent_,ondemand_,ondemand_,security_,container_,duo_,pipeline_,dependency_Example: push |
created_Query | String (date- | Return pipelines created before the specified datetime. Example: 2015- |
created_Query | String (date- | Return pipelines created after the specified datetime. Example: 2015- |
order_Query | String | Return pipelines ordered by created_Allowed values: created_Default: created_Example: created_ |
sortQuery | String | Return pipelines sorted in desc orderAllowed values: descDefault: descExample: desc |
cursorQuery | String | Cursor for obtaining the next set of records Example: ey |
per_Query | Integer | Number of items per page Default: 20Maximum: 100Minimum: 1Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
Create a pipeline
POST /api/v4/projects/{id}/pipeline
Creates a pipeline in the specified project.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
inputs | Object | The list of inputs to be used to create the pipeline |
refRequired | String | Reference Example: develop |
variables | Array of objects | Array of variables available in the pipeline |
variables[]. | String | The key of the variable Example: UPLOAD_ |
variables[]. | String | The value of the variable Example: true |
variables[]. | String | The type of variable, Allowed values: env_,fileDefault: env_ |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
List all project pipelines
GET /api/v4/projects/{id}/pipelines
Lists all pipelines in a project. By default, child pipelines are not included in the results. To return child pipelines, set source to parent_pipeline.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
scopeQuery | String | The scope of pipelines Allowed values: running,pending,finished,branches,tagsExample: pending |
statusQuery | String | The status of pipelines Allowed values: created,waiting_,preparing,waiting_,pending,running,success,failed,canceling,canceled,skipped,manual,scheduledExample: pending |
refQuery | String | The ref of pipelines Example: develop |
shaQuery | String | The sha of pipelines Example: a91957a858320c0e17f3 |
yaml_Query | Boolean | Returns pipelines with invalid configurations Example: false |
usernameQuery | String | The username of the user who triggered pipelines Example: root |
updated_Query | String (date- | Return pipelines updated before the specified datetime. Example: 2015- |
updated_Query | String (date- | Return pipelines updated after the specified datetime. Example: 2015- |
created_Query | String (date- | Return pipelines created before the specified datetime. Example: 2015- |
created_Query | String (date- | Return pipelines created after the specified datetime. Example: 2015- |
order_Query | String | Order pipelines Allowed values: id,status,ref,updated_,user_Default: idExample: status |
sortQuery | String | Sort pipelines Allowed values: asc,descDefault: descExample: asc |
sourceQuery | String | The source of pipelines Allowed values: unknown,push,web,trigger,schedule,api,external,pipeline,chat,webide,merge_,external_,parent_,ondemand_,ondemand_,security_,container_,duo_,pipeline_,dependency_Example: push |
nameQuery | String | Filter pipelines by name Example: Build pipeline |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not Found | — |
Retrieve the latest pipeline
GET /api/v4/projects/{id}/pipelines/latest
Retrieves the latest pipeline for the most recent commit on a specified ref in a project. If no pipeline exists for the commit, a 403 status code is returned. Use the page and per_page pagination parameters to control the pagination of results.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
refQuery | String | Branch ref of pipeline. Example: develop |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Retrieve a pipeline
GET /api/v4/projects/{id}/pipelines/{pipeline_id}
Retrieves a specified pipeline from a project. You can also get a child pipeline.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Delete a pipeline
DELETE /api/v4/projects/{id}/pipelines/{pipeline_id}
Deletes a specified pipeline for a project.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
Responses
| Code | Description | Schema |
|---|---|---|
204 | Pipeline was deleted | — |
400 | Bad Request | — |
403 | Forbidden | — |
404 | Not Found | — |
List all bridge jobs by pipeline (deprecated)
GET /api/v4/projects/{id}/pipelines/{pipeline_id}/bridges
Deprecated in GitLab 19.2. Use trigger_jobs endpoint instead.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
scopeQuery | String or array of strings | The scope of builds to show Example: ["pending", |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Cancel all jobs for a pipeline
POST /api/v4/projects/{id}/pipelines/{pipeline_id}/cancel
Cancels all jobs in a specified pipeline.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
List all jobs by pipeline
GET /api/v4/projects/{id}/pipelines/{pipeline_id}/jobs
Lists all jobs for a specified pipeline.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
include_Query | Boolean | Includes retried jobs Default: false |
scopeQuery | String or array of strings | The scope of builds to show Example: ["pending", |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Update pipeline metadata
PUT /api/v4/projects/{id}/pipelines/{pipeline_id}/metadata
Updates pipeline metadata. The metadata contains the name of the pipeline. This feature was introduced in GitLab 16.6.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
nameRequired | String | The name of the pipeline Example: Deployment to production |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Retry jobs in a pipeline
POST /api/v4/projects/{id}/pipelines/{pipeline_id}/retry
Retries failed or canceled jobs in a pipeline. If there are no failed or canceled jobs in the pipeline, calling this endpoint has no effect.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Retrieve a test report for a pipeline
GET /api/v4/projects/{id}/pipelines/{pipeline_id}/test_report
Retrieves a test report for a pipeline.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | Test |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Retrieve a test report summary for a pipeline
GET /api/v4/projects/{id}/pipelines/{pipeline_id}/test_report_summary
Retrieves a test report summary for a pipeline.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | Test |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
List all trigger jobs by pipeline
GET /api/v4/projects/{id}/pipelines/{pipeline_id}/trigger_jobs
Lists all trigger jobs for a specified pipeline.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
scopeQuery | String or array of strings | The scope of builds to show Example: ["pending", |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
List all pipeline variables
GET /api/v4/projects/{id}/pipelines/{pipeline_id}/variables
Lists all pipeline variables for a specified pipeline. Use the page and per_page pagination parameters to control the pagination of results.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | The project ID or URL- Example: 11 |
pipeline_Path, | Integer | The pipeline ID Example: 18 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesCiBridge
| Property | Type | Description |
|---|---|---|
allow_ | Boolean | — |
commit | APIEntities | — |
coverage | Number (float) | Example:98. |
created_ | String (date- | Example:2015- |
downstream_ | APIEntities | — |
duration | Number (float) | Time spent running Example: 0. |
erased_ | String (date- | Example:2015- |
failure_ | String | Example:script_ |
finished_ | String (date- | Example:2015- |
id | Integer (int64) | Example:1 |
name | String | Example:deploy_ |
pipeline | APIEntities | — |
project | Object | — |
project. | String | Example:false |
queued_ | Number (float) | Time spent enqueued Example: 0. |
ref | String | Example:main |
stage | String | Example:deploy |
started_ | String (date- | Example:2015- |
status | String | Example:waiting_ |
tag | Boolean | — |
user | APIEntities | — |
web_ | String | Example:https: |
APIEntitiesCiJob
| Property | Type | Description |
|---|---|---|
allow_ | Boolean | — |
archived | Boolean | Example:false |
artifacts | Array of APIEntities | — |
artifacts_ | String (date- | Example:2016- |
artifacts_ | APIEntities | — |
commit | APIEntities | — |
coverage | Number (float) | Example:98. |
created_ | String (date- | Example:2015- |
duration | Number (float) | Time spent running Example: 0. |
erased_ | String (date- | Example:2015- |
failure_ | String | Example:script_ |
finished_ | String (date- | Example:2015- |
id | Integer (int64) | Example:1 |
name | String | Example:deploy_ |
pipeline | APIEntities | — |
project | Object | — |
project. | String | Example:false |
queued_ | Number (float) | Time spent enqueued Example: 0. |
ref | String | Example:main |
runner | APIEntities | — |
runner_ | APIEntities | — |
stage | String | Example:deploy |
started_ | String (date- | Example:2015- |
status | String | Example:waiting_ |
tag | Boolean | — |
tag_ | Array of strings | Example:["ubuntu18", |
user | APIEntities | — |
web_ | String | Example:https: |
APIEntitiesCiJobArtifact
| Property | Type | Description |
|---|---|---|
file_ | String | Allowed values:raw,zip,gzipExample: zip |
file_ | String | Allowed values:archive,metadata,trace,junit,sast,dependency_,container_,dast,codequality,license_,performance,metrics,metrics_,network_,lsif,dotenv,cobertura,terraform,accessibility,cluster_,secret_,requirements,coverage_,browser_,load_,api_,cluster_,cyclonedx,requirements_,annotations,repository_,jacoco,sarifExample: archive |
filename | String | Example:artifacts. |
size | Integer | Example:1000 |
APIEntitiesCiJobArtifactFile
| Property | Type | Description |
|---|---|---|
filename | String | Example:artifacts. |
size | Integer | Example:1000 |
APIEntitiesCiPipeline
| Property | Type | Description |
|---|---|---|
archived | Boolean | Example:false |
before_ | String | Example:a91957a858320c0e17f3 |
committed_ | String (date- | Example:2015- |
coverage | Number (float) | Example:98. |
created_ | String (date- | Example:2015- |
detailed_ | Detailed | — |
duration | Integer | Time spent running in seconds Example: 127 |
finished_ | String (date- | Example:2015- |
id | Integer (int64) | Example:1 |
iid | Integer | Example:2 |
project_ | Integer (int64) | Example:3 |
queued_ | Integer | Time spent enqueued in seconds Example: 63 |
ref | String | Example:feature- |
sha | String | Example:0ec9e58fdfca6cdd6652 |
source | String | Example:push |
started_ | String (date- | Example:2015- |
status | String | Example:success |
tag | Boolean | Example:false |
updated_ | String (date- | Example:2015- |
user | APIEntities | — |
web_ | String | Example:https: |
yaml_ | String | Example:widgets: |
APIEntitiesCiPipelineBasic
| Property | Type | Description |
|---|---|---|
created_ | String (date- | Example:2022- |
id | Integer (int64) | Example:1 |
iid | Integer | Example:2 |
project_ | Integer (int64) | Example:3 |
ref | String | Example:feature- |
sha | String | Example:0ec9e58fdfca6cdd6652 |
source | String | Example:push |
status | String | Example:success |
updated_ | String (date- | Example:2022- |
web_ | String | Example:https: |
APIEntitiesCiPipelineMergeRequest
| Property | Type | Description |
|---|---|---|
iid | Integer | Example:14 |
title | String | Example:Add rate limiting to the public API |
web_ | String | Example:https: |
APIEntitiesCiPipelineWithMetadata
| Property | Type | Description |
|---|---|---|
archived | Boolean | Example:false |
before_ | String | Example:a91957a858320c0e17f3 |
committed_ | String (date- | Example:2015- |
coverage | Number (float) | Example:98. |
created_ | String (date- | Example:2015- |
detailed_ | Detailed | — |
duration | Integer | Time spent running in seconds Example: 127 |
finished_ | String (date- | Example:2015- |
id | Integer (int64) | Example:1 |
iid | Integer | Example:2 |
name | String | Example:Build pipeline |
project_ | Integer (int64) | Example:3 |
queued_ | Integer | Time spent enqueued in seconds Example: 63 |
ref | String | Example:feature- |
sha | String | Example:0ec9e58fdfca6cdd6652 |
source | String | Example:push |
started_ | String (date- | Example:2015- |
status | String | Example:success |
tag | Boolean | Example:false |
updated_ | String (date- | Example:2015- |
user | APIEntities | — |
web_ | String | Example:https: |
yaml_ | String | Example:widgets: |
APIEntitiesCiRunner
| Property | Type | Description |
|---|---|---|
active | Boolean | Example:true |
created_ | String (date- | Example:2025- |
created_ | APIEntities | — |
description | String | Example:test- |
id | Integer (int64) | Example:8 |
ip_ | String | Example:127. |
is_ | Boolean | Example:true |
job_ | String | Allowed values:active,idleExample: idle |
name | String | Example:test |
online | Boolean | Example:true |
paused | Boolean | Example:false |
runner_ | String | Allowed values:instance_,group_,project_Example: instance_ |
status | String | Example:online |
APIEntitiesCiRunnerManager
| Property | Type | Description |
|---|---|---|
architecture | String | Example:amd64 |
contacted_ | String | Example:2023- |
created_ | String | Example:2023- |
id | Integer (int64) | Example:8 |
ip_ | String | Example:127. |
job_ | String | Allowed values:active,idleExample: idle |
platform | String | Example:linux |
revision | String | Example:91a27b2a |
status | String | Example:online |
system_ | String | Example:runner- |
version | String | Example:16. |
APIEntitiesCiUserPipeline
| Property | Type | Description |
|---|---|---|
created_ | String (date- | Example:2022- |
detailed_ | Detailed | — |
duration | Integer | Time spent running in seconds Example: 127 |
finished_ | String (date- | Example:2022- |
id | Integer (int64) | Example:1 |
iid | Integer | Example:2 |
merge_ | APIEntities | — |
name | String | Example:Build pipeline |
project | APIEntities | — |
project_ | Integer (int64) | Example:3 |
queued_ | Integer | Time spent queued in seconds Example: 63 |
ref | String | Example:feature- |
sha | String | Example:0ec9e58fdfca6cdd6652 |
source | String | Example:push |
started_ | String (date- | Example:2022- |
status | String | Example:success |
updated_ | String (date- | Example:2022- |
web_ | String | Example:https: |
APIEntitiesCiVariable
| Property | Type | Description |
|---|---|---|
description | String | Example:This variable is being used for . |
environment_ | String | Example:* |
hidden | Boolean | — |
key | String | Example:TEST_ |
masked | Boolean | — |
protected | Boolean | — |
raw | Boolean | — |
value | String | Example:TEST_ |
variable_ | String | Example:env_ |
APIEntitiesCommit
| Property | Type | Description |
|---|---|---|
author_ | String | Example:john@example. |
author_ | String | Example:John Smith |
authored_ | String (date- | Example:2012- |
committed_ | String (date- | Example:2012- |
committer_ | String | Example:jack@example. |
committer_ | String | Example:Jack Smith |
created_ | String (date- | Example:2017- |
extended_ | Object | Example:{"Signed- |
id | String | Example:2695effb5807a22ff3d1 |
message | String | Example:Initial commit |
parent_ | Array of strings | Example:["2a4b78934375d7f53875 |
short_ | String | Example:2695effb |
title | String | Example:Initial commit |
trailers | Object | Example:{"Merged- |
web_ | String | Example:https: |
APIEntitiesCustomAttribute
| Property | Type | Description |
|---|---|---|
key | String | Example:foo |
value | String | Example:bar |
APIEntitiesProjectIdentity
| Property | Type | Description |
|---|---|---|
created_ | String (date- | Example:2020- |
description | String | Example:desc |
id | Integer (int64) | Example:1 |
name | String | Example:project1 |
name_ | String | Example:John Doe / |
path | String | Example:project1 |
path_ | String | Example:namespace1/ |
APIEntitiesUser
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:/ |
avatar_ | String | Example:https: |
bio | String | — |
bot | Boolean | — |
created_ | String | — |
custom_ | Array of APIEntities | — |
discord | String | — |
followers | String | — |
following | String | — |
github | String | — |
id | Integer (int64) | Example:1 |
is_ | String | — |
job_ | String | — |
linkedin | String | — |
local_ | String | — |
location | String | — |
locked | Boolean | — |
name | String | Example:Administrator |
organization | String | — |
pronouns | String | — |
public_ | String | Example:john@example. |
state | String | Example:active |
twitter | String | — |
username | String | Example:admin |
web_ | String | Example:https: |
website_ | String | — |
work_ | String | — |
APIEntitiesUserBasic
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:/ |
avatar_ | String | Example:https: |
custom_ | Array of APIEntities | — |
id | Integer (int64) | Example:1 |
locked | Boolean | — |
name | String | Example:Administrator |
public_ | String | Example:john@example. |
state | String | Example:active |
username | String | Example:admin |
web_ | String | Example:https: |
DetailedStatusEntity
| Property | Type | Description |
|---|---|---|
action | Object | — |
action. | String | Example:Cancel this job |
action. | String | Example:Are you sure? |
action. | String | Example:cancel |
action. | String | Example:post |
action. | String | Example:/ |
action. | String | Example:Cancel |
details_ | String | Example:/ |
favicon | String | Example:/ |
group | String | Example:success |
has_ | Boolean | Example:true |
icon | String | Example:status_ |
illustration | Object | Example:{"content": |
label | String | Example:passed |
text | String | Example:passed |
tooltip | String | Example:passed |
TestCaseEntity
| Property | Type | Description |
|---|---|---|
attachment_ | String | Example:http: |
classname | String | Example:vulnerability_ |
execution_ | Integer | Example:180 |
file | String | Example:. |
name | String | Default:(No name)Example: Security Reports can create an auto- |
recent_ | Object | Example:{"base_ |
severity | String | Example:low |
stack_ | String | Example:Failure/ |
status | String | Example:success |
system_ | String | Example:Failure/ |
TestReportEntity
| Property | Type | Description |
|---|---|---|
error_ | Integer | Example:0 |
failed_ | Integer | Example:0 |
skipped_ | Integer | Example:0 |
success_ | Integer | Example:1 |
test_ | Array of Test | — |
total_ | Integer | Example:1 |
total_ | Integer | Example:180 |
TestReportSummaryEntity
| Property | Type | Description |
|---|---|---|
test_ | Test | — |
total | Object | Example:{"count": |
TestSuiteEntity
| Property | Type | Description |
|---|---|---|
error_ | Integer | Example:0 |
failed_ | Integer | Example:0 |
name | String | Example:test |
skipped_ | Integer | Example:12 |
success_ | Integer | Example:3351 |
suite_ | String | Example:JUnit XML parsing failed: |
test_ | Array of Test | — |
total_ | Integer | Example:3363 |
total_ | Integer | Example:1904 |
TestSuiteSummaryEntity
| Property | Type | Description |
|---|---|---|
build_ | Array of integers | Example:[66004] |
error_ | Integer | Example:0 |
failed_ | Integer | Example:0 |
name | String | Example:test |
severity_ | Object | Example:{"critical": |
skipped_ | Integer | Example:12 |
success_ | Integer | Example:3351 |
suite_ | String | Example:JUnit XML parsing failed: |
test_ | Array of Test | — |
total_ | Integer | Example:3363 |
total_ | Integer | Example:1904 |