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

Multi-project pipelines

Modern alternative to trigger tokens

Launch pipeline in separate project

Use the trigger keyword

Example

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

trigger.branch is optional

Parent-child pipelines

Child pipeline can be made from multiple files

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 1: 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 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

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

Pro tip: Artifacts from parent pipeline

Requires Enterprise Edition Premium

Generate artifact and trigger child 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
  variables:
    PARENT_PIPELINE_ID: $CI_PIPELINE_ID

Fetch artifact from parent pipeline

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

Pro tip: 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