Introducing Parent/Child Pipelines in Bitbucket

CI/CD pipelines can grow complex as teams and codebases expand. Bitbucket’s parent/child pipelines capability launched in mid-2025 is a game-changer for managing this complexity. It allows you to trigger an entire pipeline from a single step of another pipeline, effectively creating a “pipeline within a pipeline.” The result? More modular, parallel, and maintainable build processes.

In this article, we will reiterate the key points from our presentation in a natural flow. You’ll learn why parent/child pipelines were introduced, what benefits they bring, and how to set them up. We’ll also cover best practices for using them effectively and highlight current limitations to be aware of. Whether you’re an experienced DevOps engineer or a technical leader looking to optimize your team’s CI/CD workflow, this guide will help you understand how parent/child pipelines can streamline complex workflows. Let’s dive in.

The Need for a Better Pipeline Structure

Modern development teams rely on continuous integration and delivery (CI/CD) pipelines to build, test, and deploy code. As projects grow, these pipelines often become large and unwieldy. Many of our clients have faced challenges with monolithic pipeline configurations that contain dozens of sequential steps. In Bitbucket Pipelines, there has historically been a cap of 100 steps per pipeline. Hitting this limit isn’t hard when you’re running extensive tests, multiple build stages, and deployments in one go. Even before reaching that hard limit, very long pipelines can be difficult to maintain and slow to execute, since many steps run one after another.

Managing such large pipelines can feel like juggling a dozen tasks in a single thread. Teams have to coordinate changes carefully, and a failure in one part means re-running everything. We’ve seen some organizations attempt workarounds: splitting jobs into separate pipelines, triggering one pipeline from another via scripts or API calls, or other custom solutions. These hacks can partially address the issues but often introduce new problems. For example, a script-triggered pipeline might require the first pipeline to wait or poll for the second to finish, wasting valuable build minutes while nothing useful happens. In other cases, maintaining multiple pipeline files or repositories adds complexity and technical debt.

The introduction of parent/child pipelines is Atlassian’s answer to these pains. It provides a native way to break down a large CI/CD process into smaller pieces without losing coordination between them. Instead of a single colossal pipeline or ad-hoc chaining, you get a clean structure: a parent pipeline that can kick off multiple child pipelines as steps. This structure addresses the need for both scalability and maintainability.

Benefits of Parent/Child Pipelines

The parent/child pipeline feature brings several concrete benefits to your build workflows. Here are the key advantages and why they matter:

• Greater parallelism: Parent/child pipelines allow you to run more steps in parallel, effectively bypassing the 100-step per pipeline limit. You can split work into multiple child pipelines that execute simultaneously, unlocking new levels of scale and speeding up overall build times. For example, different components of your application can build and test in parallel child pipelines rather than queuing up sequentially.

• Modular pipeline structure: Instead of one giant pipeline with every job, you can organize your CI/CD into smaller, focused pipelines. Each child pipeline can handle a distinct stage or service. This modular approach makes the configuration easier to read and maintain. Teams can update one part of the pipeline without risking the entire flow, and they can reuse child pipelines across different parent triggers if needed.

• No wasted build minutes: One major benefit of Bitbucket’s native implementation is efficient management of build time. In the past, if you chained pipelines using custom scripts, the parent pipeline might sit idle waiting for the child to finish, consuming your pipeline minutes quota. Parent/child pipelines avoid this the Bitbucket Pipelines service handles the orchestration for you behind the scenes. The parent pipeline doesn’t burn time unnecessarily while a child runs. Once a child pipeline is triggered, the parent will only resume when needed, eliminating those “polling” or idle wait periods.

• Seamless reruns: Failures are inevitable in CI/CD, whether due to flaky tests or integration issues. With parent/child pipelines, you don’t have to rerun the entire parent pipeline if a single component fails. Bitbucket lets you rerun just the failed child pipeline step. This means if one child pipeline fails, you can rerun that child in isolation. You avoid triggering a full rebuild of everything, saving time and compute resources. It makes the failure recovery process more efficient and developer-friendly.

