diff options
Diffstat (limited to 'doc/ci/triggers/README.md')
| -rw-r--r-- | doc/ci/triggers/README.md | 36 |
1 files changed, 22 insertions, 14 deletions
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 6fca482975c..2e7ec58f048 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,11 +1,11 @@ --- stage: Verify group: Continuous Integration -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/#designated-technical-writers +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 +# Triggering pipelines through the API **(CORE)** Triggers can be used to force a pipeline rerun of a specific `ref` (branch or tag) with an API call. @@ -32,7 +32,7 @@ This also applies when using the `pipelines` or `triggers` keywords with the leg A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). -DANGER: **Warning:** +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) @@ -56,7 +56,7 @@ and it creates a dependent pipeline relation visible on the build_docs: stage: deploy script: - - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline + - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" only: - tags ``` @@ -96,7 +96,7 @@ Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts ## Adding a new trigger Go to your -**Settings ➔ CI/CD** under **Triggers** to add a new trigger. The **Add trigger** button creates +**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. @@ -109,12 +109,12 @@ overview of the time the triggers were last used. ## 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. +**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 GitLab's API endpoint: +To trigger a job you need to send a `POST` request to the GitLab API endpoint: ```plaintext POST /projects/:id/trigger/pipeline @@ -126,7 +126,7 @@ 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 GitLab's +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'.  @@ -143,7 +143,7 @@ By using cURL you can trigger a pipeline rerun with minimal effort, for example: curl --request POST \ --form token=TOKEN \ --form ref=master \ - https://gitlab.example.com/api/v4/projects/9/trigger/pipeline + "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` In this case, the project with ID `9` gets rebuilt on `master` branch. @@ -164,7 +164,7 @@ need to add in project A's `.gitlab-ci.yml`: build_docs: stage: deploy script: - - "curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" + - 'curl --request POST --form token=TOKEN --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"' only: - tags ``` @@ -244,7 +244,7 @@ curl --request POST \ --form token=TOKEN \ --form ref=master \ --form "variables[UPLOAD_TO_S3]=true" \ - https://gitlab.example.com/api/v4/projects/9/trigger/pipeline + "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` Trigger variables have the [highest priority](../variables/README.md#priority-of-environment-variables) @@ -257,10 +257,10 @@ in conjunction with cron. The example below triggers a job on the `master` branch of project with ID `9` every night at `00:30`: ```shell -30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline +30 0 * * * curl --request POST --form token=TOKEN --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` -This behavior can also be achieved through GitLab's UI with +This behavior can also be achieved through the GitLab UI with [pipeline schedules](../pipelines/schedules.md). ## Legacy triggers @@ -268,5 +268,13 @@ This behavior can also be achieved through GitLab's UI with 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 will be +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. |