Introducing parent/child pipelines

We’re excited to announce the launch of parent/child pipelines for Bitbucket Pipelines. This powerful new capability lets you define a step within a pipeline that triggers and encapsulates a whole other pipeline, which can help to streamline more complex workflows into modular pieces and achieve greater parallelism within your pipeline.

As teams and codebases grow, so do the demands on CI/CD pipelines. Many customers have told us about the challenges of maintaining large, monolithic pipeline configurations, or hitting the 100-step limit when trying to build complex workflows. Some have even built custom solutions or work arounds to address these limits, but these approaches often come with trade-offs like wasted build minutes or extra complexity.

Parent/child pipelines is our native solution to these challenges:

• Greater parallelism: Run more steps in parallel and go beyond the 100-step limit, unlocking new levels of scale for your builds.
• Modular pipeline structure: Break up complex workflows into smaller, focused jobs. Reuse and maintain your pipeline configuration with ease.
• No wasted build minutes: Our native implementation manages the state of the pipeline build for you—no more polling or blocked steps while waiting for triggered pipelines to finish.
• Seamless reruns: Rerun only the failed steps in a child pipeline, without triggering a full rerun which can save time and resources.
• Intuitive UI navigation: Jump directly between parent and child pipelines in the Bitbucket UI with clear status updates and two-way links.

Getting started with parent/child pipelines

1. Define your child pipeline as a custom pipeline in your bitbucket-pipelines.yml.
2. Reference the child pipeline from your parent pipeline using a step like the following example:

pipelines:
  custom:
    a-pipeline:
      - step:
        type: pipeline
        name: "Run child pipeline"
        custom: another-pipeline
    another-pipeline:
      - step:
        name: 'Success'
        script:
          - echo "I'm a successful step"

There are two new step properties:

• type: With the implementation of parent/child pipelines, we introduced a new type keyword which should be set to pipeline, indicating that the step in question is a wrapper for a child pipeline. The default type (inline) is inferred if the type field is not included on a step, so is not required to be specified for normal steps.
• custom: For pipeline steps, this is where you reference or add the name of the custom pipeline which you want the step to run.

When you run your parent pipeline, you’ll see steps with a special icon indicating that they wrap a child pipeline. You can select this icon to view the progress, logs and results of that child.

Example

Modular Pipelines

Parent/child pipelines can easily be combined with shared pipelines configurations, unlocking greater modularity within your workflows.

Example yml configuration

pipelines:
  custom:
    a-parent-pipeline:
      - step:
        type: pipeline
        name: "Run child pipeline"
        custom: imported-child-pipeline
    imported-child-pipeline:
      import: shared-pipelines:main:a-child-pipeline

Current limitations

• Child pipelines (or a pipeline running within a pipeline) must be defined as ‘custom’ pipelines (more info about custom pipelines). The parent pipeline does not have this requirement.
• Deployments and deployment stages are not supported in child pipelines themselves, or on the step wrapping a child pipeline.
  • Environments are supported (See: Evolving deployments in Bitbucket Pipelines: Concurrency Groups and Environments for details about Environments without deployments).
• A maximum of 20 child pipeline steps are allowed in a single parent pipeline.
• Child pipelines may not have additional child pipelines, only one level of “nesting” is supported.

Feedback

We’re always keen to hear your thoughts and feedback. If you have any questions or suggestions on this feature, please share them via the Pipelines Community space.