Use this API to trigger pipelines.

Trigger a pipeline with a token

POST /api/v4/projects/{id}/ref/{ref}/trigger/pipeline

Triggers a pipeline with a token. With a CI/CD job token, the triggered pipeline is a multi-project pipeline. The job that authenticates the request becomes associated with the upstream pipeline, which is visible on the pipeline graph. If you use a trigger token in a job, the job is not associated with the upstream pipeline.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
Example: 18
ref
Path, required		StringThe commit sha or name of a branch or tag
Example: develop

Request body (application/json)

PropertyTypeDescription
inputsObjectThe list of inputs to be used to create the pipeline
token
Required		StringThe unique token of trigger or job token
Example: 6d056f63e50fe6f8c5f8f4aa10edb7
variablesObjectThe list of variables to be injected into build
Example: {"VAR1":"value1","VAR2":"value2"}

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesCiPipeline
400Bad request—
401Unauthorized—
403Forbidden—
404Not found—

Trigger a pipeline with a token

POST /api/v4/projects/{id}/trigger/pipeline

Triggers a pipeline with a token. With a CI/CD job token, the triggered pipeline is a multi-project pipeline. The job that authenticates the request becomes associated with the upstream pipeline, which is visible on the pipeline graph. If you use a trigger token in a job, the job is not associated with the upstream pipeline.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
Example: 18

Request body (application/json)

PropertyTypeDescription
inputsObjectThe list of inputs to be used to create the pipeline
token
Required		StringThe unique token of trigger or job token
Example: 6d056f63e50fe6f8c5f8f4aa10edb7
variablesObjectThe list of variables to be injected into build
Example: {"VAR1":"value1","VAR2":"value2"}

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesCiPipeline
400Bad request—
401Unauthorized—
403Forbidden—
404Not found—

List all project trigger tokens

GET /api/v4/projects/{id}/triggers

Lists all pipeline trigger tokens for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
Example: 18
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

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

Create a trigger token

POST /api/v4/projects/{id}/triggers

Creates a pipeline trigger token for a project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
Example: 18

Request body (application/json)

PropertyTypeDescription
description
Required		StringThe trigger token description
Example: my trigger token description
expires_atString (date-time)Timestamp of when the pipeline trigger token expires
Example: 2024-07-01T00:00:00.000Z

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesTrigger
400Bad request—
401Unauthorized—
403Forbidden—
404Not found—

Retrieve trigger token details

GET /api/v4/projects/{id}/triggers/{trigger_id}

Retrieves details of a pipeline trigger token for a project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
Example: 18
trigger_id
Path, required		IntegerThe trigger token ID
Example: 10

Responses

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

Update a pipeline trigger token

PUT /api/v4/projects/{id}/triggers/{trigger_id}

Updates a pipeline trigger token for a project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
Example: 18
trigger_id
Path, required		IntegerThe trigger token ID

Request body (application/json)

PropertyTypeDescription
descriptionStringThe trigger token description

Responses

CodeDescriptionSchema
200OKAPIEntitiesTrigger
400Bad request—
401Unauthorized—
403Forbidden—
404Not found—

Delete a pipeline trigger token

DELETE /api/v4/projects/{id}/triggers/{trigger_id}

Deletes a pipeline trigger token for a project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
Example: 18
trigger_id
Path, required		IntegerThe trigger token ID
Example: 10

Responses

CodeDescriptionSchema
204No Content—
400Bad Request—
401Unauthorized—
403Forbidden—
404Not found—
412Precondition Failed—

Schemas

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

APIEntitiesCiPipeline

PropertyTypeDescription
archivedBooleanExample: false
before_shaStringExample: a91957a858320c0e17f3a0eca7cfacbff50ea29a
committed_atString (date-time)Example: 2015-12-24T15:51:21.880Z
coverageNumber (float)Example: 98.29
created_atString (date-time)Example: 2015-12-24T15:51:21.880Z
detailed_statusDetailedStatusEntity—
durationIntegerTime spent running in seconds
Example: 127
finished_atString (date-time)Example: 2015-12-24T17:54:31.198Z
idInteger (int64)Example: 1
iidIntegerExample: 2
project_idInteger (int64)Example: 3
queued_durationIntegerTime spent enqueued in seconds
Example: 63
refStringExample: feature-branch
shaStringExample: 0ec9e58fdfca6cdd6652c083c9edb53abc0bad52
sourceStringExample: push
started_atString (date-time)Example: 2015-12-24T17:54:30.733Z
statusStringExample: success
tagBooleanExample: false
updated_atString (date-time)Example: 2015-12-24T17:54:31.198Z
userAPIEntitiesUserBasic—
web_urlStringExample: https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61
yaml_errorsStringExample: widgets:build: needs 'widgets:test'

APIEntitiesCustomAttribute

PropertyTypeDescription
keyStringExample: foo
valueStringExample: bar

APIEntitiesTrigger

PropertyTypeDescription
created_atString (date-time)Example: 2015-12-24T15:51:21.880Z
descriptionStringExample: test
expires_atString (date-time)Example: 2015-12-24T17:54:31.198Z
idInteger (int64)Example: 10
last_usedString (date-time)Example: 2015-12-24T17:54:31.198Z
ownerAPIEntitiesUserBasic—
tokenStringExample: 6d056f63e50fe6f8c5f8f4aa10edb7
updated_atString (date-time)Example: 2015-12-24T17:54:31.198Z

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

DetailedStatusEntity

PropertyTypeDescription
actionObject—
action.button_titleStringExample: Cancel this job
action.confirmation_messageStringExample: Are you sure?
action.iconStringExample: cancel
action.methodStringExample: post
action.pathStringExample: /namespace1/project1/-/jobs/2/cancel
action.titleStringExample: Cancel
details_pathStringExample: /test-group/test-project/-/pipelines/287
faviconStringExample: /assets/ci_favicons/favicon_status_success.png
groupStringExample: success
has_detailsBooleanExample: true
iconStringExample: status_success
illustrationObjectExample: {"content":"This job depends on upstream jobs that need to succeed in order for this job to be triggered","image":"illustrations/empty-state/empty-job-not-triggered-md.svg","size":"","title":"This job has not been triggered yet"}
labelStringExample: passed
textStringExample: passed
tooltipStringExample: passed
←
REST API / CI runners
REST API / CI variables
→