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.
動作の概要
The parent pipeline runs a step with
type: pipeline.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.The parent waits for the child to complete.
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.jsonThe 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プロパティ
プロパティ | 必須 | 説明 |
|---|---|---|
| ✅ | Must be |
| ✅ | Name of the custom pipeline to run (must match a key under |
| ❌ | Map of key/value pairs passed to the child as pipeline variables (maximum 20) |
| ❌ | List of artifact names or paths to share from the parent into the child (maximum 20) |
| ❌ | 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 stepThe 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 contextThe 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.
動作の仕組み
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.The child pipeline runs normally.
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:, orits 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.shParent 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-testsWhen 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-testsAll three children run simultaneously. The parent waits for all to complete.
Constraints and Limits
limit | 値 |
|---|---|
Maximum depth | 1 level only — parent triggers children; children cannot trigger further children |
Maximum | 20 |
Variables passed to child ( | 20 per |
Shared artifacts | 20 |
Child pipelines | Must be defined under |
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 passedCustom 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 testBoth 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.
トラブルシューティング
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.
関連情報
Pipeline artifacts input and output reference — Full syntax for
artifacts: input:andartifacts: output:Child pipeline step options — All options for
type: pipelinestepsVariable sharing reference — Pass variables between steps and pipelines
Tutorial 9: Parent/Child Basics — Hands-on guide
Tutorial 10: Reusable Modules — Building reusable children with parameters
この内容はお役に立ちましたか?