README.md 10.4 KB
Newer Older
Marcia Ramos's avatar
Marcia Ramos committed
1
---
2 3 4
stage: Verify
group: Continuous Integration
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/#designated-technical-writers
Marcia Ramos's avatar
Marcia Ramos committed
5 6 7
type: tutorial
---

8
# Triggering pipelines through the API
9

10
> **Notes**:
11
>
Marcel Amirault's avatar
Marcel Amirault committed
12
> - [Introduced](https://about.gitlab.com/releases/2015/08/22/gitlab-7-14-released/) in GitLab 7.14.
13
> - GitLab 8.12 has a completely redesigned job permissions system. Read all
14
>   about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#pipeline-triggers).
15

16 17
Triggers can be used to force a pipeline rerun of a specific `ref` (branch or
tag) with an API call.
18

19 20
## Authentication tokens

21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
The following methods of authentication are supported:

- [Trigger token](#trigger-token)
- [CI job token](#ci-job-token)

If using the `$CI_PIPELINE_SOURCE` [predefined environment variable](../variables/predefined_variables.md#variables-reference)
to limit which jobs run in a pipeline, the value could be either `pipeline` or `trigger`,
depending on which trigger method is used.

| `$CI_PIPELINE_SOURCE` value | Trigger method |
|-----------------------------|----------------|
| `pipeline`                  | Using the `trigger:` keyword in the CI/CD configuration file, or using the trigger API with `$CI_JOB_TOKEN`. |
| `trigger`                   | Using the trigger API using a generated trigger token |

This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/README.md#onlyexcept-basic).
36 37 38 39 40

### Trigger token

A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger).

41 42 43
DANGER: **Danger:**
Passing plain text tokens in public projects is a security issue. Potential
attackers can impersonate the user that exposed their trigger token publicly in
44
their `.gitlab-ci.yml` file. Use [variables](../variables/README.md#gitlab-cicd-environment-variables)
45 46
to protect trigger tokens.

47 48
### CI job token

49 50
You can use the `CI_JOB_TOKEN` [variable](../variables/README.md#predefined-environment-variables) (used to authenticate
with the [GitLab Container Registry](../../user/packages/container_registry/index.md)) in the following cases.
51

52
#### When used with multi-project pipelines
53

54
> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2017) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3.
55
> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [made available](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) in all tiers in GitLab 12.4.
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72

This way of triggering can only be used when invoked inside `.gitlab-ci.yml`,
and it creates a dependent pipeline relation visible on the
[pipeline graph](../multi_project_pipelines.md#overview). For example:

```yaml
build_docs:
  stage: deploy
  script:
  - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
  only:
  - tags
```

Pipelines triggered that way also expose a special variable:
`CI_PIPELINE_SOURCE=pipeline`.

73
Read more about the [pipelines trigger API](../../api/pipeline_triggers.md).
74

75
#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)**
76

77
> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5.
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97

With the introduction of dependencies between different projects, one of
them may need to access artifacts created by a previous one. This process
must be granted for authorized accesses, and it can be done using the
`CI_JOB_TOKEN` variable that identifies a specific job. For example:

```yaml
build_submodule:
  image: debian
  stage: test
  script:
  - apt update && apt install -y unzip
  - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN"
  - unzip artifacts.zip
  only:
  - tags
```

This allows you to use that for multi-project pipelines and download artifacts
from any project to which you have access as this follows the same principles
98
with the [permission model](../../user/permissions.md#job-permissions).
99 100 101

Read more about the [jobs API](../../api/jobs.md#download-the-artifacts-archive).

102
## Adding a new trigger
103

104
You can add a new trigger by going to your project's
105
**Settings ➔ CI/CD** under **Triggers**. The **Add trigger** button will
106 107
create a new token which you can then use to trigger a rerun of this
particular project's pipeline.
108 109 110 111 112 113 114

Every new trigger you create, gets assigned a different token which you can
then use inside your scripts or `.gitlab-ci.yml`. You also have a nice
overview of the time the triggers were last used.

![Triggers page overview](img/triggers_page.png)

115
## Revoking a trigger
116 117

You can revoke a trigger any time by going at your project's
118
**Settings ➔ CI/CD** under **Triggers** and hitting the **Revoke** button.
119
The action is irreversible.
120

121
## Triggering a pipeline
122

123
> **Notes**:
124 125 126
>
> - Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
>   it will not trigger a job.
127

128
To trigger a job you need to send a `POST` request to GitLab's API endpoint:
129

130
```plaintext
131
POST /projects/:id/trigger/pipeline
132 133
```

134 135 136
The required parameters are the [trigger's `token`](#authentication-tokens)
and the Git `ref` on which the trigger will be performed. Valid refs are the
branch and the tag. The `:id` of a project can be found by
137
[querying the API](../../api/projects.md) or by visiting the **CI/CD**
138
settings page which provides self-explanatory examples.
139

140 141
When a rerun of a pipeline is triggered, the information is exposed in GitLab's
UI under the **Jobs** page and the jobs are marked as triggered 'by API'.
142

143
![Marked rebuilds as on jobs page](img/builds_page.png)
144 145 146

---

147 148
You can see which trigger caused the rebuild by visiting the single job page.
A part of the trigger's token is exposed in the UI as you can see from the image
149 150
below.

151
![Marked rebuilds as triggered on a single job page](img/trigger_single_build.png)
152 153 154

---

155
By using cURL you can trigger a pipeline rerun with minimal effort, for example:
156

157
```shell
158 159 160
curl --request POST \
     --form token=TOKEN \
     --form ref=master \
161
     https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
162 163 164 165
```

In this case, the project with ID `9` will get rebuilt on `master` branch.

166 167
Alternatively, you can pass the `token` and `ref` arguments in the query string:

168
```shell
169
curl --request POST \
170
    "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=master"
171
```
172 173 174 175

You can also benefit by using triggers in your `.gitlab-ci.yml`. Let's say that
you have two projects, A and B, and you want to trigger a rebuild on the `master`
branch of project B whenever a tag on project A is created. This is the job you
Spell Bot's avatar
Spell Bot committed
176
need to add in project A's `.gitlab-ci.yml`:
177 178 179 180 181

```yaml
build_docs:
  stage: deploy
  script:
182
  - "curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
183 184 185
  only:
  - tags
```
186

Evan Read's avatar
Evan Read committed
187
This means that whenever a new tag is pushed on project A, the job will run and the
188 189 190 191
`build_docs` job will be executed, triggering a rebuild of project B. The
`stage: deploy` ensures that this job will run only after all jobs with
`stage: test` complete successfully.

192
## Triggering a pipeline from a webhook
193

194
> **Notes**:
195 196 197 198 199 200
>
> - Introduced in GitLab 8.14.
> - `ref` should be passed as part of the URL in order to take precedence over
>   `ref` from the webhook body that designates the branch ref that fired the
>   trigger in the source repository.
> - `ref` should be URL-encoded if it contains slashes.
201

202 203 204
To trigger a job from a webhook of another project you need to add the following
webhook URL for Push and Tag events (change the project ID, ref and token):

205
```plaintext
206 207 208 209 210 211
https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN
```

## Making use of trigger variables

You can pass any number of arbitrary variables in the trigger API call and they
Marcel Amirault's avatar
Marcel Amirault committed
212
will be available in GitLab CI/CD so that they can be used in your `.gitlab-ci.yml`
213 214
file. The parameter is of the form:

215
```plaintext
216 217 218
variables[key]=value
```

219
This information is also exposed in the UI. Please note that _values_ are only viewable by Owners and Maintainers.
220 221 222 223

![Job variables in UI](img/trigger_variables.png)

Using trigger variables can be proven useful for a variety of reasons:
224

225
- Identifiable jobs. Since the variable is exposed in the UI you can know
226 227
  why the rebuild was triggered if you pass a variable that explains the
  purpose.
228
- Conditional job processing. You can have conditional jobs that run whenever
229 230 231 232 233 234 235 236 237 238 239 240 241 242
  a certain variable is present.

Consider the following `.gitlab-ci.yml` where we set three
[stages](../yaml/README.md#stages) and the `upload_package` job is run only
when all jobs from the test and build stages pass. When the `UPLOAD_TO_S3`
variable is non-zero, `make upload` is run.

```yaml
stages:
- test
- build
- package

run_tests:
Scott Edlund's avatar
Scott Edlund committed
243
  stage: test
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
  script:
  - make test

build_package:
  stage: build
  script:
  - make build

upload_package:
  stage: package
  script:
  - if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi
```

You can then trigger a rebuild while you pass the `UPLOAD_TO_S3` variable
and the script of the `upload_package` job will run:

261
```shell
262 263 264 265
curl --request POST \
  --form token=TOKEN \
  --form ref=master \
  --form "variables[UPLOAD_TO_S3]=true" \
266
  https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
267 268
```

269 270 271
Trigger variables have the [highest priority](../variables/README.md#priority-of-environment-variables)
of all types of variables.

272
## Using cron to trigger nightly pipelines
273 274 275

>**Note:**
The following behavior can also be achieved through GitLab's UI with
276
[pipeline schedules](../pipelines/schedules.md).
277 278 279 280 281

Whether you craft a script or just run cURL directly, you can trigger jobs
in conjunction with cron. The example below triggers a job on the `master`
branch of project with ID `9` every night at `00:30`:

282
```shell
283 284 285
30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
```

286 287 288 289 290 291
## Legacy triggers

Old triggers, created before GitLab 9.0 will be marked as legacy.

Triggers with the legacy label do not have an associated user and only have
access to the current project. They are considered deprecated and will be
292
removed with one of the future versions of GitLab.