Okay, here’s a basic GitLab CI/CD YAML example that demonstrates how the trigger configuration option is used, focusing on creating parent-child pipelines within the same project. This is a common way to break down complex CI/CD logic into more manageable pieces.

The trigger keyword allows a job in your main .gitlab-ci.yml (the parent pipeline) to initiate a new, separate pipeline (the child pipeline) based on another YAML file within the same project or even in a different project (multi-project pipelines).

Example Files:

You’ll need two YAML files in your repository for this example:

1. .gitlab-ci.yml (The main/parent pipeline configuration)
2. .child-pipeline.yml (The configuration for the child pipeline)

File 1: .gitlab-ci.yml (Parent Pipeline)

YAML

# .gitlab-ci.yml

stages:
  - setup
  - build_and_trigger
  - deploy # This stage might run jobs from the parent or child

default:
  image: alpine:latest

# A regular job in the parent pipeline
prepare_environment:
  stage: setup
  script:
    - echo "--- Parent Pipeline: Preparing Environment ---"
    - export PARENT_VARIABLE="Hello from Parent"
    - echo "Parent variable set."

# This job triggers a child pipeline defined in another YAML file
trigger_build_services_pipeline:
  stage: build_and_trigger
  # 'trigger' keyword starts the definition for a downstream pipeline
  trigger:
    include: '.child-pipeline.yml' # Path to the child pipeline's YAML configuration in THIS project
    strategy: depend # The trigger job will mirror the status of the child pipeline.
                     # If the child pipeline succeeds, this job succeeds. If it fails, this job fails.
    forward_pipeline_variables: true # Forwards predefined CI variables (like CI_COMMIT_REF_NAME) to the child.
    forward_yaml_variables: true # Forwards variables defined in this parent YAML (like PARENT_VARIABLE if it was global or job level)
                                  # Note: For variables defined in the 'script' like PARENT_VARIABLE above,
                                  # you'd typically pass them explicitly using 'trigger:variables:'.
  variables: # Explicitly pass variables to the child pipeline
    PASSED_FROM_PARENT: "This data comes from the trigger job"
    ANOTHER_PARENT_VAR: "Value_XYZ"
  script: # This script runs BEFORE the trigger actually happens.
    - echo "--- Parent Pipeline: About to trigger child pipeline for building services ---"
    - echo "This job will now trigger and wait for .child-pipeline.yml"

# Another job in the parent pipeline that might run after the trigger job (if strategy:depend is used)
# or in parallel if it's in the same stage and doesn't depend on the trigger job.
parent_final_step:
  stage: deploy
  needs: ["trigger_build_services_pipeline"] # Make this explicitly depend on the trigger job
  script:
    - echo "--- Parent Pipeline: Final Step ---"
    - echo "This runs after the child pipeline (triggered by 'trigger_build_services_pipeline') completes successfully."

Code language: PHP (php)

File 2: .child-pipeline.yml (Child Pipeline Configuration)

YAML

# .child-pipeline.yml

# This file defines the jobs that will run in the child pipeline.
# It can have its own stages, jobs, variables, etc.

default:
  image: alpine:latest

stages:
  - build_child
  - test_child

variables:
  CHILD_PIPELINE_VAR: "Specific to Child Pipeline"

build_service_a:
  stage: build_child
  script:
    - echo "--- Child Pipeline: Building Service A ---"
    - echo "Accessing variable passed from parent: $PASSED_FROM_PARENT"
    - echo "Accessing another parent var: $ANOTHER_PARENT_VAR"
    - echo "Accessing child-specific variable: $CHILD_PIPELINE_VAR"
    - echo "Accessing forwarded predefined variable (e.g., branch): $CI_COMMIT_REF_NAME"
    - sleep 10
    - echo "Service A built."
  artifacts:
    paths:
      - service_a.txt
    expire_in: 1 hour

test_service_a:
  stage: test_child
  needs: ["build_service_a"] # Child pipeline can also use 'needs'
  script:
    - echo "--- Child Pipeline: Testing Service A ---"
    - if [ -f "service_a.txt" ]; then echo "Artifact from child build_service_a found."; else echo "Artifact NOT found!"; exit 1; fi
    - sleep 5
    - echo "Service A tests passed."

Code language: PHP (php)

Explanation:

