diff options
Diffstat (limited to 'doc/ci/triggers/README.md')
| -rw-r--r-- | doc/ci/triggers/README.md | 190 |
1 files changed, 79 insertions, 111 deletions
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 5f611314d09..7ec7136d8c6 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,18 +1,25 @@ -# Triggering jobs through the API +# Triggering pipelines through the API -> **Note**: +> **Notes**: - [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. + +## Authentication tokens + +The following methods of authentication are supported. + +### Trigger token -## Add a trigger +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 ➔ CI/CD Pipelines ➔ Triggers**. 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.  -## 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 **CI/CD 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. - - - ---- - -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 + +> **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. + +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): -### Making use of trigger variables +``` +https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN +``` -Using trigger variables can be proven useful for a variety of reasons. +## 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. + + + +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,11 @@ curl --request POST \ https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` -### Using webhook to trigger job - -You can add the following webhook to another project in order to trigger a job: +## Using cron to trigger nightly pipelines -``` -https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN&variables[UPLOAD_TO_S3]=true -``` - -### Using cron to trigger nightly jobs +>**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` @@ -226,32 +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 ``` -[ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 - -## Using scheduled triggers - -> [Introduced][ci-10533] in GitLab CE 9.1 as experimental. - -In order to schedule a trigger, navigate to your project's **Settings ➔ CI/CD Pipelines ➔ Triggers** and edit an existing trigger token. - - - -To set up a scheduled trigger: - -1. Check the **Schedule trigger (experimental)** checkbox -1. Enter a cron value for the frequency of the trigger ([learn more about cron notation](http://www.nncron.ru/help/EN/working/cron-format.htm)) -1. Enter the timezone of the cron trigger ([see a list of timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) -1. Enter the branch or tag that the trigger will target -1. Hit **Save trigger** for the changes to take effect - - - -You can check a next execution date of the scheduled trigger, which is automatically calculated by a server. +## Legacy triggers - +Old triggers, created before GitLab 9.0 will be marked as legacy. -> **Notes**: -- Those triggers won't be executed precicely. Because scheduled triggers are handled by Sidekiq, which runs according to its interval. For exmaple, if you set a trigger to be executed every minute (`* * * * *`) and the Sidekiq worker performs 00:00 and 12:00 o'clock every day (`0 */12 * * *`), then your trigger will be executed only 00:00 and 12:00 o'clock every day. To change the Sidekiq worker's frequency, you have to edit the `trigger_schedule_worker` value in `config/gitlab.yml` and restart GitLab. The Sidekiq worker's configuration on GiLab.com is able to be looked up at [here](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example#L185). -- Cron notation is parsed by [Rufus-Scheduler](https://github.com/jmettraux/rufus-scheduler). +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. -[ci-10533]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10533 +[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 |