Structure Complex Workflows with Drone CI Multi-Pipelines (2026)

Drone CI’s multi-pipeline feature allows you to orchestrate complex, multi-stage build and deployment processes by linking independent pipelines together.

Let’s see this in action. Imagine a typical scenario: first, we build our application, then we test it, and finally, if all tests pass, we deploy it.

Here’s a simple drone.yml that defines three sequential pipelines: build, test, and deploy.

kind: pipeline
name: build
steps:
  - name: build-image
    image: plugins/docker
    settings:
      repo: your-dockerhub-username/your-app
      tags:
        - ${DRONE_COMMIT_SHA}
        - latest

---

kind: pipeline
name: test
depends_on:
  - build
steps:
  - name: run-tests
    image: your-testing-image
    commands:
      - ./run-tests.sh

---

kind: pipeline
name: deploy
depends_on:
  - test
steps:
  - name: deploy-app
    image: your-deployment-image
    commands:
      - ./deploy.sh
    when:
      status: success

In this example:

• The build pipeline is the entry point. It builds a Docker image and pushes it to a repository.
• The test pipeline depends_on the build pipeline. This means it will only start after build has successfully completed. Its job is to run integration tests against the newly built image.
• The deploy pipeline depends_on the test pipeline. It will only execute if test succeeds. The when: status: success clause ensures that deploy only runs if the test pipeline’s status was success.

This chaining mechanism is the core of multi-pipeline orchestration. Drone CI manages the dependencies, ensuring that each pipeline executes in the correct order. You can define complex dependency graphs, not just linear sequences. For instance, a deploy pipeline could depend on multiple preceding pipelines, requiring all of them to succeed before it can start.

The depends_on keyword is the key. It takes a list of pipeline names. Drone’s scheduler interprets this and queues up pipelines based on these declared dependencies. If a pipeline listed in depends_on fails, any pipeline that depends on it will also be marked as failed or skipped, preventing further execution down that path. This is crucial for maintaining build integrity and avoiding deployments of broken code.

The when clause offers fine-grained control over when a pipeline executes. While depends_on handles the order, when lets you define conditions based on various factors like the commit branch, the status of previous pipelines, or even the presence of specific tags. In our deploy pipeline, when: status: success is a common pattern to ensure deployment only happens on successful test runs. Other useful conditions include branch: main to deploy only from the main branch, or event: push to trigger only on code pushes.

Under the hood, Drone CI maintains a Directed Acyclic Graph (DAG) of your pipelines based on the depends_on relationships. When a commit is pushed, Drone analyzes this DAG. It starts by executing all pipelines that have no dependencies. As each pipeline completes, Drone checks its dependents. If a dependent pipeline’s dependencies are all met (i.e., all pipelines it depends_on have succeeded), it’s added to the queue for execution. This process continues until all reachable pipelines have been processed or a failure occurs.

A subtle but powerful aspect of multi-pipelines is how artifacts are implicitly passed. While not explicitly defined as first-class artifact passing between pipelines in the same way as within a single pipeline, the output of one pipeline (like a Docker image pushed to a registry) becomes the input for the next. The build pipeline pushes an image tagged with the commit SHA. The test pipeline, by referencing that same image name (implicitly or explicitly in its configuration), consumes the artifact produced by build. This creates a chain of production and consumption without explicit artifact declarations between pipelines.

The real power here is in managing the lifecycle of a change. You can have an initial pipeline that builds and publishes a library, followed by multiple parallel pipelines that consume that library to test their own integrations with it, and then a final pipeline that aggregates the results or triggers a deployment if all dependent tests pass.

This entire system is managed by Drone’s internal scheduler, which constantly monitors the status of pipelines and their dependencies. It’s not about sending explicit signals between pipelines; rather, it’s about the scheduler observing the state of the DAG and making decisions about what can run next.

You can also create pipelines that run in parallel by having them depend on the same upstream pipeline but not on each other. For example, you could have test-frontend and test-backend both depend on build. They would then run concurrently after build finishes.

The next step in mastering Drone CI workflows is understanding how to manage secrets and configurations across these interconnected pipelines without leaking sensitive information or creating brittle configurations.