How to Set Up Woodpecker CI: Ultra-Lightweight Open-Source CI/CD Engine

Continuous integration engines are notorious resource hogs. Popular solutions like self-hosted Jenkins, GitLab CI, or TeamCity can quickly consume 4GB to 8GB of RAM just to keep their baseline web interfaces and Java runtimes operational. For independent developers, small teams, and open-source creators running budget Linux VPS instances, allocating that much memory solely to a CI server is wasteful.

Woodpecker CI—a community-driven, open-source fork of Drone CI—solves this problem completely. Built entirely in Go, Woodpecker operates on a clean container-native pipeline model: every build step executes inside an ephemeral Docker container. The entire Woodpecker server and agent stack consumes less than 100MB of RAM at idle, providing modern YAML-driven CI/CD pipelines on any entry-level VPS.

1. Why Woodpecker Outperforms Legacy CI Systems

Woodpecker’s architecture delivers several distinct advantages for small-to-medium teams:

• Extremely Low Memory Footprint: Runs smoothly on a 1GB RAM VPS alongside your web applications.
• Zero Pipeline Pollution: Because each build step runs inside a fresh Docker container, build dependencies (such as Node.js, Python, or Go SDKs) never need to be installed directly on the host operating system.
• Native Git Forge Integration: Supports seamless OAuth integration with GitHub, GitLab, Gitea, and Forgejo.
• Simple Declarative Pipelines: Pipelines are declared using human-readable .woodpecker.yaml syntax that mirrors modern GitHub Actions conventions.

2. Production Woodpecker Architecture: Server & Agent

Woodpecker separates management and execution into two lightweight daemons:

1. Woodpecker Server: Handles webhooks, user authentication, pipeline queue scheduling, and the web UI.
2. Woodpecker Agent: Polls the server for pending jobs and orchestrates local Docker containers to execute pipeline steps.

Below is a production docker-compose.yml file integrating Woodpecker with GitHub OAuth authentication:

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - /opt/woodpecker/data:/var/lib/woodpecker
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=https://ci.yourdomain.com
      - WOODPECKER_SERVER_ADDR=:8000
      - WOODPECKER_AGENT_SECRET=GenerateRandom64CharSecretStringHere!
      # GitHub OAuth Configuration
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_OAUTH_CLIENT_ID
      - WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_OAUTH_CLIENT_SECRET
    deploy:
      resources:
        limits:
          memory: 256M

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    restart: unless-stopped
    depends_on:
      - woodpecker-server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=GenerateRandom64CharSecretStringHere!
      - WOODPECKER_MAX_WORKFLOWS=2
    deploy:
      resources:
        limits:
          memory: 128M

3. Creating GitHub OAuth Application

To enable authentication, register an OAuth application in GitHub:

1. In GitHub, go to Settings > Developer settings > OAuth Apps > New OAuth App.
2. Set Application name to Woodpecker CI.
3. Set Homepage URL to https://ci.yourdomain.com.
4. Set Authorization callback URL to https://ci.yourdomain.com/authorize.
5. Copy the generated Client ID and Client Secret into your Compose environment variables.

4. Writing Your First .woodpecker.yaml Pipeline

Create a .woodpecker.yaml file in the root of any repository you want Woodpecker to test and build. Below is an enterprise pipeline that tests a Node.js application, builds a production Docker image, and notifies your team:

steps:
  lint:
    image: node:20-alpine
    commands:
      - npm ci
      - npm run lint

  test:
    image: node:20-alpine
    commands:
      - npm test
    depends_on:
      - lint

  build_image:
    image: plugins/docker
    settings:
      registry: ghcr.io
      repo: ghcr.io/organization/production-app
      tags:
        - latest
        - ${CI_COMMIT_SHA:0:8}
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
    when:
      branch: main
      event: push
    depends_on:
      - test

Every step executes in parallel or sequentially based on the depends_on directive, providing deterministic build times without eating server resources.

Woodpecker CI Production Optimization, Matrix Builds & Vault Integration

Maximize the efficiency and security of your lightweight Woodpecker CI pipeline infrastructure on Linux VPS:

• Configuring Matrix Testing Across Node/Python Versions: Woodpecker supports matrix testing without spawning bloated external agents. Test your application across multiple language runtimes simultaneously using concise YAML declarations:

  matrix:
    NODE_VERSION:
      - 18-alpine
      - 20-alpine
      - 22-alpine
  
  steps:
    test:
      image: node:${NODE_VERSION}
      commands:
        - npm ci
        - npm test

• Global Pipeline Secret Management: Instead of embedding sensitive credentials in repositories, define global or repository-level encrypted secrets via the Woodpecker web UI or CLI. Secrets are injected into container environments only during authenticated branch builds.
• Docker-in-Docker (DinD) Security Safeguards: When building Docker images inside Woodpecker, utilize the dedicated plugins/docker image which provides an isolated build context without requiring the insecure privileged: true host socket mount.
• Automatic Resource Garbage Collection: Prevent pipeline artifacts and intermediate container layers from exhausting VPS disk space by running automated Docker pruning cron jobs:

  # Clean dangling builder images weekly
  0 4 * * 0 docker image prune -a --filter "until=168h" -f