How Multiple Workflows Work in Woodpecker CI

Updated

Woodpecker CI lets you define more than one workflow for a single project, and those workflows can depend on each other. That means you can split a pipeline into separate units — for example, a build workflow and a deploy workflow — and control the order in which they run instead of forcing everything into one linear sequence. This is useful when different parts of your pipeline have different triggers, different execution needs, or should only run after another part succeeds.

What a "workflow" means in Woodpecker

Woodpecker executes pipeline steps inside Docker containers. A workflow is a named group of those steps. When you define multiple workflows, each one is its own unit with its own steps, and Woodpecker runs them according to the dependencies you declare.

The practical consequence: instead of one long pipeline where every step waits on the previous one, you get several pipelines that can run independently or in a defined order.

How dependencies between workflows work

The key capability is that workflows "can even depend on each other." In practice this means you express a relationship such as "workflow B runs only after workflow A completes." Woodpecker then schedules them accordingly rather than starting everything at once.

This matters because:

  • Ordering is explicit. You decide which workflow gates which, instead of relying on step position inside a single pipeline.
  • Failure is contained. If a dependency fails, the dependent workflow does not proceed, which keeps a broken build from triggering a deploy.
  • Independent work stays independent. Workflows without a dependency relationship are not forced to wait on each other.

Typical scenarios for multiple workflows

Multiple workflows fit situations where a single pipeline would be awkward:

Scenario Why multiple workflows help
Build then deploy Deploy depends on a successful build, so it runs only after build passes
Separate concerns (lint, test, build) Each concern is its own workflow with its own steps and container images
Different triggers per task A workflow can be scoped to the events it should respond to
Reusable structure across projects Workflows can be composed rather than duplicated as one large pipeline

For example, a project might have a test workflow that runs on every push and a release workflow that depends on test and only proceeds once tests pass.

How to configure it

Woodpecker's own documentation is the authoritative place to configure multi-workflow setups, including how dependencies are declared. The site points readers to "Check out the docs" for this. Because the exact syntax and available options live in the docs and can change, treat the documentation as the source of truth rather than copying a config from a blog post.

A reasonable approach:

  1. Read the Woodpecker docs section on workflows and dependencies.
  2. Define your first workflow with its steps.
  3. Add a second workflow and declare its dependency on the first.
  4. Push and confirm in the Woodpecker UI that the second workflow waits for the first.

What to keep in mind

  • Woodpecker is open source and, per its site, "is and always will be totally free," so there is no paid tier gating multi-workflow features.
  • Steps run in Docker containers; if a normal image is not enough, you can build plugins to extend pipeline behavior.
  • The dependency behavior is a scheduling relationship, not a merge of the workflows — each remains a distinct unit.

If your pipeline is growing into a single long chain of steps, splitting it into dependent workflows is the intended way to keep it organized.