woodpecker-cli exec: Run a Woodpecker Pipeline Locally
woodpecker-cli exec executes a Woodpecker pipeline on your machine using the local Docker backend, so you can test steps without a server.
Like act for GitHub Actions, woodpecker-cli exec runs the pipeline locally. It is the fastest way to test a Woodpecker step change before it hits the server.
What it does
woodpecker-cli exec reads a pipeline file and runs its steps in Docker containers locally, injecting the environment and metadata a real run would have. You can set the event and repo context via flags.
Common usage
woodpecker-cli exec .woodpecker.yml
woodpecker-cli exec --backend-engine local .woodpecker.yml
woodpecker-cli exec --pipeline-event pull_request .woodpecker.yml
woodpecker-cli exec --env MY_VAR=value .woodpecker.ymlOptions
| Flag | What it does |
|---|---|
| [path] | Pipeline file to execute |
| --backend-engine <engine> | docker (default) or local |
| --pipeline-event <event> | Simulate push, pull_request, tag, etc. |
| --env <KEY=val> | Set an environment variable for the run |
| --local | Run using the local filesystem instead of cloning |
In CI
exec is a local development tool. Use it to iterate on steps, and use woodpecker-cli lint as the PR gate. Running it inside CI requires a Docker-in-Docker setup similar to act.
Common errors in CI
Cannot connect to the Docker daemon means Docker is not running or the socket is not available (see the CI errors module). Error: open .woodpecker.yml: no such file or directory means the path is wrong. Steps that expect server-only metadata may print empty values because exec only simulates the run.