Commit dec2f3c4 authored by Sean Packham's avatar Sean Packham

Merge branch 'docs/triggers' into 'master'

Refactor CI triggers docs

See merge request !12012
parents e50c31ab 268d9f8f
......@@ -4,15 +4,22 @@
- [Introduced][ci-229] in GitLab CE 7.14.
- GitLab 8.12 has a completely redesigned job permissions system. Read all
about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers).
- GitLab 9.0 introduced a trigger ownership to solve permission problems.
Triggers can be used to force a rebuild of a specific `ref` (branch or tag)
with an API call.
Triggers can be used to force a pipeline rerun of a specific `ref` (branch or
tag) with an API call.
## Add a trigger
## 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).
## Adding a new trigger
You can add a new trigger by going to your project's
**Settings ➔ PipelinesTriggers**. The **Add trigger** button will
**Settings ➔ Pipelines** under **Triggers**. The **Add trigger** button will
create a new token which you can then use to trigger a rerun of this
particular project's pipeline.
......@@ -22,7 +29,10 @@ overview of the time the triggers were last used.
![Triggers page overview](img/triggers_page.png)
## Take ownership
## Taking ownership of a trigger
> **Note**:
GitLab 9.0 introduced a trigger ownership to solve permission problems.
Each created trigger when run will impersonate their associated user including
their access to projects and their project permissions.
......@@ -30,26 +40,20 @@ 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.
## Legacy triggers
Old triggers, created before 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.
Legacy trigger are considered deprecated and will be removed
with one of the future versions of GitLab.
## Revoke a trigger
## Revoking a trigger
You can revoke a trigger any time by going at your project's
**Settings > Triggers** and hitting the **Revoke** button. The action is
irreversible.
**Settings ➔ Pipelines** under **Triggers** and hitting the **Revoke** button.
The action is irreversible.
## Trigger a pipeline
## Triggering a pipeline
> **Note**:
Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
it will not trigger a job.
> **Notes**:
- Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
it will not trigger a job.
- If your project is public, passing the token in plain text is probably not the
wisest idea, so you might want to use a
[secret variable](../variables/README.md#secret-variables) for that purpose.
To trigger a job you need to send a `POST` request to GitLab's API endpoint:
......@@ -57,11 +61,11 @@ To trigger a job you need to send a `POST` request to GitLab's API endpoint:
POST /projects/:id/trigger/pipeline
```
The required parameters are the trigger's `token` 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 [querying the API](../../api/projects.md)
or by visiting the **Pipelines** settings page which provides
self-explanatory examples.
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
[querying the API](../../api/projects.md) or by visiting the **Pipelines**
settings page which provides self-explanatory examples.
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'.
......@@ -78,46 +82,7 @@ below.
---
See the [Examples](#examples) section for more details on how to actually
trigger a rebuild.
## Trigger a pipeline from webhook
> Introduced in GitLab 8.14.
To trigger a job from webhook of another project you need to add the following
webhook url for Push and Tag push events:
```
https://gitlab.example.com/api/v4/projects/:id/ref/:ref/trigger/pipeline?token=TOKEN
```
> **Note**:
- `ref` should be passed as part of url in order to take precedence over `ref`
from webhook body that designates the branchref that fired the trigger in the source repository.
- `ref` should be url encoded if contains slashes.
## Pass job variables to a trigger
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
```
This information is also exposed in the UI.
![Job variables in UI](img/trigger_variables.png)
---
See the [Examples](#examples) section below for more details.
## Examples
Using cURL you can trigger a rebuild with minimal effort, for example:
By using cURL you can trigger a pipeline rerun with minimal effort, for example:
```bash
curl --request POST \
......@@ -135,8 +100,6 @@ curl --request POST \
"https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=master"
```
### Triggering a pipeline within `.gitlab-ci.yml`
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
......@@ -156,14 +119,37 @@ Now, whenever a new tag is pushed on project A, the job will run and the
`stage: deploy` ensures that this job will run only after all jobs with
`stage: test` complete successfully.
_**Note:** If your project is public, passing the token in plain text is
probably not the wisest idea, so you might want to use a
[secure variable](../variables/README.md#user-defined-variables-secure-variables)
for that purpose._
## Triggering a pipeline from a webhook
### Making use of trigger variables
> **Notes**:
- 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.
Using trigger variables can be proven useful for a variety of reasons.
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
```
This information is also exposed in the UI.
![Job variables in UI](img/trigger_variables.png)
Using trigger variables can be proven useful for a variety of reasons:
* Identifiable jobs. Since the variable is exposed in the UI you can know
why the rebuild was triggered if you pass a variable that explains the
......@@ -208,15 +194,7 @@ curl --request POST \
https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
```
### Using a webhook to trigger a pipeline
You can add the following webhook to another project in order to trigger a job:
```
https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN&variables[UPLOAD_TO_S3]=true
```
### Using cron to trigger nightly pipelines
## Using cron to trigger nightly pipelines
>**Note:**
The following behavior can also be achieved through GitLab's UI with
......@@ -230,4 +208,18 @@ branch of project with ID `9` every night at `00:30`:
30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
```
## 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
[take ownership](#taking-ownership) of any legacy triggers.
[ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017
[ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229
[ee]: https://about.gitlab.com/gitlab-ee/
[variables]: ../variables/README.md
[predef]: ../variables/README.md#predefined-variables-environment-variables
[registry]: ../../user/project/container_registry.md
doc/ci/triggers/img/triggers_page.png

108 KB | W: | H:

doc/ci/triggers/img/triggers_page.png

20.4 KB | W: | H:

doc/ci/triggers/img/triggers_page.png
doc/ci/triggers/img/triggers_page.png
doc/ci/triggers/img/triggers_page.png
doc/ci/triggers/img/triggers_page.png
  • 2-up
  • Swipe
  • Onion skin
......@@ -431,3 +431,4 @@ export CI_REGISTRY_PASSWORD="longalfanumstring"
[protected branches]: ../../user/project/protected_branches.md
[protected tags]: ../../user/project/protected_tags.md
[shellexecutors]: https://docs.gitlab.com/runner/executors/
[eep]: https://about.gitlab.com/gitlab-ee/ "Available only in GitLab Enterprise Edition Premium"
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment