Triggers

Trigger other pipelines

Ability to split automation across multiple pipeline

Trigger tokens

Trigger pipelines through the API

Fire and forget

Multi-project pipelines

Launch pipeline in separate project

Use the trigger keyword

Parent-child pipelines

Load stages and jobs from a file using include

Nomenclature

The preceding pipeline is upstream

The following pipeline is downstream

The pipeline triggering you is the upstream pipeline

The pipeline you trigger is the downstream pipeline

Relationship between pipelines in the above picture:

• Pipeline 1 is upstream of pipeline 2
• Pipeline 2 is downstream of pipeline 1
• Pipeline 2 is upstream of pipeline 3
• Pipeline 3 is downstream of pipeline 2

Heads-up for trigger tokens

Visibility of trigger tokens

Users sees only their own tokens

Tokens of other users are hidden

Branch protection can prevent triggers

Trigger owner must be able to either…

• Push to a branch
• Merge into a branch

Fire and forget

Unable to check pipeline status

Multi-project pipelines

Modern alternative to trigger tokens

Launch pipeline in separate project

Use the trigger keyword

Examples

Trigger a pipeline in another project:

job_name:
  trigger:
    project: <path-to-project>

Specify the branch to use:

job_name:
  trigger:
    project: <path-to-project>
    branch: main

Parent-child pipelines

Child pipelines are created from a file using include

include supports local for files in the same repository

Use project/ref/file for files in other repositories

Example

job_name:
  trigger:
    include: <relative-path-to-file>

job_name2:
  trigger:
    include:
    - project: <path-to-project>
      ref: main
      file: <relative-path-to-file>

File must match /\.ya?ml$/

Hands-On

See chapter Triggers

Pro tip 2: Wait for downstream pipeline

Upstream pipeline only waits for successful trigger

Wait for successul downstream pipeline using strategy

job_name:
  trigger:
    include: child.yaml
    strategy: depend

Useful when triggering the pipeline of a dependency

Pro tip 1: Artifacts from parent pipeline

Requires Enterprise Edition Premium

Generate artifact and trigger child pipeline

Fetch artifact from parent pipeline

build_artifacts:
  stage: build
  script: echo "This is a test artifact!" >> artifact.txt
  artifacts:
    paths:
    - artifact.txt

deploy:
  stage: deploy
  trigger:
    include:
    - local: path/to/child-pipeline.yml

test:
  stage: test
  script: cat artifact.txt
  needs:
  - pipeline: $UPSTREAM_PIPELINE_ID
    job: build_artifacts

This works for dotenv reports as well

needs:project requires Premium subscription

Pro tip 2: Variable inheritence

Downstream pipelines inherit some variables

Job variables are passed on unless:

job_name:
  inherit:
    variables: false

Predefined variables must be redefined as job variables:

job_name:
  variables:
    my_var: ${CI_COMMIT_REF_NAME}
  trigger:
    #...

Do not redefined masked variables - they will not be masked

Pro tip 3: Do not pass global variables

Only allow job variables to be passed to downstream pipelines:

variables:
  GLOBAL_VAR: value

trigger-job:
  inherit:
    variables: false
  variables:
    JOB_VAR: value
  trigger:
    include:
    - local: path/to/child-pipeline.yml

Pro tip 4: Types of variables to forward

Use trigger:forward to define which types of variables to forward to downstream pipelines

• yaml_variables - variables defined in the trigger job
• pipeline_variables - variables passed to this pipeline

This only works for the direct downstream pipeline

Pro tip 5: Permissions for include

When including a file from another project…

job_name:
  trigger:
    include:
    - project: <path-to-project>
      ref: main
      file: <relative-path-to-file>

…the user must have the permission to run a pipeline in the other project

Pro tip 6: Dynamic includes

Included file can also be generated before job start

generate:
  script:
  - |
    cat <<EOF >child.yaml
    test:
      script:
      - printenv
    EOF
  artifacts:
    paths:
    - child.yaml

use:
  trigger:
    include:
    - artifact: child.yaml
      job: generate