MirrorNest
← All guides

Woodpecker CI

Woodpecker CI is a lightweight, container-native continuous integration engine that runs YAML pipelines in isolated containers, with a small server/agent architecture and a built-in SQLite database by default.

Target: Any Docker hostDevOpsCI/CDOfficial homepage ↗Official docs ↗
This guide is synthesized from Woodpecker CI's own official documentation, linked above — always cross-check exact package/version names there before running these commands on a production server, since distro and project versions move over time.

  1. 1Register an OAuth application with your forge

    Woodpecker authenticates through your Git forge (GitHub, Gitea, Forgejo, GitLab, Bitbucket). Create an OAuth app there first and note the client ID/secret.

  2. 2Generate a shared agent secret

    openssl rand -hex 32

    The server and every agent authenticate to each other using this same secret.

  3. 3Define server and agent in docker-compose.yaml

    services: woodpecker-server: image: woodpeckerci/woodpecker-server:v3 ports: - 8000:8000 volumes: - woodpecker-server-data:/var/lib/woodpecker/ environment: - WOODPECKER_OPEN=true - WOODPECKER_HOST=${WOODPECKER_HOST} - WOODPECKER_GITHUB=true - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT} - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET} - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} woodpecker-agent: image: woodpeckerci/woodpecker-agent:v3 command: agent restart: always depends_on: - woodpecker-server volumes: - woodpecker-agent-config:/etc/woodpecker - /var/run/docker.sock:/var/run/docker.sock environment: - WOODPECKER_SERVER=woodpecker-server:9000 - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} volumes: woodpecker-server-data: woodpecker-agent-config:

  4. 4Set environment variables and start

    WOODPECKER_HOST must be the public address in <scheme>://<hostname> form (no trailing slash).

    docker compose up -d

  5. 5First login

    Visit your WOODPECKER_HOST URL, log in via your forge's OAuth flow, and enable repositories you want Woodpecker to build.