Skip to main content
Mapagam

Using Job Triggers and Child Pipelines

1. Creating Pipeline Triggers

Property Description Example
trigger Defines a pipeline trigger job in the CI/CD configuration trigger:
project The path to the project that will be triggered project: "group/subproject"
branch The branch to trigger the pipeline on branch: "main"
strategy Strategy for triggering pipelines (default: web) strategy: "web"

Example: Basic Pipeline Trigger Configuration

trigger_pipeline:
  trigger:
    project: "group/subproject"
    branch: "main"
  only:
    - master
Note: Pipeline triggers require appropriate permissions to access the target project.
Warning: Ensure that the project path is correctly specified to avoid pipeline failures.

2. Triggering Child Pipelines

Property Description Example
trigger Defines a child pipeline to be triggered from the current job trigger:
project Path to the child pipeline's project project: "group/subgroup/project"
branch Branch to run the child pipeline on branch: "main"
strategy Strategy to use when triggering child pipelines strategy: "none"

Example: Triggering a Child Pipeline

trigger_child_pipeline:
  trigger:
    project: "group/subgroup/child-project"
    branch: "main"
    strategy: "none"
Note: The child pipeline will inherit the variables and environment of the parent pipeline.
Warning: Ensure that the child project has proper access permissions to be triggered by the parent pipeline.

3. Using Trigger Strategies

Strategy Description Use Case Notes
pipeline trigger Triggers a new pipeline in another project or group Multi-project workflows, cross-repository builds Requires trigger job in the target project
child pipeline Creates a new pipeline from within a running pipeline Modular CI/CD, conditional execution Uses trigger or workflow rules
manual trigger Requires manual approval before pipeline execution Release workflows, security checks Enabled via manual in job definition
scheduled trigger Automatically starts a pipeline at a set time or interval Regular maintenance, nightly builds Configured using scheduled in .gitlab-ci.yml

Example: Pipeline Trigger Configuration

trigger_job:
  trigger:
    project: "group/subgroup/project"
    branch: "main"
    strategy: "pipeline"

Example: Manual Trigger Job

manual_deploy:
  script:
    - echo "Deploying to production"
  when: manual
  allow_failure: false
Note: Pipeline triggers can be secured using token or secret variables to prevent unauthorized access.
Warning: Child pipelines inherit the environment variables and context from their parent pipeline, which can lead to unintended side effects.

4. Passing Variables to Triggered Pipelines

Variable Type Description Default Value
CI_PIPELINE_SOURCE string Source of the pipeline trigger (e.g., pipeline, web) pipeline
CI_PIPELINE_TRIGGER_TOKEN string Token used to authenticate the pipeline trigger None
CI_PIPELINE_ID number ID of the parent pipeline that triggered this one None

Example: Triggering a Pipeline with Variables

curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
     --request POST \
     --form "variables[ENVIRONMENT]=staging" \
     --form "variables[DEPLOY_VERSION]=v1.2.3" \
     "https://gitlab.example.com/api/v4/projects/123/pipeline/trigger"
Note: Variables passed via --form are accessible in the child pipeline as $ENVIRONMENT and $DEPLOY_VERSION.

5. Using Forward Variables

Forward variables allow you to pass variables from a parent pipeline to a child pipeline when using trigger jobs. These variables are defined in the parent pipeline and can be accessed in the child pipeline's context.

Variable Description Usage
trigger Defines a job that triggers a child pipeline trigger: section in the job configuration
forward_variables Lists variables to forward from parent to child pipeline forward_variables: under trigger:

Example: Forwarding Variables in a Trigger Job

job1:
  trigger:
    project: "group/subgroup/project"
    forward_variables:
      - CI_COMMIT_SHA
      - CI_COMMIT_REF_NAME
Note: Variables forwarded must be defined in the parent pipeline's environment or explicitly set using variables:.
Warning: Forwarded variables are not automatically available in the child pipeline's variables: section. They must be explicitly referenced or used in the child pipeline's configuration.

Child pipelines can access forwarded variables using the $VAR_NAME syntax, just like any other variable in GitLab CI/CD.

Variable Name Type Description
CI_COMMIT_SHA String Full commit SHA of the triggering job
CI_COMMIT_REF_NAME String Name of the branch or tag that triggered the pipeline

6. Creating Parent-Child Pipelines