• Intuitive UI navigation: Bitbucket’s interface clearly indicates when a step contains a child pipeline. In the build results, a pipeline step of type “pipeline” will show a special icon or marker. Clicking that icon lets you drill down into the child pipeline’s details you can see its steps, logs, and status. There’s also a link back up to the parent pipeline. This two-way navigation is smooth and integrated, so you can jump between parent and child views easily. Even complex builds spanning multiple pipelines remain understandable, as the UI ties them together and shows the overall status at a glance.

Together, these benefits mean you can achieve more with your CI/CD pipeline without fighting against the tooling. Next, we’ll look at how you can set up parent/child pipelines in your Bitbucket repository to realize these advantages.

How to Set Up a Parent/Child Pipeline in Bitbucket

Setting up a parent/child pipeline is straightforward if you’re familiar with Bitbucket Pipelines configuration. Here are the basic steps to get started:

1. Define the child pipeline in your configuration: In your bitbucket-pipelines.yml file, define the child pipeline as a custom pipeline. Under the pipelines: section, there is a subsection for custom pipelines where you can name and configure pipelines that are not tied to specific branches or events. For example, you might add a section like my-child-pipeline: under pipelines: custom: and list the steps that child pipeline should perform. This child pipeline can contain any steps you need, just like a regular pipeline.

2. Reference the child from a parent pipeline step: In the parent pipeline (which could be your default pipeline or any other pipeline that runs on a push, PR, or manually), add a step that triggers the child. To do this, you will use a special step type. Instead of a normal script step, define a step with type: pipeline and specify which custom pipeline to run with the custom: attribute. Give the step a clear name as well. For example, your parent pipeline could have a step:

   - step: type: pipeline name: "Run child pipeline" custom: my-child-pipeline

   This tells Bitbucket: “At this point in the parent pipeline, run the pipeline defined as ‘my-child-pipeline’.” The parent will spawn the child pipeline and continue once the child is done.

3. Run the pipeline and monitor the results: After configuring the above, trigger your parent pipeline by pushing code or via your usual pipeline trigger. When the parent pipeline runs, you will see the special step that encapsulates the child pipeline. In Bitbucket’s Pipelines UI, that step will show an indicator. You can click on it to view the real-time progress and logs of the child pipeline. Each child pipeline will run as if it were a normal pipeline, reporting success or failure independently. Once the child completes, the parent pipeline can proceed to any subsequent steps. If something goes wrong in a child pipeline, you have the option to rerun that child without restarting the whole parent run.

By following these steps, you integrate a child pipeline into your main workflow. Essentially, the parent pipeline acts as an orchestrator, and child pipelines handle the detailed tasks. This setup is powerful for organizing complex builds.

Understanding the Parent/Child Pipeline Mechanism

It’s useful to understand what’s happening under the hood with parent/child pipelines. Bitbucket introduced two new pipeline step properties to enable this feature: type: pipeline and custom: (pipeline name). A step in your YAML with type: pipeline signals to Bitbucket that this step is not a usual inline script execution, but rather a wrapper that will trigger another pipeline. The custom field then tells Bitbucket which custom pipeline to run at that point; it should match the name of a pipeline you’ve defined under the custom section in the YAML.

If you don’t include a type on a step, Bitbucket assumes the default type. In other words, setting type: pipeline is what differentiates a parent pipeline’s special step from a normal step. The system will take care of starting the specified child pipeline as a separate execution. The parent pipeline will pause at that step until the child finishes, but importantly it isn’t consuming a build container or timer while waiting. This is how it avoids those wasted minutes we mentioned earlier Bitbucket manages the state asynchronously.

From a user perspective, Bitbucket’s interface makes it clear which steps are pipelines. The special icon next to a pipeline step can be clicked to navigate into the child pipeline’s details. Inside the child pipeline view, you’ll find a link back to its parent pipeline. This intuitive UI linking means even though you have multiple pipelines running as part of one overall job, you won’t get lost. You can always trace which parent triggered which child and see where a failure occurred. This design is a big improvement over custom solutions where you might have had to manually find the results of a triggered pipeline.

