Skip to main content
šŸŽ¤ Luca Berton is speaking at Red Hat Summit & KubeCon EU 2026!Learn more →
Back to Blog

Woodpecker CI Self-Hosted Pipelines

Woodpecker CI is a lightweight, container-native CI/CD system you can self-host. Learn how Woodpecker compares to Drone, GitHub Actions, and GitLab CI.

Luca BertonFebruary 6, 20262 min read

GitHub Actions is convenient until you need custom runners, air-gapped builds, or control over your CI infrastructure. Woodpecker CI gives you a self-hosted, container-native pipeline system in minutes.

What Woodpecker Is

Woodpecker is a community fork of Drone CI. Every step runs in a container. No plugin marketplace lock-in — any Docker image is a valid step.

Installation

yaml
# docker-compose.yml
services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    ports:
      - "8000:8000"
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=https://ci.myorg.com
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=your-client-id
      - WOODPECKER_GITHUB_SECRET=your-client-secret
      - WOODPECKER_AGENT_SECRET=shared-secret
    volumes:
      - woodpecker-data:/var/lib/woodpecker

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=shared-secret
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
Related Course

Master this topic with hands-on labs

Go beyond reading — build real projects in sandboxed environments with expert video guidance.

Browse Courses →

Pipeline Configuration

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

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

  - name: test
    image: node:20-alpine
    commands:
      - npm test

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

  - name: docker
    image: plugins/docker
    settings:
      repo: myorg/order-api
      tags: ${CI_COMMIT_SHA}
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
    when:
      branch: main
      event: push

Multi-Pipeline

Split pipelines into separate files:

.woodpecker/
ā”œā”€ā”€ test.yml      # Runs on every push
ā”œā”€ā”€ build.yml     # Runs on main branch
ā”œā”€ā”€ deploy.yml    # Runs on tag
└── security.yml  # Runs weekly
yaml
# .woodpecker/test.yml
when:
  event: [push, pull_request]

steps:
  - name: test
    image: node:20-alpine
    commands:
      - npm ci
      - npm test
yaml
# .woodpecker/deploy.yml
when:
  event: tag

steps:
  - name: deploy
    image: myorg/deployer:latest
    commands:
      - kubectl set image deployment/order-api order-api=myorg/order-api:${CI_COMMIT_TAG}
    secrets: [kube_config]

Services

Run databases and caches alongside your tests:

yaml
services:
  - name: postgres
    image: postgres:16
    environment:
      POSTGRES_DB: test
      POSTGRES_PASSWORD: test

  - name: redis
    image: redis:7-alpine

steps:
  - name: test
    image: node:20-alpine
    environment:
      DATABASE_URL: postgres://postgres:test@postgres:5432/test
      REDIS_URL: redis://redis:6379
    commands:
      - npm ci
      - npm test
Stay Updated

Get weekly IT automation tips

Docker, Ansible, Terraform, MLOps — curated insights delivered to your inbox. No spam.

Subscribe Free →

Matrix Builds

yaml
matrix:
  NODE_VERSION:
    - "18"
    - "20"
    - "22"

steps:
  - name: test
    image: node:${NODE_VERSION}-alpine
    commands:
      - node --version
      - npm ci
      - npm test

Kubernetes Agent

yaml
# Woodpecker agent on Kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: woodpecker-agent
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: agent
          image: woodpeckerci/woodpecker-agent:latest
          env:
            - name: WOODPECKER_SERVER
              value: "woodpecker-server:9000"
            - name: WOODPECKER_AGENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: woodpecker-secrets
                  key: agent-secret
            - name: WOODPECKER_BACKEND
              value: kubernetes

Woodpecker vs Alternatives

FeatureWoodpeckerGitHub ActionsGitLab CIDrone
Self-hostedYesRunners onlyYesYes
Container-nativeYesYesYesYes
LicenseApache 2.0ProprietaryProprietaryProprietary
Config formatYAMLYAMLYAMLYAML
Matrix buildsYesYesYesLimited
Setup complexityLowN/AHighLow
Multi-platformYesYesYesYes
PluginsDocker imagesMarketplaceTemplatesDocker images

Use Woodpecker for self-hosted CI with zero vendor lock-in. Use GitHub Actions for convenience with GitHub repos. Use GitLab CI if you are already on GitLab.

---

Ready to go deeper? Master CI/CD pipelines with hands-on courses at CopyPasteLearn.

Ready to learn by doing?

Stop reading tutorials — start building. Expert video courses with hands-on labs in real sandboxed environments.

Share this article
LB
Luca Berton

Docker Captain, IT automation expert, Red Hat Summit & KubeCon speaker. Building hands-on education for DevOps engineers at CopyPasteLearn.

Related Articles

Explore topics

Browse more articles on the topics covered here.