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.

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 for the relevant jobs.

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.

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.

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

In GitLab 15.9 and later, 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:

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