woodpecker-ci.org

Woodpecker CI is an open-source, free CI/CD engine that runs pipeline steps inside Docker containers. It fits teams or individuals who want a self-hostable continuous integration system that stays simple to operate but can be extended through plugins and multiple interdependent workflows. If you need a hosted-only service or a system that does not rely on Docker for step execution, Woodpecker is not the direct match.

Core characteristics

Open source and free

Woodpecker is and always will be totally free, and its source code is open-source, so you can contribute to help evolve the project. This matters if licensing cost or vendor lock-in is a deciding factor for your CI choice.

Docker-based pipeline execution

Woodpecker uses Docker containers to execute pipeline steps. Each step runs in a container, which means the environment for a step is defined by the image you choose rather than by the host machine's installed tooling.

Extensibility through plugins

If you need more than a normal Docker image, you can create plugins to extend pipeline features. Plugins are the mechanism for packaging custom behavior so it can be reused across pipelines.

Multiple workflows with dependencies

Woodpecker allows you to easily create multiple workflows for a project, and those workflows can even depend on each other. This is useful when a project has distinct stages or targets that should run in a defined order rather than as one flat pipeline.

What problem it solves

When to consider it

• You want a CI/CD engine you can run and inspect yourself, built on Docker.
• Your pipelines benefit from containerized steps and you are comfortable defining steps as container images.
• You have project structures that map naturally to several workflows with ordering between them.
• You may need custom step behavior and are willing to build a plugin rather than only use off-the-shelf images.

When to look elsewhere

• You require a fully managed CI service and do not want to operate the engine.
• Your environment cannot use Docker containers for pipeline steps.
• You need capabilities that are neither covered by standard Docker images nor by writing a plugin.

Next step

To evaluate it concretely, start from the official site and docs: review how a pipeline step is defined as a container, then check the plugin mechanism and the multi-workflow documentation to confirm they match your project's structure.

Woodpecker CI runs every pipeline step inside a Docker container, and when a standard image can't do what you need, you extend the pipeline by building a plugin. That design is the core of how the engine executes work: instead of running commands directly on the host, each step is isolated in a container, and plugins are just containers with a defined interface that Woodpecker calls. This applies to any project where you want reproducible, isolated build steps and reusable custom logic.

Docker as the execution model

Woodpecker is based on Docker containers and uses them to execute pipeline steps. The practical consequence is that a step isn't a shell command running on the agent host — it's a container started from an image you specify, with your commands or the image's entrypoint running inside it.

This gives you a few concrete properties:

• Isolation per step. Each step gets its own container, so tool versions, environment variables, and filesystem changes don't leak between steps unless you explicitly share them (for example through a workspace volume).
• Reproducibility. The image tag pins the environment. A step that passes on one agent should behave the same on another, because the container is the unit of execution rather than the host's installed toolchain.
• Image choice as configuration. Selecting a language runtime, a database client, or a build tool is mostly a matter of picking the right image for that step.

A typical pipeline therefore looks like a sequence of steps, each naming an image and the commands to run inside it. The agent pulls the image, starts the container, executes the step, and reports the result back.

When a normal Docker image isn't enough

The documented boundary is explicit: if you need more than a normal Docker image, you can create plugins to extend the pipeline features. So the decision point is whether an existing image plus a command list covers your need.

Use a plain image when:

• The task is "run these commands with this toolchain" (build, test, lint, package).
• The behavior is fully described by the image's contents and the commands you pass.
• You don't need to react to Woodpecker's pipeline metadata in a structured way.

Build a plugin when:

• You want reusable logic that other pipelines can call with parameters rather than copy-pasted commands.
• The step needs to integrate with Woodpecker's execution context in a defined way.
• You're packaging a capability (deploy target, notification channel, artifact handler) that should behave consistently across projects.

How plugins extend the pipeline

A plugin in Woodpecker is essentially a container with a defined contract: Woodpecker runs it as a step and passes configuration in, and the plugin performs its work and returns a result. Because the mechanism is container-based, anything you can package into an image can become a plugin.

The practical workflow is:

1. Identify the repeated or specialized task that a plain image plus commands handles awkwardly.
2. Package it as a container image that reads its configuration from the environment or step settings.
3. Reference it as a step in the pipeline, supplying the settings for that particular use.
4. Verify by running the pipeline and checking that the plugin step receives its inputs and produces the expected effect (artifact, deployment, message, exit status).

The benefit of this over inlining commands is reuse and consistency: the logic lives in one image, and every pipeline that needs it calls the same versioned artifact.

Multi-workflow pipelines

Woodpecker also allows you to easily create multiple workflows for your project, and they can even depend on each other. Combined with container-based steps, this means you can structure a pipeline as several workflows — for example separate build, test, and deploy flows — with explicit dependencies between them, each workflow made of containerized steps and plugin steps.

What this buys you

