Merge branch 'selhorn-trigger-cleanup' into 'master'

Updated trigger to be reference only

See merge request gitlab-org/gitlab!73217

doc/ci/pipelines/parent_child_pipelines.md

@@ -81,7 +81,8 @@ microservice_a:
   trigger:
     include:
       - project: 'my-group/my-pipeline-library'
-        file: 'path/to/ci-config.yml'
+        ref: 'main'
+        file: '/path/to/child-pipeline.yml'
 ```
 
 The maximum number of entries that are accepted for `trigger:include:` is three.
@@ -98,7 +99,7 @@ microservice_a:
     strategy: depend
 ```
 
-## Merge Request child pipelines
+## Merge request child pipelines
 
 To trigger a child pipeline as a [Merge Request Pipeline](merge_request_pipelines.md) we need to:
 
@@ -149,7 +150,7 @@ microservice_a:
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9.
 
 Instead of running a child pipeline from a static YAML file, you can define a job that runs
-your own script to generate a YAML file, which is then [used to trigger a child pipeline](../yaml/index.md#trigger-child-pipeline-with-generated-configuration-file).
+your own script to generate a YAML file, which is then used to trigger a child pipeline.
 
 This technique can be very powerful in generating pipelines targeting content that changed or to
 build a matrix of targets and architectures.
@@ -171,6 +172,31 @@ configuration for jobs, like scripts, that use the Windows runner would use `\`.
 In GitLab 12.9, the child pipeline could fail to be created in certain cases, causing the parent pipeline to fail.
 This is [resolved](https://gitlab.com/gitlab-org/gitlab/-/issues/209070) in GitLab 12.10.
 
+### Dynamic child pipeline example
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9.
+
+You can trigger a child pipeline from a [dynamically generated configuration file](../pipelines/parent_child_pipelines.md#dynamic-child-pipelines):
+
+```yaml
+generate-config:
+  stage: build
+  script: generate-ci-config > generated-config.yml
+  artifacts:
+    paths:
+      - generated-config.yml
+
+child-pipeline:
+  stage: test
+  trigger:
+    include:
+      - artifact: generated-config.yml
+        job: generate-config
+```
+
+The `generated-config.yml` is extracted from the artifacts and used as the configuration
+for triggering the child pipeline.
+
 ## Nested child pipelines
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) in GitLab 13.4.

doc/ci/resource_groups/index.md

@@ -177,7 +177,7 @@ deploy:
 ```
 
 In a parent pipeline, it runs the `test` job that subsequently runs a child pipeline,
-and the [`strategy: depend` option](../yaml/index.md#linking-pipelines-with-triggerstrategy) makes the `test` job wait until the child pipeline has finished.
+and the [`strategy: depend` option](../yaml/index.md#triggerstrategy) makes the `test` job wait until the child pipeline has finished.
 The parent pipeline runs the `deploy` job in the next stage, that requires a resource from the `production` resource group.
 If the process mode is `oldest_first`, it executes the jobs from the oldest pipelines, meaning the `deploy` job is going to be executed next.
 

doc/ci/triggers/index.md

@@ -113,6 +113,9 @@ This means that whenever a new tag is pushed on project A, the job runs and the
 `stage: deploy` ensures that this job runs only after all jobs with
 `stage: test` complete successfully.
 
+NOTE:
+You [cannot use the API to start `when:manual` trigger jobs](https://gitlab.com/gitlab-org/gitlab/-/issues/284086).
+
 ## Triggering a pipeline from a webhook
 
 To trigger a job from a webhook of another project you need to add the following

doc/ci/yaml/index.md

@@ -3802,31 +3802,19 @@ deploystacks:
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in GitLab Premium 11.8.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8.
 
-Use `trigger` to define a downstream pipeline trigger. When GitLab starts a `trigger` job,
-a downstream pipeline is created.
+Use `trigger` to start a downstream pipeline that is either:
 
-Jobs with `trigger` can only use a [limited set of keywords](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file).
-For example, you can't run commands with [`script`](#script), [`before_script`](#before_script),
-or [`after_script`](#after_script).
+- [A multi-project pipeline](../pipelines/multi_project_pipelines.md).
+- [A child pipeline](../pipelines/parent_child_pipelines.md).
 
-You can use this keyword to create two different types of downstream pipelines:
-
-- [Multi-project pipelines](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file)
-- [Child pipelines](../pipelines/parent_child_pipelines.md)
-
-In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can
-view which job triggered a downstream pipeline. In the [pipeline graph](../pipelines/index.md#visualize-pipelines),
-hover over the downstream pipeline job.
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you
-can use [`when:manual`](#when) in the same job as `trigger`. In GitLab 13.4 and
-earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`.
-You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086).
+**Possible inputs**: 
 
-#### Basic `trigger` syntax for multi-project pipelines
+- For multi-project pipelines, path to the downstream project.
+- For child pipelines, path to the child pipeline CI/CD configuration file.
 
-You can configure a downstream trigger by using the `trigger` keyword
-with a full path to a downstream project:
+**Example of `trigger` for multi-project pipeline**:
 
 ```yaml
 rspec:
@@ -3838,47 +3826,7 @@ staging:
   trigger: my/deployment
 ```
 
-#### Complex `trigger` syntax for multi-project pipelines
-
-You can configure a branch name that GitLab uses to create
-a downstream pipeline with:
-
-```yaml
-rspec:
-  stage: test
-  script: bundle exec rspec
-
-staging:
-  stage: deploy
-  trigger:
-    project: my/deployment
-    branch: stable
-```
-
-To mirror the status from a triggered pipeline:
-
-```yaml
-trigger_job:
-  trigger:
-    project: my/project
-    strategy: depend
-```
-
-To mirror the status from an upstream pipeline:
-
-```yaml
-upstream_bridge:
-  stage: test
-  needs:
-    pipeline: other/project
-```
-
-#### `trigger` syntax for child pipeline
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) in GitLab 12.7.
-
-To create a [child pipeline](../pipelines/parent_child_pipelines.md), specify the path to the
-YAML file that contains the configuration of the child pipeline:
+**Example of `trigger` for child pipelines**:
 
 ```yaml
 trigger_job:
@@ -3886,71 +3834,36 @@ trigger_job:
     include: path/to/child-pipeline.yml
 ```
 
-Similar to [multi-project pipelines](../pipelines/multi_project_pipelines.md#mirror-status-of-a-triggered-pipeline-in-the-trigger-job),
-it's possible to mirror the status from a triggered pipeline:
-
-```yaml
-trigger_job:
-  trigger:
-    include:
-      - local: path/to/child-pipeline.yml
-    strategy: depend
-```
-
-##### Trigger child pipeline with generated configuration file
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9.
-
-You can also trigger a child pipeline from a [dynamically generated configuration file](../pipelines/parent_child_pipelines.md#dynamic-child-pipelines):
-
-```yaml
-generate-config:
-  stage: build
-  script: generate-ci-config > generated-config.yml
-  artifacts:
-    paths:
-      - generated-config.yml
-
-child-pipeline:
-  stage: test
-  trigger:
-    include:
-      - artifact: generated-config.yml
-        job: generate-config
-```
+**Additional details**:
 
-The `generated-config.yml` is extracted from the artifacts and used as the configuration
-for triggering the child pipeline.
+- Jobs with `trigger` can only use a [limited set of keywords](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file).
+  For example, you can't run commands with [`script`](#script), [`before_script`](#before_script),
+  or [`after_script`](#after_script).
+- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you
+  can use [`when:manual`](#when) in the same job as `trigger`. In GitLab 13.4 and
+  earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`.
+- In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can
+  view which job triggered a downstream pipeline in the [pipeline graph](../pipelines/index.md#visualize-pipelines).
 
-##### Trigger child pipeline with files from another project
+**Related topics**:
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205157) in GitLab 13.5.
+- [Multi-project pipeline configuration examples](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file).
+- [Child pipeline configuration examples](../pipelines/parent_child_pipelines.md#examples).
+- To force a rebuild of a specific branch, tag, or commit, you can
+  [use an API call with a trigger token](../triggers/index.md).
+  The trigger token is different than the `trigger` keyword.
 
-To trigger child pipelines with files from another private project under the same
-GitLab instance, use [`include:file`](#includefile):
+#### `trigger:strategy`
 
-```yaml
-child-pipeline:
-  trigger:
-    include:
-      - project: 'my-group/my-pipeline-library'
-        ref: 'main'
-        file: '/path/to/child-pipeline.yml'
-```
-
-#### Linking pipelines with `trigger:strategy`
+Use `trigger:strategy` to force the `trigger` job to wait for the downstream pipeline to complete
+before it is marked as **success**.
 
-By default, the `trigger` job completes with the `success` status
-as soon as the downstream pipeline is created.
+This behavior is different than the default, which is for the `trigger` job to be marked as
+**success** as soon as the downstream pipeline is created.
 
-To force the `trigger` job to wait for the downstream (multi-project or child) pipeline to complete, use
-`strategy: depend`. This setting makes the trigger job wait with a "running" status until the triggered
-pipeline completes. At that point, the `trigger` job completes and displays the same status as
-the downstream job.
+This setting makes your pipeline execution linear rather than parallel.
 
-This setting can help keep your pipeline execution linear. In the following example, jobs from
-subsequent stages wait for the triggered pipeline to successfully complete before
-starting, which reduces parallelization.
+**Example of `trigger:strategy`**:
 
 ```yaml
 trigger_job:
@@ -3959,14 +3872,8 @@ trigger_job:
     strategy: depend
 ```
 
-#### Trigger a pipeline by API call
-
-To force a rebuild of a specific branch, tag, or commit, you can use an API call
-with a trigger token.
-
-The trigger token is different than the [`trigger`](#trigger) keyword.
-
-[Read more in the triggers documentation.](../triggers/index.md)
+In this example, jobs from subsequent stages wait for the triggered pipeline to
+successfully complete before starting. 
 
 ### `interruptible`
 
@@ -4109,7 +4016,7 @@ deployment:
   script: echo "Deploying..."
 ```
 
-You must define [`strategy: depend`](#linking-pipelines-with-triggerstrategy)
+You must define [`strategy: depend`](#triggerstrategy)
 with the `trigger` keyword. This ensures that the lock isn't released until the downstream pipeline
 finishes.