Trigger a pipeline with a token

POST

/api/v4/projects/{id}/(ref/{ref}/)trigger/pipeline

• GitLab REST API

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.

Authorizations

• http
• oauth2

Parameters

Path Parameters

id

required

One of:

string

string

integer

integer

The ID or URL-encoded path of the project

Example

18

ref

required

string

The commit sha or name of a branch or tag

Example

develop

Request Body ^required

Media type application/json

object

token

required

The unique token of trigger or job token

string

nullable

Example

6d056f63e50fe6f8c5f8f4aa10edb7

variables

The list of variables to be injected into build

object

Example

{
  "VAR1": "value1",
  "VAR2": "value2"
}

inputs

The list of inputs to be used to create the pipeline.

object

Responses

201

Created

Media type application/json

object

id

integer format: int64

iid

integer

project_id

integer format: int64

sha

string

ref

string

status

string

source

string

created_at

string format: date-time

updated_at

string format: date-time

web_url

string

before_sha

string

tag

boolean

yaml_errors

string

user

object

id

integer format: int64

username

string

public_email

string

name

string

state

string

locked

boolean

avatar_url

string

avatar_path

string

custom_attributes

Array<object>

object

key

string

value

string

web_url

string

started_at

string format: date-time

finished_at

string format: date-time

committed_at

string format: date-time

duration

Time spent running in seconds

integer

queued_duration

Time spent enqueued in seconds

integer

coverage

number format: float

detailed_status

object

icon

string

text

string

label

string

group

string

tooltip

string

has_details

boolean

details_path

string

illustration

object

favicon

string

action

string

archived

boolean

Example

{
  "id": 1,
  "iid": 2,
  "project_id": 3,
  "sha": "0ec9e58fdfca6cdd6652c083c9edb53abc0bad52",
  "ref": "feature-branch",
  "status": "success",
  "source": "push",
  "created_at": "2015-12-24T15:51:21.880Z",
  "updated_at": "2015-12-24T17:54:31.198Z",
  "web_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61",
  "before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
  "tag": false,
  "yaml_errors": "widgets:build: needs 'widgets:test'",
  "user": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "started_at": "2015-12-24T17:54:30.733Z",
  "finished_at": "2015-12-24T17:54:31.198Z",
  "committed_at": "2015-12-24T15:51:21.880Z",
  "duration": 127,
  "queued_duration": 63,
  "coverage": 98.29,
  "detailed_status": {
    "icon": "status_success",
    "text": "passed",
    "label": "passed",
    "group": "success",
    "tooltip": "passed",
    "has_details": true,
    "details_path": "/test-group/test-project/-/pipelines/287",
    "illustration": {
      "image": "illustrations/empty-state/empty-job-not-triggered-md.svg",
      "size": "",
      "title": "This job has not been triggered yet",
      "content": "This job depends on upstream jobs that need to succeed in order for this job to be triggered"
    },
    "favicon": "/assets/ci_favicons/favicon_status_success.png"
  },
  "archived": false
}

400

Bad request

401

Unauthorized

403

Forbidden

404

Not found