diff options
Diffstat (limited to 'doc/ci/triggers/README.md')
| -rw-r--r-- | doc/ci/triggers/README.md | 69 |
1 files changed, 51 insertions, 18 deletions
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 2e7ec58f048..b4cea48a362 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Triggering pipelines through the API **(CORE)** +# Triggering pipelines through the API **(FREE)** Triggers can be used to force a pipeline rerun of a specific `ref` (branch or tag) with an API call. @@ -17,7 +17,7 @@ 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) +If using the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) to limit which jobs run in a pipeline, the value could be either `pipeline` or `trigger`, depending on which trigger method is used. @@ -35,12 +35,12 @@ A unique trigger token can be obtained when [adding a new trigger](#adding-a-new WARNING: Passing plain text tokens in public projects is a security issue. Potential attackers can impersonate the user that exposed their trigger token publicly in -their `.gitlab-ci.yml` file. Use [variables](../variables/README.md#gitlab-cicd-environment-variables) +their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/README.md) to protect trigger tokens. ### CI job token -You can use the `CI_JOB_TOKEN` [variable](../variables/README.md#predefined-environment-variables) (used to authenticate +You can use the `CI_JOB_TOKEN` [CI/CD variable](../variables/README.md#predefined-cicd-variables) (used to authenticate with the [GitLab Container Registry](../../user/packages/container_registry/index.md)) in the following cases. #### When used with multi-project pipelines @@ -53,7 +53,7 @@ and it creates a dependent pipeline relation visible on the [pipeline graph](../multi_project_pipelines.md). For example: ```yaml -build_docs: +trigger_pipeline: stage: deploy script: - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" @@ -126,16 +126,14 @@ branches or tags. The `:id` of a project can be found by [querying the API](../../api/projects.md) or by visiting the **CI/CD** settings page which provides self-explanatory examples. -When a rerun of a pipeline is triggered, the information is exposed in the GitLab -UI under the **Jobs** page and the jobs are marked as triggered 'by API'. +When a rerun of a pipeline is triggered, jobs are marked as triggered `by API` in +**CI/CD > Jobs**. - - -You can see which trigger caused the rebuild by visiting the single job page. +You can see which trigger caused a job to run 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 below. - + By using cURL you can trigger a pipeline rerun with minimal effort, for example: @@ -146,7 +144,7 @@ curl --request POST \ "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` -In this case, the project with ID `9` gets rebuilt on `master` branch. +In this case, the pipeline for the project with ID `9` runs on the `master` branch. Alternatively, you can pass the `token` and `ref` arguments in the query string: @@ -156,12 +154,12 @@ curl --request POST \ ``` 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` +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 need to add in project A's `.gitlab-ci.yml`: ```yaml -build_docs: +trigger_pipeline: stage: deploy script: - 'curl --request POST --form token=TOKEN --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"' @@ -170,7 +168,7 @@ build_docs: ``` This means that whenever a new tag is pushed on project A, the job runs and the -`build_docs` job is executed, triggering a rebuild of project B. The +`trigger_pipeline` job is executed, triggering the pipeline for project B. The `stage: deploy` ensures that this job runs only after all jobs with `stage: test` complete successfully. @@ -187,6 +185,41 @@ 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. +### Using webhook payload in the triggered pipeline + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31197) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-trigger_payload-variable). **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +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). +The payload is exposed as a [file-type variable](../variables/README.md#custom-cicd-variables-of-type-file), +so you can access the data with `cat $TRIGGER_PAYLOAD` or a similar command. + +#### Enable or disable the `TRIGGER_PAYLOAD` variable + +The `TRIGGER_PAYLOAD` CI/CD variable is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:ci_trigger_payload_into_pipeline) +``` + +To disable it: + +```ruby +Feature.disable(:ci_trigger_payload_into_pipeline) +``` + ## Making use of trigger variables You can pass any number of arbitrary variables in the trigger API call and they @@ -204,7 +237,7 @@ This information is also exposed in the UI. Please note that _values_ are only v 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 + why the pipeline was triggered if you pass a variable that explains the purpose. - Conditional job processing. You can have conditional jobs that run whenever a certain variable is present. @@ -236,7 +269,7 @@ upload_package: - if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi ``` -You can then trigger a rebuild while you pass the `UPLOAD_TO_S3` variable +You can then trigger a pipeline while you pass the `UPLOAD_TO_S3` variable and the script of the `upload_package` job is run: ```shell @@ -247,7 +280,7 @@ curl --request POST \ "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` -Trigger variables have the [highest priority](../variables/README.md#priority-of-environment-variables) +Trigger variables have the [highest priority](../variables/README.md#priority-of-cicd-variables) of all types of variables. ## Using cron to trigger nightly pipelines |