In summary, the parent/child mechanism adds a layer of orchestration within the YAML config. Bitbucket’s platform handles the coordination seamlessly you just declare the relationships in the config, and the pipelines run in the right order with clear visibility.

Building Modular Pipelines with Reusable Configurations

One of the most powerful outcomes of using parent/child pipelines is the ability to create modular, reusable pipeline components. Atlas Bench often advocates for DRY principles in CI/CD configurations. With this feature, you can encapsulate a set of steps as a child pipeline and invoke it in multiple places or even across repositories.

For instance, imagine you maintain a standard set of quality checks or deployment steps that should run for all your projects. Instead of duplicating those steps in every repository’s pipeline config, you could define a child pipeline in a central location and reuse it. Bitbucket has a concept of shared pipeline configurations, which allows one repository to import pipeline definitions from another. Parent/child pipelines work seamlessly with such shared configs. You might have a shared repository defining a pipeline called “a-child-pipeline” that performs certain common tasks. In your project repo’s bitbucket-pipelines.yml, your parent pipeline step can simply reference this shared child pipeline. When the parent runs, it will pull in and execute that imported child pipeline. This setup unlocks greater modularity you maintain one definition of the common pipeline and use it wherever needed.

Even within a single repository, breaking up a complex pipeline into modular pieces is beneficial. Teams can work on different parts of the CI/CD process in parallel. For example, your build could consist of one pipeline that handles building the application and running unit tests, another pipeline for integration tests, and yet another for packaging and artifact upload. The parent pipeline orchestrates these pieces. This modular approach not only makes the YAML files cleaner but also encourages separation of concerns. Each child pipeline can be owned by a sub-team or focused on a specific outcome, and issues in one area won’t directly impact the others except for final pass/fail status aggregation.

From a maintenance perspective, modular pipelines are easier to update. Need to add a new static analysis step for all your microservices? Update the child pipeline definition for static analysis, and every parent that calls it automatically uses the new step. This beats editing many lines in one huge pipeline or copy-pasting changes across multiple configs. Overall, parent/child pipelines combined with shared configurations can bring a more architected approach to CI/CD, treating pipelines as building blocks rather than one-off scripts.

Tips for Using Parent/Child Pipelines Effectively

When adopting parent/child pipelines, keep these best practices in mind to make the most of the feature:

• Group related tasks into child pipelines: Identify parts of your pipeline that make sense to isolate. For example, you might put all integration tests in one child pipeline and UI tests in another. Grouping related steps ensures each child pipeline has a clear purpose and can run independently. This logical separation improves clarity and makes troubleshooting easier.

• Run independent steps in parallel: Take advantage of the parallelism by triggering multiple child pipelines from a parent. If you have tasks that don’t depend on each other, set them up as separate child pipelines under the same parent. This way, they execute at the same time, reducing the total build time. The parent pipeline will wait for all to finish, and you’ll get a combined result faster than if those steps ran one after the other.

• Name pipelines clearly: Use descriptive names for your custom pipelines and the parent pipeline steps that call them. Instead of naming a child pipeline “pipeline1” or “child123,” use a name like “run-backend-tests” or “deploy-to-staging”. Clear naming appears in the Bitbucket UI and logs, helping everyone on the team immediately understand what each pipeline does. This reduces confusion when viewing the pipeline results and aids communication.

• Plan around the 20-child limit: Bitbucket currently allows a maximum of 20 child pipeline steps within a single parent pipeline run. This is plenty for most use cases, but if you foresee needing more, consider structuring your pipelines hierarchically or combining some tasks. Perhaps you can have one child pipeline orchestrate a few subtasks internally if you truly need to exceed 20 parallel pieces. In general, try not to approach the limit unless absolutely necessary having dozens of parallel pipelines could become hard to manage practically.

• Keep child pipelines self-contained: Each child pipeline should ideally be able to run on its own and produce a meaningful outcome. Avoid making a child pipeline too dependent on subtle context from the parent. For instance, pass along only the necessary variables or artifacts to the child. This makes it easier to rerun or reuse the child pipeline in other contexts. If a child pipeline needs certain environment variables or artifacts, ensure the parent provides them explicitly so that the child’s behavior is predictable.

