debian-mirror-gitlab/doc/ci/triggers/README.md

289 lines
11 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
2020-06-23 00:09:42 +05:30
stage: Verify
group: Continuous Integration
2021-02-22 17:27:13 +05:30
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
2019-09-04 21:01:54 +05:30
type: tutorial
---
2021-03-11 19:13:27 +05:30
# Triggering pipelines through the API **(FREE)**
2017-09-10 17:25:29 +05:30
Triggers can be used to force a pipeline rerun of a specific `ref` (branch or
tag) with an API call.
2017-09-10 17:25:29 +05:30
## Authentication tokens
2020-04-22 19:07:51 +05:30
The following methods of authentication are supported:
- [Trigger token](#trigger-token)
- [CI job token](#ci-job-token)
2021-03-11 19:13:27 +05:30
If using the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md)
2020-04-22 19:07:51 +05:30
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 |
2021-06-08 01:23:25 +05:30
This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/README.md#only--except).
2017-09-10 17:25:29 +05:30
### Trigger token
A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger).
2021-02-22 17:27:13 +05:30
WARNING:
2019-07-07 11:18:12 +05:30
Passing plain text tokens in public projects is a security issue. Potential
attackers can impersonate the user that exposed their trigger token publicly in
2021-03-11 19:13:27 +05:30
their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/README.md)
2019-07-07 11:18:12 +05:30
to protect trigger tokens.
2019-07-31 22:56:46 +05:30
### CI job token
2021-03-11 19:13:27 +05:30
You can use the `CI_JOB_TOKEN` [CI/CD variable](../variables/README.md#predefined-cicd-variables) (used to authenticate
2020-04-22 19:07:51 +05:30
with the [GitLab Container Registry](../../user/packages/container_registry/index.md)) in the following cases.
2019-07-31 22:56:46 +05:30
2019-12-21 20:55:43 +05:30
#### When used with multi-project pipelines
2019-07-31 22:56:46 +05:30
2020-04-22 19:07:51 +05:30
> - 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.
2020-06-23 00:09:42 +05:30
> - 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.
2019-07-31 22:56:46 +05:30
This way of triggering can only be used when invoked inside `.gitlab-ci.yml`,
and it creates a dependent pipeline relation visible on the
2021-01-03 14:25:43 +05:30
[pipeline graph](../multi_project_pipelines.md). For example:
2019-07-31 22:56:46 +05:30
```yaml
2021-03-11 19:13:27 +05:30
trigger_pipeline:
2019-07-31 22:56:46 +05:30
stage: deploy
script:
2021-02-22 17:27:13 +05:30
- curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
2019-07-31 22:56:46 +05:30
only:
2020-07-28 23:09:34 +05:30
- tags
2019-07-31 22:56:46 +05:30
```
Pipelines triggered that way also expose a special variable:
`CI_PIPELINE_SOURCE=pipeline`.
2020-04-22 19:07:51 +05:30
Read more about the [pipelines trigger API](../../api/pipeline_triggers.md).
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)**
2019-07-31 22:56:46 +05:30
2020-04-22 19:07:51 +05:30
> 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.
2019-07-31 22:56:46 +05:30
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:
2020-07-28 23:09:34 +05:30
- 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
2019-07-31 22:56:46 +05:30
only:
2020-07-28 23:09:34 +05:30
- tags
2019-07-31 22:56:46 +05:30
```
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
2020-04-22 19:07:51 +05:30
with the [permission model](../../user/permissions.md#job-permissions).
2019-07-31 22:56:46 +05:30
2020-10-24 23:57:45 +05:30
Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts-archive).
2019-07-31 22:56:46 +05:30
2017-09-10 17:25:29 +05:30
## Adding a new trigger
2021-01-03 14:25:43 +05:30
Go to your
2021-02-22 17:27:13 +05:30
**Settings > CI/CD** under **Triggers** to add a new trigger. The **Add trigger** button creates
2021-01-03 14:25:43 +05:30
a new token which you can then use to trigger a rerun of this
2017-08-17 22:00:37 +05:30
particular project's pipeline.
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)
2017-09-10 17:25:29 +05:30
## Revoking a trigger
You can revoke a trigger any time by going at your project's
2021-02-22 17:27:13 +05:30
**Settings > CI/CD** under **Triggers** and hitting the **Revoke** button.
2017-09-10 17:25:29 +05:30
The action is irreversible.
2017-09-10 17:25:29 +05:30
## Triggering a pipeline
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
To trigger a job you need to send a `POST` request to the GitLab API endpoint:
2020-03-13 15:44:24 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/trigger/pipeline
```
2017-09-10 17:25:29 +05:30
The required parameters are the [trigger's `token`](#authentication-tokens)
2021-01-03 14:25:43 +05:30
and the Git `ref` on which the trigger is performed. Valid refs are
2020-10-24 23:57:45 +05:30
branches or tags. The `:id` of a project can be found by
2018-03-17 18:26:18 +05:30
[querying the API](../../api/projects.md) or by visiting the **CI/CD**
2017-09-10 17:25:29 +05:30
settings page which provides self-explanatory examples.
2021-03-11 19:13:27 +05:30
When a rerun of a pipeline is triggered, jobs are marked as triggered `by API` in
**CI/CD > Jobs**.
2021-03-11 19:13:27 +05:30
You can see which trigger caused a job to run by visiting the single job page.
2017-08-17 22:00:37 +05:30
A part of the trigger's token is exposed in the UI as you can see from the image
below.
2021-03-11 19:13:27 +05:30
![Marked as triggered on a single job page](img/trigger_single_job.png)
2017-09-10 17:25:29 +05:30
By using cURL you can trigger a pipeline rerun with minimal effort, for example:
2020-03-13 15:44:24 +05:30
```shell
2016-09-13 17:45:13 +05:30
curl --request POST \
--form token=TOKEN \
--form ref=master \
2021-02-22 17:27:13 +05:30
"https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
```
2021-03-11 19:13:27 +05:30
In this case, the pipeline for the project with ID `9` runs on the `master` branch.
2016-06-02 11:05:42 +05:30
Alternatively, you can pass the `token` and `ref` arguments in the query string:
2020-03-13 15:44:24 +05:30
```shell
2016-09-13 17:45:13 +05:30
curl --request POST \
2017-08-17 22:00:37 +05:30
"https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=master"
2016-06-02 11:05:42 +05:30
```
You can also benefit by using triggers in your `.gitlab-ci.yml`. Let's say that
2021-03-11 19:13:27 +05:30
you have two projects, A and B, and you want to trigger a pipeline on the `master`
branch of project B whenever a tag on project A is created. This is the job you
2019-12-21 20:55:43 +05:30
need to add in project A's `.gitlab-ci.yml`:
```yaml
2021-03-11 19:13:27 +05:30
trigger_pipeline:
stage: deploy
script:
2021-02-22 17:27:13 +05:30
- 'curl --request POST --form token=TOKEN --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"'
only:
2020-07-28 23:09:34 +05:30
- tags
```
2021-01-03 14:25:43 +05:30
This means that whenever a new tag is pushed on project A, the job runs and the
2021-03-11 19:13:27 +05:30
`trigger_pipeline` job is executed, triggering the pipeline for project B. The
2021-01-03 14:25:43 +05:30
`stage: deploy` ensures that this job runs only after all jobs with
`stage: test` complete successfully.
2017-09-10 17:25:29 +05:30
## Triggering a pipeline from a webhook
2017-09-10 17:25:29 +05:30
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):
2020-03-13 15:44:24 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN
```
2021-01-03 14:25:43 +05:30
You should pass `ref` as part of the URL, to take precedence over `ref` from
the webhook body that designates the branch ref that fired the trigger in the
source repository. Be sure to URL-encode `ref` if it contains slashes.
2020-10-24 23:57:45 +05:30
2021-03-11 19:13:27 +05:30
### Using webhook payload in the triggered pipeline
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31197) in GitLab 13.9.
2021-04-29 21:17:54 +05:30
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321027) in GitLab 13.11.
2021-03-11 19:13:27 +05:30
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).
2021-04-29 21:17:54 +05:30
The payload is exposed as a [file-type variable](../variables/README.md#cicd-variable-types),
2021-03-11 19:13:27 +05:30
so you can access the data with `cat $TRIGGER_PAYLOAD` or a similar command.
2017-09-10 17:25:29 +05:30
## Making use of trigger variables
You can pass any number of arbitrary variables in the trigger API call and they
2021-01-03 14:25:43 +05:30
are available in GitLab CI/CD so that they can be used in your `.gitlab-ci.yml`
2017-09-10 17:25:29 +05:30
file. The parameter is of the form:
2020-03-13 15:44:24 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
variables[key]=value
```
2019-02-15 15:39:39 +05:30
This information is also exposed in the UI. Please note that _values_ are only viewable by Owners and Maintainers.
2017-09-10 17:25:29 +05:30
![Job variables in UI](img/trigger_variables.png)
Using trigger variables can be proven useful for a variety of reasons:
2018-12-13 13:39:08 +05:30
- Identifiable jobs. Since the variable is exposed in the UI you can know
2021-03-11 19:13:27 +05:30
why the pipeline was triggered if you pass a variable that explains the
purpose.
2018-12-13 13:39:08 +05:30
- Conditional job processing. You can have conditional jobs that run whenever
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:
2020-07-28 23:09:34 +05:30
- test
- build
- package
run_tests:
2019-02-15 15:39:39 +05:30
stage: test
script:
2020-07-28 23:09:34 +05:30
- make test
build_package:
stage: build
script:
2020-07-28 23:09:34 +05:30
- make build
upload_package:
stage: package
script:
2020-07-28 23:09:34 +05:30
- if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi
```
2021-03-11 19:13:27 +05:30
You can then trigger a pipeline while you pass the `UPLOAD_TO_S3` variable
2021-01-03 14:25:43 +05:30
and the script of the `upload_package` job is run:
2020-03-13 15:44:24 +05:30
```shell
2016-09-13 17:45:13 +05:30
curl --request POST \
--form token=TOKEN \
--form ref=master \
--form "variables[UPLOAD_TO_S3]=true" \
2021-02-22 17:27:13 +05:30
"https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
```
2021-04-29 21:17:54 +05:30
Trigger variables have the [highest priority](../variables/README.md#cicd-variable-precedence)
2020-03-13 15:44:24 +05:30
of all types of variables.
2017-09-10 17:25:29 +05:30
## Using cron to trigger nightly pipelines
2017-08-17 22:00:37 +05:30
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`:
2020-03-13 15:44:24 +05:30
```shell
2021-02-22 17:27:13 +05:30
30 0 * * * curl --request POST --form token=TOKEN --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
```
2021-02-22 17:27:13 +05:30
This behavior can also be achieved through the GitLab UI with
2021-01-03 14:25:43 +05:30
[pipeline schedules](../pipelines/schedules.md).
2017-09-10 17:25:29 +05:30
## Legacy triggers
2021-01-03 14:25:43 +05:30
Old triggers, created before GitLab 9.0 are marked as legacy.
2017-09-10 17:25:29 +05:30
Triggers with the legacy label do not have an associated user and only have
2021-02-22 17:27:13 +05:30
access to the current project. They are considered deprecated and might be
2019-12-04 20:38:33 +05:30
removed with one of the future versions of GitLab.
2021-02-22 17:27:13 +05:30
## 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 instead of a trigger token. [Add a new trigger](#adding-a-new-trigger)
and use that token to authenticate when triggering a pipeline.