Chained pipeline

A Chained pipeline stage runs another Harness pipeline as a stage within the current pipeline.

A Chained pipeline stage runs a separate Harness pipeline, the child pipeline, as a single stage inside the current (parent) pipeline. The child pipeline executes in full: all its stages, steps, and logic run as if triggered directly. The chained stage passes or fails based on the child pipeline's final status.

You can chain the same child pipeline multiple times in a parent, for example, to deploy to different environments in sequence using the same reusable pipeline.

What you will learn

• What a chained pipeline stage is and when to use one

• How to create a chained stage and pass inputs to a child pipeline

• How to read outputs from a child pipeline back into the parent pipeline

• How Harness resolves remote Git-stored child pipelines

• How looping strategies apply to chained stages

When to use chained pipeline stages

• You have a reusable pipeline (for example, a standard test suite or a compliance scan) that multiple parent pipelines need to call

• Your deployment process is too complex for a single pipeline and you want to break it into composable sub-pipelines

• You want to enforce a common pipeline as a required gate; chaining it ensures it always runs in its entirety

• You need to pass data from a parent pipeline into a child pipeline, or read outputs from the child back in the parent

Limitations

• Nested chaining is not supported. A child pipeline cannot itself contain chained pipeline stages.

• Artifacts, test results, and logs from the child pipeline live in the child pipeline's execution history, not the parent's.

• Pre-flight checks skip child pipeline validation during manual runs of the parent.

• Auto-suggested expressions are supported in the Inputs tab of the chained stage, but not in the Outputs tab.

• Runtime input changes in child pipelines require opening the Inputs section in the parent to pick up the updates.

Create a chained pipeline stage

To add a Chained pipeline stage:

1. On the pipeline canvas, select + to add a stage.

2. In the Add stage panel, select Chained pipeline.

3. Select the pipeline you want to chain from the pipeline selector. You can select pipelines from any org or project in your account that you have read access to.

4. Configure any inputs the child pipeline requires.

5. Select Add stage.

You can add multiple chained pipeline stages in the same parent pipeline, including chaining the same child pipeline more than once with different inputs.

YAML

In YAML, a chained pipeline stage uses the chain key. The uses field references the child pipeline using the full org/project/pipeline_id path:

pipeline:
  id: parent_pipeline
  name: Parent Pipeline
  stages:
    - name: deploy-to-staging
      id: deploy_to_staging
      chain:
        uses: my-org/my-project/child_pipeline
        with:
          inputs:
            env: staging

    - name: deploy-to-production
      id: deploy_to_production
      chain:
        uses: my-org/my-project/child_pipeline
        with:
          inputs:
            env: production
  clone:
    enabled: false

Pass inputs to a child pipeline

If the child pipeline defines inputs, you pass values for them under chain.with.inputs in the parent. The input names must match exactly what the child pipeline defines.

Child pipeline: defines an env input:

pipeline:
  id: child_pipeline
  name: Child Pipeline
  inputs:
    env:
      type: string
      default: dev
      desc: Target environment
  stages:
    - name: run
      id: run
      steps:
        - name: print-env
          id: print_env
          run:
            script: echo "Deploying to ${{ inputs.env }}"
  clone:
    enabled: false

Parent pipeline: passes a value for env:

pipeline:
  id: parent_pipeline
  name: Parent Pipeline
  stages:
    - name: chain-stage
      id: chain_stage
      chain:
        uses: my-org/my-project/child_pipeline
        with:
          inputs:
            env: production
  clone:
    enabled: false

You can also pass a pipeline-level expression instead of a fixed value:

with:
  inputs:
    env: ${{ inputs.target_env }}

Read outputs from a child pipeline

To read a value produced by the child pipeline back in the parent, map it using chain.with.outputs. Each output entry has a name (what you call it in the parent) and a value (an expression referencing the child pipeline's output):

chain:
  uses: my-org/my-project/child_pipeline
  with:
    outputs:
      - name: image_tag
        value: ${{ stages.run.outputs.image_tag }}

Reference the mapped output in a subsequent parent stage:

${{ stages.chain_stage.outputs.image_tag }}

The child pipeline must fully complete before its outputs are available to downstream stages in the parent.

Go to Output variables with chained pipelines to review the full reference.

Re-run chained pipelines

When you re-run a parent pipeline that has a failed chained stage, Harness re-executes only the failed stage inside the child pipeline, not the entire child pipeline from the start. This preserves successful work and reduces re-run time.

Remote chained pipelines

When the parent and child pipelines are stored in remote Git repositories, Harness resolves the child using these rules:

Parent	Child	Branch used for child
Inline	Remote	Child's default branch
Remote	Inline	Parent's branch; child resolved inline
Remote (same repo)	Remote (same repo)	Same branch as parent
Remote (different repo)	Remote (different repo)	Child's default branch

Loop strategies

You can apply a matrix, for loop, or while loop looping strategy to a chained pipeline stage to run the same child pipeline multiple times with different inputs.

Looping strategies on chained pipeline stages require the feature flags PIPE_ENABLE_STRATEGY_FOR_CHAINED_PIPELINES and PIPE_POPULATE_STEP_DETAILS_IN_RUNTIME_ID_FOR_STRATEGY_CHILD_NODES. Contact Harness Support to enable them.

Example: deploy to multiple environments using a matrix:

- name: deploy
  id: deploy
  chain:
    uses: my-org/my-project/child_pipeline
    with:
      inputs:
        env: ${{ matrix.env }}
  strategy:
    matrix:
      env:
        - dev
        - staging
        - production

Considerations

• Each pipeline (parent and child) uses its own delegate, settings, and governance rules during execution

• Notification settings from the parent apply to the parent execution; the child uses its own notification settings

• Approval steps in the child pipeline pause the child; the parent waits until the child resumes and finishes

• Execution controls (failure strategy, conditional execution, timeout) on the chained stage apply to the child pipeline as a unit, not to individual stages inside it

Next steps

• Go to Stage overview to understand how stages work and how to add them to a pipeline.

• Go to Output variables with chained pipelines to review the full output variables reference.

• Go to Strategy to apply looping strategies to a chained stage.