Self-host Woodpecker CI
updated Sep 2026prices checked · Jul 2026
We earn commissions when you shop through the links below. Full disclosure →
A lightweight CI/CD engine, forked from Drone, that runs pipelines defined in YAML as Docker containers. It has no user accounts of its own: you log in through a connected forge such as GitHub, Gitea, Forgejo or GitLab.
Key facts
CategoryCI/CD
LicenseApache-2.0
StackGo, Vue
Min RAM256 MB
Official imageyes
Difficulty
What you need
- Any VPS with at least 256 MB of RAM
- A domain you control — most self-hosted setups need HTTPS in front of them
- Under an hour if you've used Docker before
Where to host itaffiliate disclosure
Hetzner Cloudrun it on
From $23.59/mo · 2 vCPU / 4 GB / 80 GB · EU + USKamaterafree trial
From $4/mo · 1 vCPU / 1 GB / 20 GB · US + EU + AsiaDigitalOceanalso works on
From $6/mo · 1 vCPU / 1 GB / 25 GB · US + EU + AsiaPaid link — we earn a commission if you shop through it.
Install
Run these commands on your server:
# Woodpecker server + agent — official compose (GitHub forge); create a GitHub OAuth app first,
# callback URL http://SERVER_IP:8000/authorize, and paste its client id + secret below
mkdir -p ~/woodpecker && cd ~/woodpecker
cat > .env <<EOF
WOODPECKER_HOST=http://SERVER_IP:8000
WOODPECKER_GITHUB_CLIENT=your-github-oauth-client-id
WOODPECKER_GITHUB_SECRET=your-github-oauth-client-secret
WOODPECKER_AGENT_SECRET=$(openssl rand -hex 32)
EOF
cat > docker-compose.yml <<'EOF'
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:
EOF
docker compose up -d
# open http://SERVER_IP:8000 and log in with GitHubMore self-hosted tools
CI/CD
Jenkins
Java
easyRead guide →
CI/CD
Semaphore UI
GoVue
easyRead guide →
Push notifications
ntfy
Go
easyRead guide →
SSO & Identity
Pocket ID
GoSvelteKit
easyRead guide →