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.
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.
> - [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),
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.
