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 parent waits for the child to complete
The parent continues based on the child's result

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:
      input:                           # optional: parent artifacts pushed into child
        - app.tar.gz
      output:                          # optional: child artifacts pulled 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

プロパティ

プロパティ	必須	説明
`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 environment variables
`artifacts: input:`	❌	List of artifact paths to push from parent into child before it runs
`artifacts: output:`	❌	List of artifact paths to pull from child back into parent after it completes

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:

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. Children do not inherit the parent's repository variables or secrets — pass them explicitly.

Passing Artifacts to and from Children

Use artifacts: input: and artifacts: output: 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:
            input:
              - app.tar.gz            # pushed from parent into child
            output:
              - security-report.json  # pulled 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:

Before the child runs, artifacts: input: items are copied from the parent's artifact context into the child
The child runs normally
After the child completes, artifacts: output: items are copied from the child's artifact context back into the parent

If an input artifact doesn't exist, the child still runs — it just won't find that file.

See the Cross-Pipeline Artifact I/O Reference for the full syntax.

The function-call model

input-variables: + artifacts: input: + artifacts: output: together give child pipelines a complete function interface: scalar arguments, file arguments, and return values. See the examples below for design patterns.

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:
    deploy-staging:
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - ./deploy.sh staging
    deploy-production:
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - ./deploy.sh production

Parent pipeline calling children:

pipelines:
  branches:
    main:
      - step:
          name: Build
          script:
            - npm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy Staging
          type: pipeline
          custom: deploy-staging
      - step:
          name: Deploy Production
          type: pipeline
          custom: deploy-production

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:
              input:
                - app.tar.gz
              output:
                - security-report.json
        - step:
            name: License Check
            type: pipeline
            custom: license-check
            artifacts:
              input:
                - app.tar.gz
              output:
                - 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	値
Maximum depth	1 level only — parent triggers children; children cannot trigger further children
Maximum triggered pipelines per parent	100
Variables passed to child	50 max, 100 KB total
Child pipelines	Must be defined under `pipelines: custom:` in the same repository

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 with its own repository's variables and secrets
Parent variables and secrets are not automatically available to children — pass them explicitly via input-variables:
Child pipelines defined under pipelines: custom: are never triggered by push or PR events — they only run when called by a parent step or triggered manually

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
              fi
              if git diff --name-only HEAD~1 | grep -q "^services/email-worker/"; then
                echo "EMAIL_CHANGED=true" >> $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
          type: pipeline
          custom: deploy-staging
          input-variables:
            RELEASE_TAG: $BITBUCKET_BUILD_NUMBER
  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
    deploy-staging:
      - step:
          name: Deploy
          deployment: staging
          script:
            - echo "Deploying release $RELEASE_TAG"
            - ./deploy.sh staging

トラブルシューティング

Child pipeline not triggering: 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 parent environment variables automatically.

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.

Pipeline artifacts input and output reference — Full syntax for artifacts: input: and artifacts: output:
Variable 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

この内容はお役に立ちましたか?

正確ではなかった明確ではなかった関係なかった

さらにヘルプが必要ですか?

アトラシアンコミュニティをご利用ください。

コミュニティに質問