Woodpecker CI, with no SaaS anywhere in the path

How to install Woodpecker CI with Docker Compose

Server and agent on one host, wired to GitHub in this example. Swap the forge block for the Gitea, Forgejo, GitLab or Bitbucket variables if your forge is one of those.

1. 1

   Install Docker and Compose

   sudo apt install docker.io docker-compose-v2
   sudo systemctl enable --now docker

   Both containers and every pipeline step run on this daemon, so this is the only dependency the host needs.

2. 2

   Register an OAuth application on your forge

   # GitHub: Settings -> Developer settings -> OAuth Apps -> New OAuth App
   # Homepage URL:     https://ci.example.com
   # Authorization callback: https://ci.example.com/authorize

   Woodpecker signs users in through the forge and reads repositories with that grant, so the client id and secret it hands back are what the server needs. Every supported forge has an equivalent form.

3. 3

   Generate the shared agent secret

   openssl rand -hex 32

   The server and the agents authenticate to each other with this string, and Woodpecker documentation names this exact command for producing it. Keep it out of the compose file - put it in an .env file beside it.

4. 4

   Write the compose file

   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:

   This is the upstream example. WOODPECKER_HOST is the public URL users and webhooks reach, port 8000 is the web interface and 9000 is the gRPC port agents connect on. WOODPECKER_OPEN=true lets anyone with a forge account sign in - turn it off once your team is registered.

5. 5

   Start it

   docker compose up -d
   docker compose logs -f woodpecker-agent

   The agent connects to the server with the shared secret and registers itself on first contact. If it loops on an authentication error, the two secrets do not match - most often because the .env file was not picked up.

6. 6

   Add a pipeline

   when:
     - event: push
   
   steps:
     - name: smoke
       image: alpine:latest
       commands:
         - cat /etc/os-release
         - echo "built on $CI_MACHINE"

   Commit that as .woodpecker.yaml, enable the repository in the web interface so the webhook is created, and push. Each step is a container, which is why the agent needs the Docker socket.

Checked against the official documentation on 2026-08-15 — read the source