Parent/Child pipelines

Parent/Child Pipelines let one pipeline (the parent) trigger one or more other pipelines (the children). The parent orchestrates the high-level flow; children handle focused, independent work. This pattern breaks monolithic pipelines into manageable pieces and enables parallel execution of independent work units.


How It Works

  1. The parent pipeline runs a step with type: pipeline.

  2. The step triggers a child pipeline defined under pipelines: custom: in the same repository. The child runs as a separate pipeline on the same commit as the parent.

  3. The parent waits for the child to complete.

  4. The parent continues based on the child's result. The parent step gets the same status as the child pipeline: passed, failed, stopped, or error. If the child pauses on a manual step, the parent step shows that action is required.


Trigger Step Syntax

Use type: pipeline with custom: to trigger a child pipeline:

- step: name: Run Security Scan type: pipeline custom: security-scan # name of the custom pipeline to run input-variables: # optional: variables passed to child SCAN_LEVEL: strict artifacts: upload: # optional: parent artifacts shared into child - app.tar.gz download: # optional: child artifacts shared back to parent - security-report.json

The child pipeline is defined under pipelines: custom: in the same file:

pipelines: custom: security-scan: # must match the parent's custom: value - step: name: Run Scan script: - 'echo "Scan level: $SCAN_LEVEL"' - ./scan.sh app.tar.gz > security-report.json artifacts: - security-report.json

Properties

Property

Required

Description

type

✅

Must be pipeline

custom

✅

Name of the custom pipeline to run (must match a key under pipelines: custom:)

input-variables

❌

Map of key/value pairs passed to the child as pipeline variables (maximum 20)

artifacts: input:

❌

List of artifact names or paths to share from the parent into the child (maximum 20)

artifacts: output:

❌

List of artifact names or paths to share from the child back to the parent (maximum 20)


Passing Variables to Children

Use input-variables: to pass data from the parent to the child. Variables are passed as a map of key/value pairs.

Variable names can only contain ASCII letters, digits, and underscores, and can't start with a digit.

pipelines: default: - step: name: Detect Version script: - export VERSION=$(cat version.txt) - echo "VERSION=$VERSION" >> $BITBUCKET_PIPELINES_VARIABLES_PATH output-variables: - VERSION - step: name: Deploy type: pipeline custom: kubernetes-deploy input-variables: SERVICE_NAME: payment-api # static value IMAGE_TAG: $BITBUCKET_COMMIT # built-in variable APP_VERSION: $VERSION # output variable from previous step

The child pipeline receives these as regular environment variables:

pipelines: custom: kubernetes-deploy: - step: name: Deploy script: - echo "Deploying $SERVICE_NAME version $APP_VERSION" - kubectl apply -f k8s/$SERVICE_NAME/

Variables passed via input-variables: are available as regular environment variables in the child pipeline's steps.

The child runs in the same repository, so workspace and repository variables are available as usual. Values from the parent’s run, such as output variables and pipeline variables, must be passed explicitly.

Use $NAME as the entire value to pass a variable (for example, APP_VERSION: $VERSION); any other value is passed as text. Secured variables can’t be passed. Referencing a secured or undefined variable fails the parent step.


Passing Artifacts to and from Children

Use artifacts: upload: and artifacts: download: on a type: pipeline step to pass files across the parent/child boundary.

Parent passes build artifact to child, receives report back:

pipelines: branches: main: - step: name: Build script: - npm run build - tar -czf app.tar.gz dist/ artifacts: - app.tar.gz - step: name: Security Scan type: pipeline custom: security-scan artifacts: upload: - app.tar.gz # shared from parent into child download: - security-report.json # shared from child back to parent - step: name: Review Report script: - cat security-report.json # available in parent context

The child pipeline needs no special declarations — it simply reads app.tar.gz as a normal file and writes security-report.json using its standard artifacts: block.

How it works

  1. Before the child pipeline starts, the artifacts listed in artifacts: upload: are shared from the parent into the child. They’re available for download in all steps of the child pipeline.

  2. The child pipeline runs normally.

  3. After the child pipeline completes successfully, artifacts: output: artifacts: download: items are copied from the child's artifact context back into the parent, and are available in all steps after the child pipeline step. If the child pipeline doesn't pass, no artifacts are shared back.

Matching artifacts

Artifacts are matched by name. To reference one, use either:

  • the name it was given with artifacts: upload: - name:, or

  • its path exactly as it was declared.

