Skip to content

Pipeline trigger tokens API

DETAILS: 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.

GET /projects/:id/triggers
Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
[
    {
        "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.

GET /projects/:id/triggers/:trigger_id
Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project
trigger_id integer Yes The trigger ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
{
    "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.

POST /projects/:id/triggers
Attribute Type Required Description
description string Yes The trigger name
id integer/string Yes ID or URL-encoded path of the project 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers"
{
    "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.

PUT /projects/:id/triggers/:trigger_id
Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the project
trigger_id integer Yes The trigger ID
description string No The trigger name 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
```0

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
```1

## Remove a pipeline trigger token

Remove a project's pipeline trigger token.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
```2

| Attribute    | Type           | Required | Description |
|--------------|----------------|----------|-------------|
| `id`         | integer/string | Yes      | ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `trigger_id` | integer        | Yes      | The trigger ID |

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
```3

## Trigger a pipeline with a token

Trigger a pipeline by using a [pipeline trigger token](../ci/triggers/index.md#create-a-pipeline-trigger-token)
or a [CI/CD job token](../ci/jobs/ci_job_token.md) for authentication.

With a CI/CD job token, the [triggered pipeline is a multi-project pipeline](../ci/pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api).
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.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
```4

Supported attributes:

| Attribute   | Type           | Required | Description |
|-------------|----------------|----------|-------------|
| `id`        | integer/string | Yes      | ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `ref`       | string         | Yes      | The branch or tag to run the pipeline on. |
| `token`     | string         | Yes      | The trigger token or CI/CD job token. |
| `variables` | hash           | No       | A map of key-valued strings containing the pipeline variables. For example: `{ VAR1: "value1", VAR2: "value2" }`. |

Example request:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
```5

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
```6