Woodpecker CI

Woodpecker is a lightweight, self-hosted, container-native CI system (a community fork of Drone, see Drone CI). Every step runs in a container, workflows live in .woodpecker/*.yaml (or a single .woodpecker.yaml) in the repo, and it connects to Gitea/Forgejo, GitHub, GitLab or Bitbucket. This sheet targets Woodpecker v3 (latest release seen: v3.20.1); v2 differences are in the last table. For overall concepts see CI/CD Overview, for the forge see Gitea (and Forgejo), and for image builds see CI Docker Builds.

Documentation: Woodpecker docs, Workflow syntax, CLI

Minimal Workflow #

# .woodpecker/test.yaml
when:
  - event: [push, pull_request]
    branch: main            # for pull_request this matches the target branch

steps:
  - name: test
    image: node:22
    commands:
      - npm ci
      - npm test

Several files in .woodpecker/ are separate workflows that run in parallel unless linked with depends_on. A pipeline is one run containing all of its workflows.

Step Keywords #

Steps can be a list (shown above, the v3 form) or a map keyed by name; both are accepted.

Workflow Level Keywords #

when Conditions #

A when list is OR-ed; the keys inside one list item are AND-ed.

steps:
  - name: deploy
    image: alpine
    commands: [./deploy.sh]
    when:
      - event: push
        branch: main
      - event: tag
        ref: refs/tags/v*
      - event: manual
      - evaluate: 'not (CI_COMMIT_MESSAGE contains "[skip deploy]")'
        event: push
  - name: notify-failure
    image: alpine
    commands: [./notify.sh]
    when:
      - status: [failure]
        event: [push, tag]

Always give every when item an event filter; the built-in linter warns otherwise, because new event types would trigger the step.

Services, Dependencies and Matrix #

matrix:
  GO_VERSION: ["1.23", "1.24"]
  DB: [postgres, mariadb]

services:
  - name: database
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: example     # throw-away CI value

steps:
  - name: build
    image: golang:${GO_VERSION}
    commands: [go build ./...]
  - name: test
    image: golang:${GO_VERSION}
    depends_on: [build]
    environment:
      DATABASE_URL: postgres://postgres:example@database:5432/postgres
    commands: [go test ./...]

Matrix variables are substituted with ${VAR} before the YAML is parsed. Use include: to list explicit combinations instead of a full product.

Workflow dependencies across files:

# .woodpecker/deploy.yaml
depends_on: [lint, test]          # files .woodpecker/lint.yaml and test.yaml
when:
  - event: push
    branch: main

In a monorepo with when.path, mark dependencies optional: true (depends_on: [{name: lint, optional: true}]) so a skipped workflow does not block the deploy.

Secrets #

Add secrets under repo Settings > Secrets, or with the CLI. By default a secret is not available to pull_request events (enable that event explicitly and only for safe secrets). You can also restrict a secret to named plugin images.

steps:
  - name: publish
    image: woodpeckerci/plugin-docker-buildx
    settings:
      repo: ghcr.io/<OWNER>/<IMAGE>
      registry: ghcr.io
      username: <USER>
      password:
        from_secret: ghcr_token
      tags: latest
    when:
      - event: push
        branch: main

  - name: call-api
    image: curlimages/curl
    environment:
      API_TOKEN:
        from_secret: api_token
    commands:
      - 'curl -fsS -H "Authorization: Bearer $API_TOKEN" https://api.example.com/ping'

Write $VAR (not ${VAR}) for runtime shell variables in commands; ${...} expressions are pre-processed before the pipeline starts. Escape them as $${VAR} if you need a literal.

Built-in Variables #

Cron and Manual Runs #

• Cron: in the repo settings add a cron job (name + schedule), then give the steps event: cron (and optionally cron: <NAME>).
• Manual: use the “Run pipeline” button or woodpecker-cli pipeline create; steps need event: manual to run. Variables passed with --var are available as environment variables.
• Deployments: woodpecker-cli pipeline deploy <REPO> <PIPELINE> <ENVIRONMENT> creates a deployment event with CI_PIPELINE_DEPLOY_TARGET.

woodpecker-cli #

Point the CLI at the server and authenticate with your personal token (User settings > Personal access token):

export WOODPECKER_SERVER=https://woodpecker.modem7.com
export WOODPECKER_TOKEN=<TOKEN>

Run woodpecker-cli <COMMAND> --help to confirm flags on your version.

Server and Agent (Docker Compose) #

The server serves the UI/API and talks to the forge; one or more agents execute the workflows. See Docker-Compose.

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v3
    restart: unless-stopped
    ports: ["8000:8000"]
    volumes:
      - woodpecker-data:/var/lib/woodpecker
    environment:
      WOODPECKER_HOST: https://woodpecker.example.com
      WOODPECKER_AGENT_SECRET: ${WOODPECKER_AGENT_SECRET}
      WOODPECKER_GITEA: "true"                      # or WOODPECKER_GITHUB / WOODPECKER_FORGEJO
      WOODPECKER_GITEA_URL: https://git.example.com
      WOODPECKER_GITEA_CLIENT: ${GITEA_OAUTH_CLIENT}
      WOODPECKER_GITEA_SECRET: ${GITEA_OAUTH_SECRET}
      WOODPECKER_ADMIN: <USER>

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v3
    restart: unless-stopped
    depends_on: [woodpecker-server]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WOODPECKER_SERVER: woodpecker-server:9000
      WOODPECKER_AGENT_SECRET: ${WOODPECKER_AGENT_SECRET}
      WOODPECKER_MAX_WORKFLOWS: 2

volumes:
  woodpecker-data:

Generate the shared secret with openssl rand -hex 32 (OpenSSL) and keep it in an .env file out of Git. The server needs a working webhook path from the forge and an OAuth app on the forge.

Docker Backend Notes #

• Each step is a container on a per-workflow Docker network; services are reachable by their name.
• The agent needs the Docker socket, which is root-equivalent on the host. Treat anyone who can edit a pipeline as able to run code on the agent host.
• privileged, volumes and custom networks only work for repositories an admin marks Trusted (repo Settings). Docker-in-Docker (docker:dind service) needs privileged: true.
• Extra agent settings: WOODPECKER_BACKEND_DOCKER_NETWORK, WOODPECKER_BACKEND_DOCKER_VOLUMES, WOODPECKER_MAX_WORKFLOWS, WOODPECKER_AGENT_LABELS.
• Agent images accumulate; prune on a schedule (docker image prune -af --filter until=168h).
• For image builds use woodpeckerci/plugin-docker-buildx (see CI Docker Builds) or a dind service.

v2 to v3 Differences #

Source: migration notes. Run woodpecker-cli lint after migrating.

Troubleshooting #