Chain file keys

Waiting for a pipeline by ID

How a ci.pipeline task waits for one CI pipeline named by its ID, what each pipeline state makes the task do, and what it never does.

Added in 2.6

A ci.pipeline task waits for one CI pipeline, named by its ID, and nothing else. It isn't tied to the item's branch or merge request, so it can follow a pipeline that something else started, such as one a merge triggered.

The ID is a GitLab pipeline id (not the iid) or a GitHub Actions run ID (not the run_number). Give it as digits, or as $NAME for a variable an earlier task left with outputs and this task names in reads.

- id: release
  steps:
    - id: find
      tasks:
        - id: find_pipeline
          kind: subprocess
          command: ./scripts/find-pipeline.sh    # your own script, not Kraft's
          outputs:
            variables: [PIPELINE_ID]
    - id: wait
      tasks:
        - id: wait_pipeline
          kind: forge
          target: ci.pipeline
          reads: [find.find_pipeline]
          pipeline: $PIPELINE_ID

The task looks up $NAME again at every check, so a writer that ran again while the wait was parked is followed to its new ID, and the old wait ends as superseded. An unset variable, a value that isn't digits, or an ID the repository doesn't hold stops the item for you with a message that never quotes the value. On GitHub a run that a person re-runs keeps its id: the task follows the newest attempt.

What the forge reportsWhat the task does
SuccessDone.
Created, pending, running, queued or waiting for a runnerKeeps waiting.
A manual job (GitLab) or an environment approval (GitHub) holds itKeeps waiting until the time cap, and says which job or approval in the log and the wait's events.
Failed jobs, or a failed downstream pipelineThe task fails, with the failed jobs as findings.
Failed with no failed job, or a GitHub startup failureStops the item for you, naming it.
Skipped, neutral or stale, or ran no jobStops the item for you. A pipeline that ran nothing isn't green.
Cancelled, and no new run followed within five minutesStops the item for you.
The time capStops the item as a timed-out wait.
The forge can't be reachedKeeps waiting.
The forge refuses the token, or answers a rate limitStops as any forge task does.
  • It never retries a job. The ID may come from a worker, and a retry is a write made with the server's token. A pipeline that failed on the forge's own infrastructure stops the item for you instead.
  • A red pipeline isn't stuck. The node's on_failure handles it when it has one. Otherwise the item stops for you as a plain failure, and neither the node's escalation nor auto_escalate_stuck sends an agent onto it, because the merge request has usually merged by then. No fix loop starts unless the node declares one.
  • Green is the pipeline's own status. A downstream pipeline counts only through strategy: depend in the GitLab trigger job: a failed bridge is red code, not infrastructure. mr.ci reads it the same way now.
  • ci_checks: false doesn't affect it. You named the pipeline.
  • A run from a fork is a configuration error, as is a pipeline of another project.
  • It can't be scope: each_repository. In a workspace item it reads the root repository only; a pipeline in a member's project answers not found.
  • A node whose only forge tasks are ci.pipeline isn't a merge-request node, so a merge request closed on the forge doesn't stop it. A chain revision may skip such a node, which it may not do for the other forge tasks. A revision that skips a writer whose reader stays is refused, with the reader's reads named.
  • The kraft-lite plugin refuses ci.pipeline.
Copyright © 2026