1. trigger: Keyword (in .gitlab-ci.yml):
   • Used within a job (trigger_build_services_pipeline in this case) to initiate a downstream (child) pipeline.
   • include: '.child-pipeline.yml':
     • This specifies that the child pipeline’s configuration is defined in the .child-pipeline.yml file located in the same project and same Git ref (branch/commit) as the parent pipeline. This is the core of a “parent-child pipeline.”
   • strategy: depend:
     • (Optional, but very common) This makes the parent trigger job (trigger_build_services_pipeline) wait for the entire child pipeline to complete.
     • The status of the trigger job will then mirror the status of the child pipeline. If the child pipeline succeeds, the trigger job succeeds. If the child pipeline fails, the trigger job fails.
     • Without strategy: depend (or if set to strategy: none), the trigger job would be marked as successful as soon as it successfully initiates the child pipeline, without waiting for it to finish.
   • forward_pipeline_variables: true:
     • (Optional) Forwards most of the predefined CI/CD variables (like CI_COMMIT_SHA, CI_COMMIT_REF_NAME, CI_PROJECT_DIR, etc.) from the parent pipeline to the child pipeline.
   • forward_yaml_variables: true:
     • (Optional) Forwards variables defined in the parent YAML (global variables: block or job-level variables: block of the trigger job) to the child pipeline.
     • Note: Variables set dynamically within a script block of the trigger job (like PARENT_VARIABLE in prepare_environment) are not automatically forwarded by this. For those, you need to pass them explicitly.
   • variables: (under trigger:):
     • This block allows you to explicitly pass new variables or override existing ones to the child pipeline.
     • PASSED_FROM_PARENT: "This data comes from the trigger job": This variable will be available in all jobs of the triggered child pipeline.
   • script: (in the trigger job):
     • Any commands in the script section of the trigger job are executed before the downstream pipeline is actually triggered. This can be used for setup or logging.
2. .child-pipeline.yml (Child Pipeline):
   • This is a standard GitLab CI/CD YAML file. It defines its own stages, jobs, variables, etc.
   • It runs in the context of the same project, commit, and Git ref as the parent pipeline that triggered it.
   • Accessing Variables: Jobs in the child pipeline (like build_service_a) can access:
     • Variables explicitly passed via trigger:variables: (e.g., $PASSED_FROM_PARENT).
     • Forwarded predefined variables (if forward_pipeline_variables: true).
     • Forwarded YAML variables from the parent (if forward_yaml_variables: true).
     • Its own globally or job-level defined variables (e.g., $CHILD_PIPELINE_VAR).
   • Artifacts in Child Pipeline: Jobs in the child pipeline can produce artifacts. These artifacts are scoped to the child pipeline. If the parent pipeline (or other pipelines) needs these, you would typically use needs: with project and job attributes to fetch artifacts from a completed child pipeline job (this is more of an advanced multi-project artifact passing scenario). For parent-child, if strategy: depend is used, the trigger job itself can have artifacts from the child if the child pipeline is configured to produce artifacts that are then “passed up” (this is a more nuanced behavior that depends on GitLab version and configuration). Usually, artifacts from the child are used within the child pipeline itself or by downstream multi-project pipelines.

Key Concepts and Benefits:

• Modularity: Break down a very large, monolithic .gitlab-ci.yml into smaller, more focused YAML files. This improves readability and maintainability.
• Reusability: Child pipeline configurations can potentially be reused or triggered by multiple parent pipelines or different trigger jobs.
• Dynamic Pipeline Generation: You can dynamically choose which child pipeline to trigger based on conditions in the parent.
• Isolation: Child pipelines can have their own stages and flow, providing some level of isolation.
• Multi-Project Pipelines (Brief Mention):
  • Instead of trigger:include:, you can use trigger:project: 'namespace/another-project' and trigger:branch: 'some-branch' to trigger a pipeline in a completely different GitLab project. This is useful for microservice architectures or when coordinating deployments across multiple repositories.

How it Looks in the UI:

• The trigger job in the parent pipeline will show a link to the downstream (child) pipeline.
• If strategy: depend is used, the trigger job will remain in a “running” state until the child pipeline completes, and then its status will reflect the child’s status.

Using trigger for parent-child pipelines is a great way to manage complexity as your CI/CD processes grow.