Parent-child pipelines in GitLab CI/CD allow you to trigger a pipeline from another pipeline, creating a hierarchical structure of pipelines. This is useful for modularizing your CI/CD process and managing complex workflows.

Property Description Example
trigger Defines a child pipeline to be triggered from the parent pipeline. trigger:
project The project path to trigger the pipeline in. project: "group/subgroup/project"
pipeline The pipeline to trigger (e.g., branch, tag, or ref). pipeline: "main"
strategy Strategy for triggering child pipelines. Default is depends_on. strategy: "depends_on"

Example: Triggering a Child Pipeline

trigger_child_pipeline:
  trigger:
    project: "group/subgroup/project"
    pipeline: "main"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
Note: The child pipeline will inherit the variables and environment from the parent pipeline unless overridden.
Warning: Ensure that the project path is correct and accessible to the parent pipeline's runner.

Key Points

  • Use trigger to define a child pipeline in the parent pipeline configuration.
  • The project field specifies where to trigger the child pipeline.
  • The pipeline field defines the branch or tag to run the child pipeline on.
  • Child pipelines can be triggered conditionally using rules.

7. Triggering via API

GitLab CI/CD allows triggering pipelines via the GitLab API. This is useful for automating pipeline execution from external systems or scripts.

Field Description Example
token Project access token with api scope glpat-xxxxxxxxx
ref Branch, tag, or commit SHA to run the pipeline on main
variables Optional variables to pass to the pipeline {"VAR1": "value1"}

Example: Triggering a Pipeline via API

curl --request POST \
  --url "https://gitlab.example.com/api/v4/projects/123/pipeline" \
  --header "PRIVATE-TOKEN: glpat-xxxxxxxxx" \
  --form "ref=main" \
  --form "variables[VAR1]=value1"
Note: The project ID must be replaced with the actual project ID in GitLab.
Warning: Ensure that the access token has sufficient permissions to trigger pipelines.

8. Using Trigger Rules

Rule Description Example
only Specifies when a job should run based on the source of the pipeline. 
only:
  - master
  - develop
except Specifies when a job should not run based on the source of the pipeline. 
except:
  - tags
changes Runs the job only if files matching a pattern have changed. 
changes:
  - src/**/*
  - tests/**/*
variables Conditionally runs a job based on the value of a CI/CD variable. 
variables:
  ENV: production
only:
  variables:
    $ENV == "production"

Example: Using Trigger Rules in a Pipeline

trigger_job:
  trigger:
    project: my-group/my-project
    branch: main
  only:
    - master
  except:
    - tags
Note: Trigger rules can be combined with other conditions like changes or variables to create more complex logic.

9. Waiting for Child Pipeline

Example: Wait for child pipeline completion

wait_for_child:
  stage: deploy
  trigger:
    project: "my-group/my-project"
    branch: "main"
  dependencies:
    - build
  only:
    - main
Property Description Values
trigger Specifies the child pipeline to wait for project, branch, strategy
dependencies Lists jobs that must complete before this job starts List of job names
only Restricts when this job runs List of branches or tags
Note: The trigger keyword is used to define a child pipeline. The dependencies key ensures that the parent job waits for the specified jobs to finish before starting.
Warning: If the child pipeline fails, the parent job will also fail unless configured otherwise.

10. Debugging Trigger Issues

Example: Trigger Job Configuration

trigger_job:
  trigger:
    include:
      - artifact: "build.tar.gz"
        job: "build"
  rules:
    - if: $CI_PIPELINE_SOURCE == "web"
Issue Description Solution
Missing artifact Child pipeline fails due to missing artifact from parent job Ensure artifact is defined in parent job with correct path
Incorrect trigger syntax Malformed trigger: configuration Validate YAML structure and use correct syntax per GitLab version
Permission denied Triggering pipeline lacks required permissions Verify user or token has pipeline scope in project
Note: Use CI_PIPELINE_SOURCE == "web" to identify manual trigger invocations.
Warning: Triggers do not inherit variables from the parent pipeline unless explicitly passed.

Common Debugging Steps

  • Check job logs for trigger errors
  • Verify artifact paths match between parent and child pipelines
  • Confirm trigger token or project access rights
  • Validate rules conditions for trigger job activation

Was this article helpful?

Related Cheat Sheets