When a merge request's pipeline never starts

At the merge stage, the agent checks the pipeline on the request’s current head commit. Most red pipelines have a failed job to trace. Some never create any jobs. This page covers that case. The merge-stage agent reads it with ch support show ci-triage. You can run the same command.

A pipeline with zero jobs

A red or cancelled pipeline with no jobs means your code never ran. The git host refused to create the jobs. On GitLab, this can happen when the project reaches its active-job limit.

The REST pipeline resource often shows no yaml_errors and no failure_reason for this case. Retrying the pipeline gives another empty pipeline. A retry does not create jobs.

Step 1: Find the real cause

If the REST resource shows zero jobs and no error fields, ask the GraphQL API. It reports failureReason:

query {
  project(fullPath: "<namespace>/<project>") {
    pipeline(iid: <pipelineIid>) {
      id
      status
      yamlErrors
      failureReason
    }
  }
}

<pipelineIid> is the pipeline’s own project-local number. It differs from the merge request’s number. It also differs from the pipeline’s global id, which the retry endpoint takes. Read it from the iid field of GET projects/:id/pipelines/:pipeline_id. Keep these numbers apart, and keep the commit SHA you track apart from all of them.

A capacity refusal often reads like this: “The pipeline job activity limit was exceeded.”

Step 2: Classify it

• Configuration defect. yamlErrors is not empty, or failureReason describes the pipeline definition. This is a real source problem. Fix it and push. Or send the task back to code, and quote the exact text.
• Admission or capacity refusal. The host refused to create jobs. This is not a code defect. Leave the diff alone. Do not send the task back to code. Go to step 3.

Step 3: Wait, then recreate

Use this for capacity refusals only. The host does not enforce these bounds. The policy sets them so the wait ends. Stay in the same merge-stage session. Do not end it just to check again later.

• Wait. Wait at least 2 minutes before the first recheck. If the refusal continues, roughly double the wait each time. Never wait more than 10 minutes between checks. Stop waiting after 30 minutes in total. Rapid polling spends the capacity you are waiting for.
• Recreate. After the 30 minutes, if the refusal persists, create a new pipeline. On GitLab, use POST /projects/:id/merge_requests/:iid/pipelines. Do not use POST .../pipelines/:id/retry. It replays the same empty job set. Recreate at most twice. Space the two attempts by the same backoff, never back to back.
• Cancel with care. Cancel only an older pipeline of the same request that a newer head has replaced, and only if you have the right to cancel it. Never cancel an unrelated validation pipeline. Never cancel a protected release or deploy pipeline. Never cancel a pipeline only because it looks old.

The steps name GitLab endpoints. On another git host, use that host’s equivalent call to create a pipeline.

Step 4: Escalate

After the full wait and both recreations, stop retrying. Raise it with ch agent ask. Name the current commit SHA, the pipeline id and iid, and the exact cause text. Do not loop the task back to code. The code is not the cause, so it fails the same way each time.

What you can do

The agent’s question or note appears where you see agent input. See When an agent needs your input for where to find it and how to answer.

The fix sits on the git-host side. Free some CI capacity, or raise the project’s job limit in GitLab. Then answer the agent so it can recreate the pipeline. If a task stays at the merge stage, Why isn’t my task moving? lists other causes.

Related guides

• When an agent needs your input — how questions and notes reach you
• Why isn’t my task moving? — diagnose a stuck task
• How work flows — the stages, including merge