For example, dist/app.js won’t match an artifact declared as dist/**. If more than one step produced an artifact with the same name, the most recent one is shared.

If an upload or download artifact isn’t found, it’s skipped without an error. The child pipeline still runs; it just won’t have that file.


Triggering Custom Pipelines

Child pipelines are defined under pipelines: custom: in the same repository. A parent step references them by name:

Child pipeline definitions:

pipelines: custom: integration-tests: - step: name: Integration Tests script: - ./run-integration-tests.sh smoke-tests: - step: name: Smoke Tests trigger: manual script: - ./run-smoke-tests.sh

Parent pipeline calling children:

pipelines: branches: main: - step: name: Build script: - npm run build artifacts: - dist/** - step: name: Integration Tests type: pipeline custom: integration-tests - step: name: Smoke Tests type: pipeline custom: smoke-tests

When a child pipeline pauses on a manual step, like smoke-tests above, the parent step shows that action is required until the manual step is run.

Child pipelines can't contain deployment steps or deployment stages, and a type: pipeline step can't use deployment. Keep deployment steps in the parent pipeline.


Parallel Children

Trigger multiple children in parallel using a parallel block:

pipelines: default: - step: name: Build All script: - npm run build artifacts: - app.tar.gz - parallel: - step: name: Security Scan type: pipeline custom: security-scan artifacts: upload: - app.tar.gz download: - security-report.json - step: name: License Check type: pipeline custom: license-check artifacts: upload: - app.tar.gz download: - license-report.json - step: name: Integration Tests type: pipeline custom: integration-tests

All three children run simultaneously. The parent waits for all to complete.


Constraints and Limits

Limit

Value

Maximum depth

1 level only — parent triggers children; children cannot trigger further children

Maximum type: pipeline steps per pipeline

20

Variables passed to child (input-variables)

20 per type: pipeline step

Shared artifacts

20 upload and 20 download per type: pipeline step

Child pipelines

Must be defined under pipelines: custom: in the same repository, and can't contain deployment steps or deployment stages

Children cannot trigger further children. The parent/child relationship is one level deep only. If a child needs to run additional pipelines, pull that orchestration up to the parent.


Access and Permissions

  • The child pipeline runs in the same repository and on the same commit as the parent, with that repository's variables

  • Values from the parent run, such as output variables, are not automatically available to children — pass them explicitly via input-variables:. Secured variables can't be passed

  • Custom pipelines are never triggered by push or PR events — hey run when called by a parent step, or when run manually, on a schedule, or through the API


Stopping and Rerunning

Stopping the parent step also stops its child pipeline. If the parent step is stopped before the child pipeline starts, the child pipeline ends with an error and none of its steps run. Stopping the child pipeline directly marks the parent step as stopped.

Rerunning a failed parent step doesn’t create a new child pipeline. It reruns the failed steps of the existing child pipeline, and the artifacts listed in artifacts: upload: are shared into the child again. The same happens when the parent step is retried automatically.


Complete Example: Monorepo Orchestration

image: node:20 pipelines: branches: main: - step: name: Detect Changes script: - | if git diff --name-only HEAD~1 | grep -q "^services/payment-api/"; then echo "PAYMENT_CHANGED=true" >> $BITBUCKET_PIPELINES_VARIABLES_PATH else echo "PAYMENT_CHANGED=false" >> $BITBUCKET_PIPELINES_VARIABLES_PATH fi if git diff --name-only HEAD~1 | grep -q "^services/email-worker/"; then echo "EMAIL_CHANGED=true" >> $BITBUCKET_PIPELINES_VARIABLES_PATH else echo "EMAIL_CHANGED=false" >> $BITBUCKET_PIPELINES_VARIABLES_PATH fi output-variables: - PAYMENT_CHANGED - EMAIL_CHANGED - parallel: - step: name: Build & Test Payment API type: pipeline custom: payment-api-build-test condition: state: PAYMENT_CHANGED == true - step: name: Build & Test Email Worker type: pipeline custom: email-worker-build-test condition: state: EMAIL_CHANGED == true - step: name: Deploy to Staging deployment: staging script: - echo "Deploying release $BITBUCKET_BUILD_NUMBER" - ./deploy.sh staging custom: payment-api-build-test: - step: name: Build Payment API image: node:20 script: - cd services/payment-api - npm ci - npm test - npm run build email-worker-build-test: - step: name: Build Email Worker image: node:20 script: - cd services/email-worker - npm ci - npm test

Both variables are always written as true or false, because a state condition that references an undefined variable fails the step instead of skipping it. The deployment stays in the parent pipeline because child pipelines can't contain deployment steps.


Troubleshooting

Parent step fails with "Child pipeline with name: … could not be found in the pipelines configuration": Check that the custom: value on the parent step matches a key under pipelines: custom: exactly (case-sensitive).

Variables not available in child: Variables must be passed via input-variables: on the parent step. The child does not inherit the parent's output variables automatically. Check that each reference is written as $NAME.

Child pipeline fails but parent continues: This should not happen by default — the parent waits for the child and fails if the child fails. Check that the parent step has type: pipeline set correctly.

Parent step fails with "includes unknown or secured variables": An input-variables: value references a variable that doesn't exist for the parent step, or is secured. Secured variables can't be passed to a child pipeline.

Child pipeline fails with "Child pipelines cannot contain deployment steps": Remove deployment from the child pipeline's steps and stages, and keep the deployment in the parent pipeline.

Artifact from the child isn't available in the parent: Artifacts are only shared back when the child pipeline passes, and each download entry must match the artifact's name or its declared path exactly.


 

Still need help?

The Atlassian Community is here for you.