diff options
Diffstat (limited to 'doc/ci/triggers/index.md')
| -rw-r--r-- | doc/ci/triggers/index.md | 54 |
1 files changed, 28 insertions, 26 deletions
diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index a47eaaf0381..506f6fb2106 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -5,19 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Trigger pipelines by using the API **(FREE)** +# Trigger pipelines by using the API **(FREE ALL)** To trigger a pipeline for a specific branch or tag, you can use an API call to the [pipeline triggers API endpoint](../../api/pipeline_triggers.md). When authenticating with the API, you can use: -- A [trigger token](#create-a-trigger-token) to trigger a branch or tag pipeline. +- A [pipeline trigger token](#create-a-pipeline-trigger-token) to trigger a branch or tag pipeline. - A [CI/CD job token](../jobs/ci_job_token.md) to [trigger a multi-project pipeline](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api). -## Create a trigger token +## Create a pipeline trigger token -You can trigger a pipeline for a branch or tag by generating a trigger token and using it +You can trigger a pipeline for a branch or tag by generating a pipeline trigger token and using it to authenticate an API call. The token impersonates a user's project access and permissions. Prerequisite: @@ -28,8 +28,9 @@ To create a trigger token: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. -1. Expand **Pipeline triggers**. -1. Enter a description and select **Add trigger**. +1. Expand **Pipeline trigger tokens**. +1. Select **Add new token** +1. Enter a description and select **Create pipeline trigger token**. - You can view and copy the full token for all triggers you have created. - You can only see the first 4 characters for tokens created by other project members. @@ -41,12 +42,12 @@ to improve the security of trigger tokens. ## Trigger a pipeline -After you [create a trigger token](#create-a-trigger-token), you can use it to trigger +After you [create a pipeline trigger token](#create-a-pipeline-trigger-token), you can use it to trigger pipelines with a tool that can access the API, or a webhook. ### Use cURL -You can use cURL to trigger pipelines with the [pipeline triggers API endpoint](../../api/pipeline_triggers.md). +You can use cURL to trigger pipelines with the [pipeline trigger token API endpoint](../../api/pipeline_triggers.md). For example: - Use a multiline cURL command: @@ -62,7 +63,7 @@ For example: ```shell curl --request POST \ - "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline?token=<token>&ref=<ref_name>" + "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline?token=<token>&ref=<ref_name>" ``` In each example, replace: @@ -75,7 +76,7 @@ In each example, replace: ### Use a CI/CD job -You can use a CI/CD job with a triggers token to trigger pipelines when another pipeline +You can use a CI/CD job with a pipeline triggers token to trigger pipelines when another pipeline runs. For example, to trigger a pipeline on the `main` branch of `project-B` when a tag @@ -116,9 +117,9 @@ Replace: - `<ref_name>` with a branch or tag name, like `main`. This value takes precedence over the `ref_name` in the webhook payload. The payload's `ref` is the branch that fired the trigger in the source repository. You must URL-encode the `ref_name` if it contains slashes. -- `<token>` with your trigger token. +- `<token>` with your pipeline trigger token. -#### Use a webhook payload +#### Access webhook payload > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31197) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321027) in GitLab 13.11. @@ -138,10 +139,10 @@ The parameter is of the form `variables[key]=value`, for example: ```shell curl --request POST \ - --form token=TOKEN \ - --form ref=main \ - --form "variables[UPLOAD_TO_S3]=true" \ - "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline" + --form token=TOKEN \ + --form ref=main \ + --form variables[UPLOAD_TO_S3]="true" \ + "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline" ``` CI/CD variables in triggered pipelines display on each job's page, but only @@ -149,9 +150,9 @@ users with the Owner and Maintainer role can view the values.  -## Revoke a trigger token +## Revoke a pipeline trigger token -To revoke a trigger token: +To revoke a pipeline trigger token: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. @@ -162,23 +163,24 @@ A revoked trigger token cannot be added back. ## Configure CI/CD jobs to run in triggered pipelines -To [configure when to run jobs](../jobs/job_control.md) in triggered pipelines: +To [configure when to run jobs](../jobs/job_control.md) in triggered pipelines, you can: - Use [`rules`](../yaml/index.md#rules) with the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md). -- Use [`only`/`except`](../yaml/index.md#onlyrefs--exceptrefs) keywords. +- Use [`only`/`except`](../yaml/index.md#onlyrefs--exceptrefs) keywords, though `rules` + is the preferred keyword. | `$CI_PIPELINE_SOURCE` value | `only`/`except` keywords | Trigger method | |-----------------------------|--------------------------|---------------------| -| `trigger` | `triggers` | In pipelines triggered with the [pipeline triggers API](../../api/pipeline_triggers.md) by using a [trigger token](#create-a-trigger-token). | +| `trigger` | `triggers` | In pipelines triggered with the [pipeline triggers API](../../api/pipeline_triggers.md) by using a [trigger token](#create-a-pipeline-trigger-token). | | `pipeline` | `pipelines` | In [multi-project pipelines](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api) triggered with the [pipeline triggers API](../../api/pipeline_triggers.md) by using the [`$CI_JOB_TOKEN`](../jobs/ci_job_token.md), or by using the [`trigger`](../yaml/index.md#trigger) keyword in the CI/CD configuration file. | Additionally, the `$CI_PIPELINE_TRIGGERED` predefined CI/CD variable is set to `true` -in pipelines triggered with a trigger token. +in pipelines triggered with a pipeline trigger token. -## See which trigger token was used +## See which pipeline trigger token was used -You can see which trigger caused a job to run by visiting the single job page. -A part of the trigger's token displays on the right of the page, under the job details: +You can see which pipeline trigger token caused a job to run by visiting the single job page. +A part of the trigger token displays on the right of the page, under the job details:  @@ -196,7 +198,7 @@ To avoid trigger loops, do not use [pipeline events](../../user/project/integrat A response of `{"message":"404 Not Found"}` when triggering a pipeline might be caused by using a [personal access token](../../user/profile/personal_access_tokens.md) -instead of a trigger token. [Create a new trigger token](#create-a-trigger-token) +instead of a pipeline trigger token. [Create a new trigger token](#create-a-pipeline-trigger-token) and use it instead of the personal access token. ### `The requested URL returned error: 400` when triggering a pipeline |