Troubleshooting downstream pipelines

Trigger job fails and does not create multi-project pipeline

With multi-project pipelines, the trigger job fails and does not create the downstream pipeline if:

  • The downstream project is not found.
  • The user that creates the upstream pipeline does not have permission to create pipelines in the downstream project.
  • The downstream pipeline targets a protected branch and the user does not have permission to run pipelines against the protected branch. See pipeline security for protected branches for more information.

To identify which user is having permission issues in the downstream project, you can check the trigger job using the following command in the Rails console and look at the user_id attribute.

ruby 
Ci::Bridge.find(<job_id>)

Job in child pipeline is not created when the pipeline runs

If the parent pipeline is a merge request pipeline, the child pipeline must use workflow:rules or rules to ensure the jobs run.

If no jobs in the child pipeline can run due to missing or incorrect rules configuration:

  • The child pipeline fails to start.
  • The parent pipeline’s trigger job fails with: downstream pipeline can not be created, the resulting pipeline would have been empty. Review therulesconfiguration.

Variable with $ character does not get passed to a downstream pipeline properly

You cannot use $$ to escape the $ character in a CI/CD variable, when passing a CI/CD variable to a downstream pipeline. The downstream pipeline still treats the $ as the start of a variable reference.

You can Prevent CI/CD variable expansion when configuring a variable in the UI, or use the variables:expand keyword to set a variable value to not be expanded. This variable can then be passed to the downstream pipeline without the $ being interpreted as a variable reference.

Variable in a trigger:include path is empty or has an unexpected value

CI/CD variables in a trigger:include path do not expand in the trigger job. The path is passed as a string with the unexpanded variable to the process that generates the child pipeline. Then the expansion happens in the context of the child pipeline.

As a result:

  • Variables from the pipeline configuration can only be used in the trigger:include path when they are forwarded to the child pipeline. This includes default variables and the trigger job’s own variables. If the trigger job uses trigger:forward with yaml_variables: false, any variables in the path cannot expand and evaluate to an empty string. Project, group, and instance CI/CD variables are not affected, as they are available in both contexts.
  • Predefined variables hold the values of the child pipeline. For example, $CI_PIPELINE_SOURCE is parent_pipeline from the child pipeline, not the pipeline source for the parent pipeline.
  • Variables scoped to an environment resolve to their unscoped value, because the child pipeline has no environment.

To avoid this behavior, use inputs with $[[ inputs.name ]] interpolation instead of a CI/CD variable. Interpolation is resolved before the configuration is processed.

Ref is ambiguous

You cannot trigger a multi-project pipeline with a tag when a branch exists with the same name. The downstream pipeline fails to create with the error: downstream pipeline can not be created, Ref is ambiguous.

Only trigger multi-project pipelines with tag names that do not match branch names.

Trigger job fails with data integrity failure

This error indicates an unexpected exception during job processing. For causes and resolution steps, see error: data integrity failure.

403 Forbidden error when downloading a job artifact from an upstream pipeline

CI/CD job tokens are scoped to the project that the pipeline executes under. Therefore, the job token in a downstream pipeline cannot be used to access an upstream project by default.

To resolve this, add the downstream project to the job token scope allowlist.

Error: needs:need pipeline should be a string

When using needs:pipeline:job with dynamic child pipelines, you might receive this error:

Unable to run pipeline
- jobs:<job_name>:needs:need pipeline should be a string

This error occurs when a pipeline ID is parsed as an integer instead of a string. To fix this, enclose the pipeline ID in quotes:

yaml 
rspec:
  needs:
    - pipeline: "$UPSTREAM_PIPELINE_ID"
      job: dependency-job
      artifacts: true