1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
---
stage: Verify
group: Pipeline Execution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
type: tutorial
---
# Trigger pipelines by using the API **(FREE)**
To trigger a pipeline for a specific branch or tag, you can use an API call
to the [pipeline triggers API endpoint](../../api/pipeline_triggers.md).
When authenticating with the API, you can use:
- A [trigger token](#create-a-trigger-token) to trigger a branch or tag pipeline.
- A [CI/CD job token](../jobs/ci_job_token.md) to [trigger a multi-project pipeline](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api).
## Create a trigger token
You can trigger a pipeline for a branch or tag by generating a trigger token and using it
to authenticate an API call. The token impersonates a user's project access and permissions.
Prerequisite:
- You must have at least the Maintainer role for the project.
To create a trigger token:
1. On the top bar, select **Main menu > Projects** and find your project.
1. On the left sidebar, select **Settings > CI/CD**.
1. Expand **Pipeline triggers**.
1. Enter a description and select **Add trigger**.
- You can view and copy the full token for all triggers you have created.
- You can only see the first 4 characters for tokens created by other project members.
WARNING:
It is a security risk to save tokens in plain text in public projects. Potential
attackers could use a trigger token exposed in the `.gitlab-ci.yml` file to impersonate
the user that created the token. Use [masked CI/CD variables](../variables/index.md#mask-a-cicd-variable)
to improve the security of trigger tokens.
## Trigger a pipeline
After you [create a trigger token](#create-a-trigger-token), you can use it to trigger
pipelines with a tool that can access the API, or a webhook.
### Use cURL
You can use cURL to trigger pipelines with the [pipeline triggers API endpoint](../../api/pipeline_triggers.md).
For example:
- Use a multiline cURL command:
```shell
curl --request POST \
--form token=<token> \
--form ref=<ref_name> \
"https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline"
```
- Use cURL and pass the `<token>` and `<ref_name>` in the query string:
```shell
curl --request POST \
"https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline?token=<token>&ref=<ref_name>"
```
In each example, replace:
- The URL with `https://gitlab.com` or the URL of your instance.
- `<token>` with your trigger token.
- `<ref_name>` with a branch or tag name, like `main`.
- `<project_id>` with your project ID, like `123456`. The project ID is displayed
at the top of every project's landing page.
### Use a CI/CD job
You can use a CI/CD job with a triggers token to trigger pipelines when another pipeline
runs.
For example, to trigger a pipeline on the `main` branch of `project-B` when a tag
is created in `project-A`, add the following job to project A's `.gitlab-ci.yml` file:
```yaml
trigger_pipeline:
stage: deploy
script:
- 'curl --fail --request POST --form token=$MY_TRIGGER_TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline"'
rules:
- if: $CI_COMMIT_TAG
environment: production
```
In this example:
- `1234` is the project ID for `project-B`. The project ID is displayed at the top
of every project's landing page.
- The [`rules`](../yaml/index.md#rules) cause the job to run every time a tag is added to `project-A`.
- `MY_TRIGGER_TOKEN` is a [masked CI/CD variables](../variables/index.md#mask-a-cicd-variable)
that contains the trigger token.
### Use a webhook
To trigger a pipeline from another project's webhook, use a webhook URL like the following
for push and tag events:
```plaintext
https://gitlab.example.com/api/v4/projects/<project_id>/ref/<ref_name>/trigger/pipeline?token=<token>
```
Replace:
- The URL with `https://gitlab.com` or the URL of your instance.
- `<project_id>` with your project ID, like `123456`. The project ID is displayed
at the top of the project's landing page.
- `<ref_name>` with a branch or tag name, like `main`. This value takes precedence over the `ref_name` in the webhook payload.
The payload's `ref` is the branch that fired the trigger in the source repository.
You must URL-encode the `ref_name` if it contains slashes.
- `<token>` with your trigger token.
#### Use a webhook payload
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31197) in GitLab 13.9.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321027) in GitLab 13.11.
If you trigger a pipeline by using a webhook, you can access the webhook payload with
the `TRIGGER_PAYLOAD` [predefined CI/CD variable](../variables/predefined_variables.md).
The payload is exposed as a [file-type variable](../variables/index.md#cicd-variable-types),
so you can access the data with `cat $TRIGGER_PAYLOAD` or a similar command.
### Pass CI/CD variables in the API call
You can pass any number of [CI/CD variables](../variables/index.md) in the trigger API call.
These variables have the [highest precedence](../variables/index.md#cicd-variable-precedence),
and override all variables with the same name.
The parameter is of the form `variables[key]=value`, for example:
```shell
curl --request POST \
--form token=TOKEN \
--form ref=main \
--form "variables[UPLOAD_TO_S3]=true" \
"https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline"
```
CI/CD variables in triggered pipelines display on each job's page, but only
users with the Owner and Maintainer role can view the values.
## Revoke a trigger token
To revoke a trigger token:
1. On the top bar, select **Main menu > Projects** and find your project.
1. On the left sidebar, select **Settings > CI/CD**.
1. Expand **Pipeline triggers**.
1. To the left of the trigger token you want to revoke, select **Revoke** (**{remove}**).
A revoked trigger token cannot be added back.
## Configure CI/CD jobs to run in triggered pipelines
To [configure when to run jobs](../jobs/job_control.md) in triggered pipelines:
- Use [`rules`](../yaml/index.md#rules) with the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md).
- Use [`only`/`except`](../yaml/index.md#onlyrefs--exceptrefs) keywords.
| `$CI_PIPELINE_SOURCE` value | `only`/`except` keywords | Trigger method |
|-----------------------------|--------------------------|---------------------|
| `trigger` | `triggers` | In pipelines triggered with the [pipeline triggers API](../../api/pipeline_triggers.md) by using a [trigger token](#create-a-trigger-token). |
| `pipeline` | `pipelines` | In [multi-project pipelines](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api) triggered with the [pipeline triggers API](../../api/pipeline_triggers.md) by using the [`$CI_JOB_TOKEN`](../jobs/ci_job_token.md), or by using the [`trigger`](../yaml/index.md#trigger) keyword in the CI/CD configuration file. |
Additionally, the `$CI_PIPELINE_TRIGGERED` predefined CI/CD variable is set to `true`
in pipelines triggered with a trigger token.
## See which trigger token was used
You can see which trigger caused a job to run by visiting the single job page.
A part of the trigger's token displays on the right of the page, under the job details:
In pipelines triggered with a trigger token, jobs are labeled as `triggered` in
**CI/CD > Jobs**.
## Troubleshooting
### `404 not found` when triggering a pipeline
A response of `{"message":"404 Not Found"}` when triggering a pipeline might be caused
by using a [personal access token](../../user/profile/personal_access_tokens.md)
instead of a trigger token. [Create a new trigger token](#create-a-trigger-token)
and use it instead of the personal access token.
|
