2017-05-18 10:55:29 +00:00
|
|
|
# Triggering pipelines through the API
|
2015-12-21 13:53:08 +00:00
|
|
|
|
2017-05-18 10:55:29 +00:00
|
|
|
> **Notes**:
|
2018-09-06 16:52:18 +00:00
|
|
|
>
|
2018-10-14 22:55:12 +00:00
|
|
|
> - [Introduced](https://about.gitlab.com/2015/08/22/gitlab-7-14-released/) in GitLab 7.14.
|
2018-09-06 16:52:18 +00:00
|
|
|
> - GitLab 8.12 has a completely redesigned job permissions system. Read all
|
2019-03-11 01:47:01 +00:00
|
|
|
> about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#pipeline-triggers).
|
2016-09-22 12:45:35 +00:00
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
Triggers can be used to force a pipeline rerun of a specific `ref` (branch or
|
|
|
|
tag) with an API call.
|
2015-12-21 13:53:08 +00:00
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
## Authentication tokens
|
|
|
|
|
|
|
|
The following methods of authentication are supported.
|
|
|
|
|
|
|
|
### Trigger token
|
|
|
|
|
|
|
|
A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger).
|
|
|
|
|
2019-03-12 03:37:05 +00:00
|
|
|
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
|
2019-04-08 12:32:38 +00:00
|
|
|
their `.gitlab-ci.yml` file. Use [variables](../variables/README.md#gitlab-cicd-environment-variables)
|
2019-03-12 03:37:05 +00:00
|
|
|
to protect trigger tokens.
|
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
## Adding a new trigger
|
2015-12-21 13:53:08 +00:00
|
|
|
|
2017-02-13 16:59:57 +00:00
|
|
|
You can add a new trigger by going to your project's
|
2017-09-09 13:44:14 +00:00
|
|
|
**Settings ➔ CI/CD** under **Triggers**. The **Add trigger** button will
|
2017-02-13 16:59:57 +00:00
|
|
|
create a new token which you can then use to trigger a rerun of this
|
|
|
|
particular project's pipeline.
|
2015-12-24 23:29:27 +00:00
|
|
|
|
|
|
|
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-06-08 09:59:43 +00:00
|
|
|
## Taking ownership of a trigger
|
|
|
|
|
|
|
|
> **Note**:
|
|
|
|
GitLab 9.0 introduced a trigger ownership to solve permission problems.
|
2017-03-17 16:13:23 +00:00
|
|
|
|
|
|
|
Each created trigger when run will impersonate their associated user including
|
|
|
|
their access to projects and their project permissions.
|
|
|
|
|
|
|
|
You can take ownership of existing triggers by clicking *Take ownership*.
|
|
|
|
From now on the trigger will be run as you.
|
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
## Revoking a trigger
|
2015-12-24 23:29:27 +00:00
|
|
|
|
|
|
|
You can revoke a trigger any time by going at your project's
|
2017-09-09 13:44:14 +00:00
|
|
|
**Settings ➔ CI/CD** under **Triggers** and hitting the **Revoke** button.
|
2017-06-08 09:59:43 +00:00
|
|
|
The action is irreversible.
|
2015-12-24 23:29:27 +00:00
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
## Triggering a pipeline
|
2015-12-24 23:29:27 +00:00
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
> **Notes**:
|
2018-09-06 16:52:18 +00:00
|
|
|
>
|
|
|
|
> - Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
|
|
|
|
> it will not trigger a job.
|
2016-12-01 11:35:24 +00:00
|
|
|
|
2017-02-13 16:59:57 +00:00
|
|
|
To trigger a job you need to send a `POST` request to GitLab's API endpoint:
|
2015-12-24 23:29:27 +00:00
|
|
|
|
|
|
|
```
|
2017-03-05 19:58:08 +00:00
|
|
|
POST /projects/:id/trigger/pipeline
|
2015-12-24 23:29:27 +00:00
|
|
|
```
|
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
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
|
2017-09-09 13:44:14 +00:00
|
|
|
[querying the API](../../api/projects.md) or by visiting the **CI/CD**
|
2017-06-08 09:59:43 +00:00
|
|
|
settings page which provides self-explanatory examples.
|
2015-12-24 23:29:27 +00:00
|
|
|
|
2017-02-13 16:59:57 +00:00
|
|
|
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'.
|
2015-12-24 23:29:27 +00:00
|
|
|
|
2017-02-13 16:59:57 +00:00
|
|
|
![Marked rebuilds as on jobs page](img/builds_page.png)
|
2015-12-24 23:29:27 +00:00
|
|
|
|
|
|
|
---
|
|
|
|
|
2017-02-13 16:59:57 +00:00
|
|
|
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
|
2015-12-24 23:29:27 +00:00
|
|
|
below.
|
|
|
|
|
2017-02-13 16:59:57 +00:00
|
|
|
![Marked rebuilds as triggered on a single job page](img/trigger_single_build.png)
|
2015-12-24 23:29:27 +00:00
|
|
|
|
|
|
|
---
|
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
By using cURL you can trigger a pipeline rerun with minimal effort, for example:
|
2015-12-24 23:29:27 +00:00
|
|
|
|
|
|
|
```bash
|
2016-08-08 07:47:17 +00:00
|
|
|
curl --request POST \
|
|
|
|
--form token=TOKEN \
|
|
|
|
--form ref=master \
|
2017-03-05 19:58:08 +00:00
|
|
|
https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
|
2015-12-24 23:29:27 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
In this case, the project with ID `9` will get rebuilt on `master` branch.
|
|
|
|
|
2016-04-27 14:41:37 +00:00
|
|
|
Alternatively, you can pass the `token` and `ref` arguments in the query string:
|
|
|
|
|
|
|
|
```bash
|
2016-08-08 07:47:17 +00:00
|
|
|
curl --request POST \
|
2017-03-05 19:58:08 +00:00
|
|
|
"https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=master"
|
2016-04-27 14:41:37 +00:00
|
|
|
```
|
2015-12-25 11:37:46 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
need to add in project's A `.gitlab-ci.yml`:
|
2015-12-24 23:29:27 +00:00
|
|
|
|
|
|
|
```yaml
|
|
|
|
build_docs:
|
|
|
|
stage: deploy
|
|
|
|
script:
|
2017-03-05 19:58:08 +00:00
|
|
|
- "curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
|
2015-12-24 23:29:27 +00:00
|
|
|
only:
|
|
|
|
- tags
|
|
|
|
```
|
2015-12-21 13:53:08 +00:00
|
|
|
|
2017-02-13 16:59:57 +00:00
|
|
|
Now, whenever a new tag is pushed on project A, the job will run and the
|
2015-12-25 11:37:46 +00:00
|
|
|
`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.
|
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
## Triggering a pipeline from a webhook
|
2015-12-25 11:37:46 +00:00
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
> **Notes**:
|
2018-09-06 16:52:18 +00:00
|
|
|
>
|
|
|
|
> - 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.
|
2015-12-25 11:37:46 +00:00
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
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):
|
|
|
|
|
|
|
|
```
|
|
|
|
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
|
|
|
|
will be available in GitLab CI so that they can be used in your `.gitlab-ci.yml`
|
|
|
|
file. The parameter is of the form:
|
|
|
|
|
|
|
|
```
|
|
|
|
variables[key]=value
|
|
|
|
```
|
|
|
|
|
2018-12-07 13:31:53 +00:00
|
|
|
This information is also exposed in the UI. Please note that _values_ are only viewable by Owners and Maintainers.
|
2017-06-08 09:59:43 +00:00
|
|
|
|
|
|
|
![Job variables in UI](img/trigger_variables.png)
|
|
|
|
|
|
|
|
Using trigger variables can be proven useful for a variety of reasons:
|
2015-12-25 11:37:46 +00:00
|
|
|
|
2018-10-11 03:11:32 +00:00
|
|
|
- Identifiable jobs. Since the variable is exposed in the UI you can know
|
2015-12-25 11:37:46 +00:00
|
|
|
why the rebuild was triggered if you pass a variable that explains the
|
|
|
|
purpose.
|
2018-10-11 03:11:32 +00:00
|
|
|
- Conditional job processing. You can have conditional jobs that run whenever
|
2015-12-25 11:37:46 +00:00
|
|
|
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:
|
2018-12-08 07:45:46 +00:00
|
|
|
stage: test
|
2015-12-25 11:37:46 +00:00
|
|
|
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:
|
|
|
|
|
|
|
|
```bash
|
2016-08-08 07:47:17 +00:00
|
|
|
curl --request POST \
|
|
|
|
--form token=TOKEN \
|
|
|
|
--form ref=master \
|
|
|
|
--form "variables[UPLOAD_TO_S3]=true" \
|
2017-03-05 19:58:08 +00:00
|
|
|
https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
|
2015-12-25 11:37:46 +00:00
|
|
|
```
|
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
## Using cron to trigger nightly pipelines
|
2017-05-18 10:55:29 +00:00
|
|
|
|
|
|
|
>**Note:**
|
|
|
|
The following behavior can also be achieved through GitLab's UI with
|
|
|
|
[pipeline schedules](../../user/project/pipelines/schedules.md).
|
|
|
|
|
|
|
|
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`:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
|
|
|
|
```
|
|
|
|
|
2017-06-08 09:59:43 +00:00
|
|
|
## 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
|
|
|
|
removed with one of the future versions of GitLab. You are advised to
|
2019-03-11 01:47:01 +00:00
|
|
|
[take ownership](#taking-ownership-of-a-trigger) of any legacy triggers.
|
2017-06-08 09:59:43 +00:00
|
|
|
|
|
|
|
[ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017
|
2018-07-03 00:37:24 +00:00
|
|
|
[ee]: https://about.gitlab.com/pricing/
|
2017-06-08 09:59:43 +00:00
|
|
|
[variables]: ../variables/README.md
|
2019-01-30 10:20:50 +00:00
|
|
|
[predef]: ../variables/README.md#predefined-environment-variables
|
2017-06-08 09:59:43 +00:00
|
|
|
[registry]: ../../user/project/container_registry.md
|