• Portability. The execution environment travels with the pipeline definition as image references, not as host setup.
• Extensibility without forking. Plugins let you add capability through images rather than modifying the engine.
• Composability. Multiple workflows with dependencies let you model real delivery stages instead of one long linear script.

Choosing between an image and a plugin

If your step is "install dependencies and run tests," an image is enough. If your step is "publish to our internal system in a standard way that every repo should follow," that's the case the docs point to for building a plugin.

Woodpecker is open source and free, and because the source is open you can contribute to help evolve the project — which also means you can inspect how the container and plugin execution actually works if you need to go deeper than the documented behavior.

Yes. Woodpecker CI is open source and, according to its website, "is and always will be totally free." That statement covers the software itself: you can download, run, modify, and contribute to it without paying a license fee. It does not mean your total CI/CD cost is zero, because you still supply the infrastructure the pipelines run on.

What "free" actually covers

The project's own framing is straightforward: the source code is open source, and the software is free to use. In practice that means:

• No license cost. You are not buying seats, build minutes, or a subscription from the project.
• You can contribute. Because the code is open source, you can help evolve the project — bug fixes, features, docs, or plugins.
• You can inspect and modify it. Open source means the implementation is available to read and change, which matters if you need to audit behavior or adapt it to your setup.

What it does not cover

Free software is not the same as free hosting. Woodpecker runs your pipeline steps in Docker containers, so the compute, storage, and network come from wherever you deploy it. If you self-host on your own machine or a server you already pay for, the marginal cost can be near zero. If you rent a VPS or cloud instance to run it, that bill is yours.

The same logic applies to maintenance: no vendor is charging you, but someone has to run upgrades, manage secrets, and keep the server healthy.

Open source and extensibility

The open-source nature connects directly to how you extend Woodpecker. Pipelines execute as Docker containers, and when a plain Docker image is not enough, you can write plugins to add pipeline features. Because the engine is open source, plugin and pipeline behavior is something you can verify rather than take on faith — useful when a step needs to do something unusual.

Woodpecker also supports multiple workflows for a project, and those workflows can depend on each other. That lets you split a large pipeline into stages that run in a controlled order instead of one long job.

How this differs from commercial CI/CD services

The practical takeaway: choose Woodpecker when you want no license fee, control over where builds run, and the ability to read and modify the engine. Choose a commercial service when you would rather pay someone else to host runners and handle operations.

Before you decide

Two things are worth confirming for your own situation, since the project page does not spell them out:

1. Where you will host it. Self-hosting shifts cost from a subscription to servers and maintenance.
2. What your pipelines need. If your steps fit standard Docker images, setup is simpler; if not, plan for plugin work.

If you want to check current capabilities, workflow configuration, or contribution paths, the project's documentation is the authoritative source.

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:

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.

Woodpecker CI's official documentation is reachable from its website, woodpecker-ci.org, which links to the docs and describes the project as an open-source, free CI/CD engine. The site states that Woodpecker "is and always will be totally free," that its source code is open-source so you can contribute, and that pipelines run in Docker containers with plugins available for extending pipeline features. If you want to start using it or help build it, the site itself is the entry point; the sections below cover what you'll find there and what to do next.

What Woodpecker CI Is

Woodpecker is a CI/CD engine built around Docker containers. Each pipeline step executes in a container, and when a normal Docker image isn't enough, you can write plugins to extend what a pipeline can do. The site also highlights multi-workflow support: you can define several workflows for one project, and they can depend on each other.

That combination — container-based steps, a plugin mechanism, and interdependent workflows — is the core of what the project offers, and it shapes both how you'd use it and how you'd contribute to it.

Finding the Documentation

The website is the starting point. From woodpecker-ci.org you can reach the project's docs, which cover how pipelines, plugins, and multi-workflow setups work. The site explicitly points readers to the docs for details on multiple workflows, so that's the place to go when you need configuration specifics rather than a general overview.

A practical path:

1. Open woodpecker-ci.org.
2. Follow the link to the documentation.
3. Read the pipeline and plugin sections first if you plan to run builds, or the workflow section if you need several pipelines that depend on each other.

Getting the Source and Contributing

Because Woodpecker's source code is open-source, contributing is a stated option on the site — the project invites you to "contribute to help evolving the project." The site doesn't spell out a contribution process in the material available here, so the concrete steps (where the repository lives, how to open issues or pull requests, coding conventions) come from the docs and the repository itself rather than the landing page.

If you want to contribute, the realistic sequence is:

• Read the docs to understand how pipelines, plugins, and workflows are structured.
• Locate the source repository through the links on the site.
• Start with the contribution guidance in the docs or repository before submitting changes.

What to Do Next

The site confirms three things you can rely on: Woodpecker is free and open-source, pipelines run on Docker containers, and plugins extend pipeline features. Anything beyond that — installation steps, exact configuration syntax, contribution rules — lives in the documentation and repository, which is where you should go next.