diff options
Diffstat (limited to 'doc/ci/triggers')
-rw-r--r-- | doc/ci/triggers/README.md | 288 | ||||
-rw-r--r-- | doc/ci/triggers/index.md | 288 |
2 files changed, 292 insertions, 284 deletions
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index b8d0df44598..5ab8653dc35 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,288 +1,8 @@ --- -stage: Verify -group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: tutorial +redirect_to: 'index.md' --- -# Triggering pipelines through the API **(FREE)** +This document was moved to [another location](index.md). -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](#trigger-token) -- [CI job token](#ci-job-token) - -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. - -| `$CI_PIPELINE_SOURCE` value | Trigger method | -|-----------------------------|----------------| -| `pipeline` | Using the `trigger:` keyword in the CI/CD configuration file, or using the trigger API with `$CI_JOB_TOKEN`. | -| `trigger` | Using the trigger API using a generated trigger token | - -This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/README.md#only--except). - -### Trigger token - -A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). - -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 [CI/CD variables](../variables/README.md) -to protect trigger tokens. - -### CI job token - -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 - -> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2017) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. -> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [made available](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) in all tiers in GitLab 12.4. - -This way of triggering can only be used when invoked inside `.gitlab-ci.yml`, -and it creates a dependent pipeline relation visible on the -[pipeline graph](../multi_project_pipelines.md). For example: - -```yaml -trigger_pipeline: - stage: deploy - script: - - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" - rules: - - if: $CI_COMMIT_TAG -``` - -Pipelines triggered that way also expose a special variable: -`CI_PIPELINE_SOURCE=pipeline`. - -Read more about the [pipelines trigger API](../../api/pipeline_triggers.md). - -#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)** - -> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5. - -With the introduction of dependencies between different projects, one of -them may need to access artifacts created by a previous one. This process -must be granted for authorized accesses, and it can be done using the -`CI_JOB_TOKEN` variable that identifies a specific job. For example: - -```yaml -build_submodule: - image: debian - stage: test - script: - - apt update && apt install -y unzip - - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" - - unzip artifacts.zip - rules: - - if: $CI_COMMIT_TAG -``` - -This allows you to use that for multi-project pipelines and download artifacts -from any project to which you have access as this follows the same principles -with the [permission model](../../user/permissions.md#job-permissions). - -Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts-archive). - -## Adding a new trigger - -Go to your -**Settings > CI/CD** under **Triggers** to add a new trigger. The **Add trigger** button creates -a new token which you can then use to trigger a rerun of this -particular project's pipeline. - -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) - -## Revoking a trigger - -You can revoke a trigger any time by going at your project's -**Settings > CI/CD** under **Triggers** and hitting the **Revoke** button. -The action is irreversible. - -## Triggering a pipeline - -To trigger a job you need to send a `POST` request to the GitLab API endpoint: - -```plaintext -POST /projects/:id/trigger/pipeline -``` - -The required parameters are the [trigger's `token`](#authentication-tokens) -and the Git `ref` on which the trigger is performed. Valid refs are -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, jobs are marked as triggered `by API` in -**CI/CD > Jobs**. - -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. - -![Marked as triggered on a single job page](img/trigger_single_job.png) - -By using cURL you can trigger a pipeline rerun with minimal effort, for example: - -```shell -curl --request POST \ - --form token=TOKEN \ - --form ref=main \ - "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" -``` - -In this case, the pipeline for the project with ID `9` runs on the `main` branch. - -Alternatively, you can pass the `token` and `ref` arguments in the query string: - -```shell -curl --request POST \ - "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=main" -``` - -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 pipeline on the `main` -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 -trigger_pipeline: - stage: deploy - script: - - 'curl --request POST --form token=TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"' - rules: - - if: $CI_COMMIT_TAG -``` - -This means that whenever a new tag is pushed on project A, the job runs and 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. - -## Triggering a pipeline from a webhook - -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): - -```plaintext -https://gitlab.example.com/api/v4/projects/9/ref/main/trigger/pipeline?token=TOKEN -``` - -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. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321027) in GitLab 13.11. - -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#cicd-variable-types), -so you can access the data with `cat $TRIGGER_PAYLOAD` or a similar command. - -## Making use of trigger variables - -You can pass any number of arbitrary variables in the trigger API call and they -are available in GitLab CI/CD so that they can be used in your `.gitlab-ci.yml` -file. The parameter is of the form: - -```plaintext -variables[key]=value -``` - -This information is also exposed in the UI. Please note that _values_ are only viewable by Owners and Maintainers. - -![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 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. - -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: - stage: test - 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 pipeline while you pass the `UPLOAD_TO_S3` variable -and the script of the `upload_package` job is run: - -```shell -curl --request POST \ - --form token=TOKEN \ - --form ref=main \ - --form "variables[UPLOAD_TO_S3]=true" \ - "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" -``` - -Trigger variables have the [highest priority](../variables/README.md#cicd-variable-precedence) -of all types of variables. - -## Using cron to trigger nightly pipelines - -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 `main` branch -of project with ID `9` every night at `00:30`: - -```shell -30 0 * * * curl --request POST --form token=TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" -``` - -This behavior can also be achieved through the GitLab UI with -[pipeline schedules](../pipelines/schedules.md). - -## Legacy triggers - -Old triggers, created before GitLab 9.0 are 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 might be -removed with one of the future versions of GitLab. - -## Troubleshooting - -### '404 not found' when triggering a pipeline - -A response of `{"message":"404 Not Found"}` when triggering a pipeline might be caused -by using a Personal Access Token instead of a trigger token. [Add a new trigger](#adding-a-new-trigger) -and use that token to authenticate when triggering a pipeline. +<!-- This redirect file can be deleted after 2021-09-28. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md new file mode 100644 index 00000000000..383887bd389 --- /dev/null +++ b/doc/ci/triggers/index.md @@ -0,0 +1,288 @@ +--- +stage: Verify +group: Pipeline Execution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: tutorial +--- + +# 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. + +## Authentication tokens + +The following methods of authentication are supported: + +- [Trigger token](#trigger-token) +- [CI job token](#ci-job-token) + +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. + +| `$CI_PIPELINE_SOURCE` value | Trigger method | +|-----------------------------|----------------| +| `pipeline` | Using the `trigger:` keyword in the CI/CD configuration file, or using the trigger API with `$CI_JOB_TOKEN`. | +| `trigger` | Using the trigger API using a generated trigger token | + +This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/index.md#only--except). + +### Trigger token + +A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). + +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 [CI/CD variables](../variables/index.md) +to protect trigger tokens. + +### CI job token + +You can use the `CI_JOB_TOKEN` [CI/CD variable](../variables/index.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 + +> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2017) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. +> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [made available](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) in all tiers in GitLab 12.4. + +This way of triggering can only be used when invoked inside `.gitlab-ci.yml`, +and it creates a dependent pipeline relation visible on the +[pipeline graph](../pipelines/multi_project_pipelines.md). For example: + +```yaml +trigger_pipeline: + stage: deploy + script: + - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" + rules: + - if: $CI_COMMIT_TAG +``` + +Pipelines triggered that way also expose a special variable: +`CI_PIPELINE_SOURCE=pipeline`. + +Read more about the [pipelines trigger API](../../api/pipeline_triggers.md). + +#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)** + +> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5. + +With the introduction of dependencies between different projects, one of +them may need to access artifacts created by a previous one. This process +must be granted for authorized accesses, and it can be done using the +`CI_JOB_TOKEN` variable that identifies a specific job. For example: + +```yaml +build_submodule: + image: debian + stage: test + script: + - apt update && apt install -y unzip + - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" + - unzip artifacts.zip + rules: + - if: $CI_COMMIT_TAG +``` + +This allows you to use that for multi-project pipelines and download artifacts +from any project to which you have access as this follows the same principles +with the [permission model](../../user/permissions.md#job-permissions). + +Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts-archive). + +## Adding a new trigger + +Go to your +**Settings > CI/CD** under **Triggers** to add a new trigger. The **Add trigger** button creates +a new token which you can then use to trigger a rerun of this +particular project's pipeline. + +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) + +## Revoking a trigger + +You can revoke a trigger any time by going at your project's +**Settings > CI/CD** under **Triggers** and hitting the **Revoke** button. +The action is irreversible. + +## Triggering a pipeline + +To trigger a pipeline you need to send a `POST` request to the GitLab API endpoint: + +```plaintext +POST /projects/:id/trigger/pipeline +``` + +The required parameters are the [trigger's `token`](#authentication-tokens) +and the Git `ref` on which the trigger is performed. Valid refs are +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, jobs are labeled as `triggered` in +**CI/CD > Jobs**. + +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. + +![Marked as triggered on a single job page](img/trigger_single_job.png) + +By using cURL you can trigger a pipeline rerun with minimal effort, for example: + +```shell +curl --request POST \ + --form token=TOKEN \ + --form ref=main \ + "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" +``` + +In this case, the pipeline for the project with ID `9` runs on the `main` branch. + +Alternatively, you can pass the `token` and `ref` arguments in the query string: + +```shell +curl --request POST \ + "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=main" +``` + +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 pipeline on the `main` +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 +trigger_pipeline: + stage: deploy + script: + - 'curl --request POST --form token=TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"' + rules: + - if: $CI_COMMIT_TAG +``` + +This means that whenever a new tag is pushed on project A, the job runs and 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. + +## Triggering a pipeline from a webhook + +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): + +```plaintext +https://gitlab.example.com/api/v4/projects/9/ref/main/trigger/pipeline?token=TOKEN +``` + +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. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321027) in GitLab 13.11. + +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/index.md#cicd-variable-types), +so you can access the data with `cat $TRIGGER_PAYLOAD` or a similar command. + +## Making use of trigger variables + +You can pass any number of arbitrary variables in the trigger API call and they +are available in GitLab CI/CD so that they can be used in your `.gitlab-ci.yml` +file. The parameter is of the form: + +```plaintext +variables[key]=value +``` + +This information is also exposed in the UI. Please note that _values_ are only viewable by Owners and Maintainers. + +![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 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. + +Consider the following `.gitlab-ci.yml` where we set three +[stages](../yaml/index.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: + stage: test + 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 pipeline while you pass the `UPLOAD_TO_S3` variable +and the script of the `upload_package` job is run: + +```shell +curl --request POST \ + --form token=TOKEN \ + --form ref=main \ + --form "variables[UPLOAD_TO_S3]=true" \ + "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" +``` + +Trigger variables have the [highest priority](../variables/index.md#cicd-variable-precedence) +of all types of variables. + +## Using cron to trigger nightly pipelines + +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 `main` branch +of project with ID `9` every night at `00:30`: + +```shell +30 0 * * * curl --request POST --form token=TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" +``` + +This behavior can also be achieved through the GitLab UI with +[pipeline schedules](../pipelines/schedules.md). + +## Legacy triggers + +Old triggers, created before GitLab 9.0 are 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 might be +removed with one of the future versions of GitLab. + +## Troubleshooting + +### '404 not found' when triggering a pipeline + +A response of `{"message":"404 Not Found"}` when triggering a pipeline might be caused +by using a Personal Access Token instead of a trigger token. [Add a new trigger](#adding-a-new-trigger) +and use that token to authenticate when triggering a pipeline. |