- List project pipelines
- Get a single pipeline
- Create a new pipeline
- Retry jobs in a pipeline
- Cancel a pipelines jobs
- Delete a pipeline
Pipelines API
List project pipelines
Introduced in GitLab 8.11
GET /projects/:id/pipelines
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
scope
| string | no | The scope of pipelines, one of: running , pending , finished , branches , tags
|
status
| string | no | The status of pipelines, one of: running , pending , success , failed , canceled , skipped , created , manual
|
ref
| string | no | The ref of pipelines |
sha
| string | no | The SHA of pipelines |
yaml_errors
| boolean | no | Returns pipelines with invalid configurations |
name
| string | no | The name of the user who triggered pipelines |
username
| string | no | The username of the user who triggered pipelines |
updated_after
| datetime | no | Return pipelines updated after the specified date. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ |
updated_before
| datetime | no | Return pipelines updated before the specified date. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ |
order_by
| string | no | Order pipelines by id , status , ref , updated_at or user_id (default: id )
|
sort
| string | no | Sort pipelines in asc or desc order (default: desc )
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines"
Example of response
[
{
"id": 47,
"status": "pending",
"ref": "new-pipeline",
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"web_url": "https://example.com/foo/bar/pipelines/47",
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
},
{
"id": 48,
"status": "pending",
"ref": "new-pipeline",
"sha": "eb94b618fb5865b26e80fdd8ae531b7a63ad851a",
"web_url": "https://example.com/foo/bar/pipelines/48",
"created_at": "2016-08-12T10:06:04.561Z",
"updated_at": "2016-08-12T10:09:56.223Z",
}
]
Get a single pipeline
Introduced in GitLab 8.11
GET /projects/:id/pipelines/:pipeline_id
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
pipeline_id
| integer | yes | The ID of a pipeline |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"
Example of response
{
"id": 46,
"status": "success",
"ref": "master",
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://localhost:3000/root"
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
"duration": null,
"coverage": "30.0",
"web_url": "https://example.com/foo/bar/pipelines/46"
}
Get variables of a pipeline
GET /projects/:id/pipelines/:pipeline_id/variables
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
pipeline_id
| integer | yes | The ID of a pipeline |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/variables"
Example of response
[
{
"key": "RUN_NIGHTLY_BUILD",
"variable_type": "env_var",
"value": "true"
},
{
"key": "foo",
"value": "bar"
}
]
Create a new pipeline
Introduced in GitLab 8.14
POST /projects/:id/pipeline
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
ref
| string | yes | Reference to commit |
variables
| array | no | An array containing the variables available in the pipeline, matching the structure [{ 'key' => 'UPLOAD_TO_S3', 'variable_type' => 'file', 'value' => 'true' }]
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=master"
Example of response
{
"id": 61,
"sha": "384c444e840a515b23f21915ee5766b87068a70d",
"ref": "master",
"status": "pending",
"before_sha": "0000000000000000000000000000000000000000",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://localhost:3000/root"
},
"created_at": "2016-11-04T09:36:13.747Z",
"updated_at": "2016-11-04T09:36:13.977Z",
"started_at": null,
"finished_at": null,
"committed_at": null,
"duration": null,
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/61"
}
Retry jobs in a pipeline
Introduced in GitLab 8.11
POST /projects/:id/pipelines/:pipeline_id/retry
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
pipeline_id
| integer | yes | The ID of a pipeline |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/retry"
Response:
{
"id": 46,
"status": "pending",
"ref": "master",
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://localhost:3000/root"
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
"duration": null,
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/46"
}
Cancel a pipelines jobs
Introduced in GitLab 8.11
POST /projects/:id/pipelines/:pipeline_id/cancel
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
pipeline_id
| integer | yes | The ID of a pipeline |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/cancel"
Response:
{
"id": 46,
"status": "canceled",
"ref": "master",
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://localhost:3000/root"
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
"duration": null,
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/46"
}
Delete a pipeline
Introduced in GitLab 11.6.
DELETE /projects/:id/pipelines/:pipeline_id
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
pipeline_id
| integer | yes | The ID of a pipeline |
curl --header "PRIVATE-TOKEN: <your_access_token>" --request "DELETE" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc