Pipeline trigger tokens API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

You can read more about triggering pipelines through the API.

List project trigger tokens

Get a list of a project’s pipeline trigger tokens.

Copy to clipboard
GET /projects/:id/triggers
AttributeTypeRequiredDescription
idinteger/stringYesID or URL-encoded path of the project
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
Copy to clipboard
[
    {
        "id": 10,
        "description": "my trigger",
        "created_at": "2016-01-07T09:53:58.235Z",
        "last_used": null,
        "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
        "updated_at": "2016-01-07T09:53:58.235Z",
        "owner": null
    }
]

The trigger token is displayed in full if the trigger token was created by the authenticated user. Trigger tokens created by other users are shortened to four characters.

Get trigger token details

Get details of a project’s pipeline trigger token.

Copy to clipboard
GET /projects/:id/triggers/:trigger_id
AttributeTypeRequiredDescription
idinteger/stringYesID or URL-encoded path of the project
trigger_idintegerYesThe trigger ID
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
Copy to clipboard
{
    "id": 10,
    "description": "my trigger",
    "created_at": "2016-01-07T09:53:58.235Z",
    "last_used": null,
    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
    "updated_at": "2016-01-07T09:53:58.235Z",
    "owner": null
}

Create a trigger token

Create a pipeline trigger token for a project.

Copy to clipboard
POST /projects/:id/triggers
AttributeTypeRequiredDescription
descriptionstringYesThe trigger name
idinteger/stringYesID or URL-encoded path of the project
Copy to clipboard
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers"
Copy to clipboard
{
    "id": 10,
    "description": "my trigger",
    "created_at": "2016-01-07T09:53:58.235Z",
    "last_used": null,
    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
    "updated_at": "2016-01-07T09:53:58.235Z",
    "owner": null
}

Update a pipeline trigger token

Update a project’s pipeline trigger token.

Copy to clipboard
PUT /projects/:id/triggers/:trigger_id
AttributeTypeRequiredDescription
idinteger/stringYesID or URL-encoded path of the project
trigger_idintegerYesThe trigger ID
descriptionstringNoThe trigger name
Copy to clipboard
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers/10"
Copy to clipboard
{
    "id": 10,
    "description": "my trigger",
    "created_at": "2016-01-07T09:53:58.235Z",
    "last_used": null,
    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
    "updated_at": "2016-01-07T09:53:58.235Z",
    "owner": null
}

Remove a pipeline trigger token

Remove a project’s pipeline trigger token.

Copy to clipboard
DELETE /projects/:id/triggers/:trigger_id
AttributeTypeRequiredDescription
idinteger/stringYesID or URL-encoded path of the project
trigger_idintegerYesThe trigger ID
Copy to clipboard
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5"

Trigger a pipeline with a token

Trigger a pipeline by using a pipeline trigger token or a CI/CD job token for authentication.

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.

Copy to clipboard
POST /projects/:id/trigger/pipeline

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringYesID or URL-encoded path of the project.
refstringYesThe branch or tag to run the pipeline on.
tokenstringYesThe trigger token or CI/CD job token.
variableshashNoA map of key-valued strings containing the pipeline variables. For example: { VAR1: "value1", VAR2: "value2" }.

Example request:

Copy to clipboard
curl --request POST --form "variables[VAR1]=value1" --form "variables[VAR2]=value2" "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline?token=2cb1840fb9dfc9fb0b7b1609cd29cb&ref=main"

Example response:

Copy to clipboard
{
  "id": 257,
  "iid": 118,
  "project_id": 123,
  "sha": "91e2711a93e5d9e8dddfeb6d003b636b25bf6fc9",
  "ref": "main",
  "status": "created",
  "source": "trigger",
  "created_at": "2022-03-31T01:12:49.068Z",
  "updated_at": "2022-03-31T01:12:49.068Z",
  "web_url": "http://127.0.0.1:3000/test-group/test-project/-/pipelines/257",
  "before_sha": "0000000000000000000000000000000000000000",
  "tag": false,
  "yaml_errors": null,
  "user": {
    "id": 1,
    "username": "root",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    "web_url": "http://127.0.0.1:3000/root"
  },
  "started_at": null,
  "finished_at": null,
  "committed_at": null,
  "duration": null,
  "queued_duration": null,
  "coverage": null,
  "detailed_status": {
    "icon": "status_created",
    "text": "created",
    "label": "created",
    "group": "created",
    "tooltip": "created",
    "has_details": true,
    "details_path": "/test-group/test-project/-/pipelines/257",
    "illustration": null,
    "favicon": "/assets/ci_favicons/favicon_status_created-4b975aa976d24e5a3ea7cd9a5713e6ce2cd9afd08b910415e96675de35f64955.png"
  }
}