Skip to content
Back to Deployment

Deploying with Woodpecker CI

Community fork of Drone CI with improved features and active development.

CI/CDIntermediate

Why

Woodpecker is a lightweight, container-native CI that's fully open-source and self-hostable. DORA's 2024 State of DevOps report shows elite teams deploy 973x more frequently than low performers.

CI/CD pipelines with automated testing reduce change failure rate to 5-15% versus 40-60% for manual deployments.

When

Self-hosted CI needs with Docker-native execution and Gitea/Forgejo integration. Avoid complex pipeline orchestration for repos with fewer than 5 contributors — a pre-commit hook + GitHub Actions suffices.

Skip self-hosted runners unless you need GPU or VPN access.

How

# .woodpecker.yml steps: build: image: node:20 commands: - npm ci - npm run build - npm test deploy: image: bitnami/kubectl commands: - kubectl apply -f k8s/ when: branch: main event: push 4. Verify deployment — curl -I https://your-app.example.com 5. Monitor logs — check for errors in first 5 minutes 6. Rollback if needed — revert to previous version

Example

# Woodpecker server via Docker docker run -d --name woodpecker-server \ -p 8000:8000 \ -e WOODPECKER_OPEN=true \ -e WOODPECKER_HOST=https://ci.example.com \ -e WOODPECKER_GITEA=true \ -e WOODPECKER_GITEA_URL=https://gitea.example.com \ -v woodpecker-data:/var/lib/woodpecker \ woodpeckerci/woodpecker-server:latest

Common Problems

  • ⚠Agent can't pull images — check Docker socket mount
  • ⚠Webhook not firing — verify repo settings in Gitea
  • ⚠Configuration drift between environments — use infrastructure-as-code (Terraform/Pulumi) to keep dev/staging/prod identical

Best Practices

  • ✓Use matrix builds — test across Node versions
  • ✓Use Woodpecker secrets — never hardcode credentials
  • ✓Set up health checks and graceful shutdown — handle SIGTERM to drain in-flight requests before exit

FAQ