How to Install & Set Up Woodpecker CI

Deploy Woodpecker CI — a lightweight, container-native pipeline engine — with Docker Compose, wired to your Git forge.

Updated 20262-step setupDownload Woodpecker CI →

Prerequisites

✓Docker and Docker Compose
✓An OAuth app on your Git host (GitHub, GitLab, Gitea, or Forgejo) for login

Create a docker-compose.yml

docker-compose.yml

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    ports:
      - 8000:8000
    environment:
      - WOODPECKER_HOST=https://ci.example.com
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=https://gitea.example.com
      - WOODPECKER_GITEA_CLIENT=your-client-id
      - WOODPECKER_GITEA_SECRET=your-client-secret
      - WOODPECKER_AGENT_SECRET=a-shared-secret
    volumes:
      - woodpecker-data:/var/lib/woodpecker
  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    command: agent
    depends_on: [woodpecker-server]
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=a-shared-secret
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
volumes:
  woodpecker-data:

Start and verify

Open http://your-host:8000 and authorize with your Git host to see your repositories.

terminal

docker compose up -d

This whole install is Docker Compose, so it's byte-for-byte the same on RHEL, Fedora, Debian, or Ubuntu — Woodpecker never touches the host's native package manager.

Documentation & Knowledge Base

Official DocumentationWoodpecker CI Documentation →Knowledge Base & CommunityWoodpecker GitHub Discussions →

Download Woodpecker CI— all versions & official links→

Need Woodpecker CI deployed and managed for you?

We're OpenStack Dev — we design, deploy, and operate production DevOps infrastructure.

Get in Touch All Install Guides