Skip to content

G
gitlab-ce
Commit 464be48e authored by Evan Read's avatar Evan Read
Browse files
Options

Merge branch 'docs-pipeline-trigger-clarification' into 'master' 

Clarify behavior of various triggered pipelines

Closes #212219 and #28709

See merge request gitlab-org/gitlab!38028
parents 3d9857f7 ee81d221
Show whitespace changes
Inline Side-by-side
Showing with 50 additions and 52 deletions
doc/ci/multi_project_pipelines.md
View file @ 464be48e
......@@ -62,6 +62,14 @@ together, allowing you to visualize their relationships on pipeline graphs.
These relationships are displayed in the pipeline graph by showing inbound and
outbound connections for upstream and downstream pipeline dependencies.
When using:
- Variables or [`rules`](yaml/README.md#rulesif) to control job behavior, the value of
the [`$CI_PIPELINE_SOURCE` predefined variable](variables/predefined_variables.md) is
`pipeline` for multi-project pipeline triggered through the API with `CI_JOB_TOKEN`.
- [`only/except`](yaml/README.md#onlyexcept-basic) to control job behavior, use the
`pipelines` keyword.
## Creating multi-project pipelines from `.gitlab-ci.yml`
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
......@@ -100,6 +108,15 @@ downstream project (`my/deployment` in this case). If a downstream project can
not be found, or a user does not have access rights to create pipeline there,
the `staging` job is going to be marked as _failed_.
When using:
- Variables or [`rules`](yaml/README.md#rulesif) to control job behavior, the value of
the [`$CI_PIPELINE_SOURCE` predefined variable](variables/predefined_variables.md) is
`pipeline` for multi-project pipelines triggered with a bridge job (using the
[`trigger:`](yaml/README.md#trigger) keyword).
- [`only/except`](yaml/README.md#onlyexcept-basic) to control job behavior, use the
`pipelines` keyword.
CAUTION: **Caution:**
In the example, `staging` will be marked as succeeded as soon as a downstream pipeline
gets created. If you want to display the downstream pipeline's status instead, see
......
doc/ci/triggers/README.md
View file @ 464be48e
......@@ -7,12 +7,6 @@ type: tutorial
# Triggering pipelines through the API
> **Notes**:
>
> - [Introduced](https://about.gitlab.com/releases/2015/08/22/gitlab-7-14-released/) in GitLab 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#pipeline-triggers).
Triggers can be used to force a pipeline rerun of a specific `ref` (branch or
tag) with an API call.
......@@ -120,11 +114,6 @@ The action is irreversible.
## Triggering a pipeline
> **Notes**:
>
> - Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
> it will not trigger a job.
To trigger a job you need to send a `POST` request to GitLab's API endpoint:
```plaintext
......@@ -132,8 +121,8 @@ POST /projects/:id/trigger/pipeline
```
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
and the Git `ref` on which the trigger will be 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.
......@@ -142,16 +131,12 @@ UI under the **Jobs** page and the jobs are marked as triggered 'by API'.
![Marked rebuilds as on jobs page](img/builds_page.png)
---
You can see which trigger caused the rebuild 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 rebuilds as triggered on a single job page](img/trigger_single_build.png)
---
By using cURL you can trigger a pipeline rerun with minimal effort, for example:
```shell
......@@ -191,14 +176,6 @@ This means that whenever a new tag is pushed on project A, the job will run and
## 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):
......@@ -206,6 +183,10 @@ webhook URL for Push and Tag events (change the project ID, ref and token):
https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN
```
`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.
## Making use of trigger variables
You can pass any number of arbitrary variables in the trigger API call and they
......
doc/ci/yaml/README.md
View file @ 464be48e
......@@ -1303,14 +1303,14 @@ For behavior similar to the [`only`/`except` keywords](#onlyexcept-basic), you c
check the value of the `$CI_PIPELINE_SOURCE` variable:
| Value | Description |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `push` | For pipelines triggered by a `git push` event, including for branches and tags. |
| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. |
| `trigger` | For pipelines created by using a trigger token. |
| `trigger` | For pipelines created by using a [trigger token](../triggers/README.md#trigger-token). |
| `schedule` | For [scheduled pipelines](../pipelines/schedules.md). |
| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). |
| `external` | When using CI services other than GitLab. |
| `pipeline` | For multi-project pipelines created by [using the API with `CI_JOB_TOKEN`](../triggers/README.md#when-used-with-multi-project-pipelines). |
| `pipeline` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. |
| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command. |
| `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). |
| `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
......@@ -1526,15 +1526,15 @@ There are a few rules that apply to the usage of job policy:
In addition, `only` and `except` allow the use of special keywords:
| **Value** | **Description** |
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `branches` | When the Git reference for a pipeline is a branch. |
| `tags` | When the Git reference for a pipeline is a tag. |
| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). |
| `external` | When using CI services other than GitLab. |
| `pipelines` | For multi-project pipelines created by using the API with `CI_JOB_TOKEN`. |
| `pipelines` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. |
| `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. |
| `schedules` | For [scheduled pipelines](../pipelines/schedules.md). |
| `triggers` | For pipelines created by using a trigger token. |
| `triggers` | For pipelines created by using a [trigger token](../triggers/README.md#trigger-token). |
| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. |
| `merge_requests` | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
| `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). |
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7