• Handle deployments at the appropriate level: If your process involves deployments (to environments like staging or production), plan where those happen. Since child pipelines do not support deployment steps directly, you should perform deployment actions in the parent pipeline or as separate dedicated pipelines. You might use child pipelines for build and test stages, then have the parent coordinate a deployment after they all succeed. This way, you stay within supported use and still deliver to your environments.

By following these tips, you’ll ensure that your adoption of parent/child pipelines is smooth and effective. The goal is to improve your pipeline’s speed and maintainability without introducing confusion. A bit of upfront planning on how to break down your workflow goes a long way.

Current Limitations to Keep in Mind

While parent/child pipelines are powerful, it’s important to be aware of a few current limitations in Bitbucket’s implementation. Understanding these will help you design your pipelines correctly and avoid surprises:

• Child pipelines must be defined as custom pipelines: You cannot trigger a standard branch or deployment pipeline as a child. The child pipeline must be listed under the pipelines: custom section in your bitbucket-pipelines.yml. 

• No built-in deployment steps in child pipelines: Bitbucket does not support using deployment environments or deployment gates within a child pipeline, nor on the parent step that triggers it. In practice, this means you cannot mark a step in a child pipeline as a “deployment to staging” for example. You also cannot have the parent’s pipeline step itself directly be a deployment step when it’s triggering a child. However, you can still perform deployment actions using scripts or rely on environment-specific variables if needed you just won’t get the special “Deployment” marking in the UI for those child steps.

• One level of nesting only: You cannot have a child pipeline trigger another child pipeline. Each parent can invoke child pipelines, but those child pipelines cannot themselves use type: pipeline steps. There is only one level of nesting supported. Keep this in mind when designing; you might have multiple child pipelines, but don’t try to nest them within each other.

• Maximum of 20 child pipelines per parent: A single parent pipeline run can include up to 20 child pipeline steps. This is a safeguard to prevent excessive resource usage and complexity. In reality, most workflows won’t need nearly that many parallel pipelines, but if you were thinking of dynamically spawning dozens of pipelines, know that 20 is the cap at the moment. If you have more than 20 distinct tasks, consider grouping some tasks together in one child or triggering some pipelines after others complete.

• Triggering conditions and context: The parent/child relationship is straightforward the parent triggers the child when it hits that step. There isn’t a way to trigger child pipelines conditionally after a run except by structuring your YAML logic. Also, the child pipeline inherits context explicitly passed to it, but not the entire state of the parent. If your workflow relies on heavy context sharing, you may need to adjust to explicitly pass what’s needed via artifacts or variables.

These limitations are good to keep in mind as you plan your adoption of parent/child pipelines. Atlassian may lift or adjust some of these limits over time as the feature matures, but for now, design within these boundaries for the best results. The limitations mostly affect edge cases; for the vast majority of use cases, parent/child pipelines will work smoothly and offer immediate benefits.

Next Steps

Parent/child pipelines in Bitbucket Pipelines represent a significant step forward in how teams can design and run their CI/CD workflows. By enabling one pipeline to trigger another, Atlassian has given us a native way to scale beyond previous limits and to structure pipelines more cleanly. No longer do you need to cram everything into one YAML or maintain clunky workarounds you can enjoy parallel execution of different parts of your process and manage each part in a modular fashion. This leads to faster builds, easier maintenance, and more flexibility in how you orchestrate complex tasks.

At Atlas Bench, we’re thrilled about this feature because it directly addresses pain points we’ve observed in real-world client environments. It aligns with our philosophy of efficient DevOps and maintainable systems. If your team has been struggling with long build times, complicated pipeline files, or limitations of your current setup, parent/child pipelines might be the solution you need. We encourage you to give it a try by updating your Bitbucket pipeline configuration. Start small perhaps create one child pipeline for a portion of your build and experience the difference in clarity and speed.

As always, Atlas Bench is here to help. Our experts have deep experience with Bitbucket and the entire Atlassian suite. We can assist in designing optimal pipeline architectures, migrating your existing CI workflows, or implementing new features like parent/child pipelines effectively in your environment.