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

doc/ci/multi_project_pipelines.md

@@ -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

@@ -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