Woodpecker CI Self-Hosted

Deploy Woodpecker CI as a lightweight self-hosted CI/CD system with Docker pipelines and GitHub/Gitea integration. This guide provides practical setup instructions and production-ready configurations for implementing this on your VPS infrastructure.

Installation

# docker-compose.yml
services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    ports:
      - "8000:8000"
    environment:
      WOODPECKER_HOST: https://ci.example.com
      WOODPECKER_GITHUB: true
      WOODPECKER_GITHUB_CLIENT: your-github-client-id
      WOODPECKER_GITHUB_SECRET: your-github-client-secret
      WOODPECKER_AGENT_SECRET: your-shared-secret
      WOODPECKER_DATABASE_DRIVER: postgres
      WOODPECKER_DATABASE_DATASOURCE: postgres://ci:password@postgres:5432/woodpecker?sslmode=disable
    volumes:
      - woodpecker-data:/var/lib/woodpecker
    depends_on:
      - postgres

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    environment:
      WOODPECKER_SERVER: woodpecker-server:9000
      WOODPECKER_AGENT_SECRET: your-shared-secret
      WOODPECKER_MAX_WORKFLOWS: 4
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - woodpecker-server

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: woodpecker
      POSTGRES_USER: ci
      POSTGRES_PASSWORD: password
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  woodpecker-data:
  pgdata:

Pipeline Configuration

# .woodpecker.yml
steps:
  - name: test
    image: node:20-alpine
    commands:
      - npm ci
      - npm test

  - name: build
    image: node:20-alpine
    commands:
      - npm run build

  - name: docker
    image: plugins/docker
    settings:
      repo: registry.example.com/myapp
      tags: ["${CI_COMMIT_SHA:0:8}", "latest"]
      registry: registry.example.com
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
    when:
      branch: main

  - name: deploy
    image: appleboy/drone-ssh
    settings:
      host: production.example.com
      username: deploy
      key:
        from_secret: ssh_key
      script:
        - docker pull registry.example.com/myapp:latest
        - docker-compose up -d
    when:
      branch: main

Matrix Builds

# Test across multiple versions
steps:
  - name: test
    image: node:${NODE_VERSION}-alpine
    commands:
      - npm ci
      - npm test

matrix:
  NODE_VERSION:
    - 18
    - 20
    - 22

Summary

Woodpecker CI is a lightweight, community-driven CI/CD system forked from Drone. It provides Docker-native pipelines, GitHub/Gitea integration, matrix builds, and secrets management — all in a self-hosted package that uses minimal resources. For teams wanting a simple, fast CI system without the complexity of Jenkins or the cost of hosted services, Woodpecker on a VPS is an excellent choice.