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
# 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.sockMaster this topic with hands-on labs
Go beyond reading ā build real projects in sandboxed environments with expert video guidance.
Browse Courses āPipeline Configuration
# .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: pushMulti-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# .woodpecker/test.yml
when:
event: [push, pull_request]
steps:
- name: test
image: node:20-alpine
commands:
- npm ci
- npm test# .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:
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 testGet weekly IT automation tips
Docker, Ansible, Terraform, MLOps ā curated insights delivered to your inbox. No spam.
Subscribe Free āMatrix Builds
matrix:
NODE_VERSION:
- "18"
- "20"
- "22"
steps:
- name: test
image: node:${NODE_VERSION}-alpine
commands:
- node --version
- npm ci
- npm testKubernetes Agent
# 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: kubernetesWoodpecker vs Alternatives
| Feature | Woodpecker | GitHub Actions | GitLab CI | Drone |
|---|---|---|---|---|
| Self-hosted | Yes | Runners only | Yes | Yes |
| Container-native | Yes | Yes | Yes | Yes |
| License | Apache 2.0 | Proprietary | Proprietary | Proprietary |
| Config format | YAML | YAML | YAML | YAML |
| Matrix builds | Yes | Yes | Yes | Limited |
| Setup complexity | Low | N/A | High | Low |
| Multi-platform | Yes | Yes | Yes | Yes |
| Plugins | Docker images | Marketplace | Templates | Docker 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.
Related Articles
Dagger CI/CD Pipelines as Code
Dagger lets you write CI/CD pipelines in real programming languages instead of YAML. Learn how Dagger works, how it compares to GitHub Actions.
Earthly Reproducible Build Tool
Earthly combines Dockerfiles and Makefiles into reproducible, containerized builds. Learn how Earthly works, how to write Earthfiles, and when it replaces.
Makefile for Container Workflows
Use Makefiles to streamline container workflows. Build, test, push, deploy targets with environment variables and CI integration.
YAML for DevOps Engineers
Master YAML for DevOps configuration. Scalars, lists, maps, anchors, multi-line strings, and common pitfalls to avoid in pipelines.
YAML Syntax Guide for DevOps
Master YAML syntax for DevOps tools. Scalars, lists, maps, anchors, multi-line strings, and common gotchas with pipeline examples.
10 Things to Do After Installing OpenClaw
Just installed OpenClaw? Here are 10 essential setup steps to get the most out of your AI agent ā from personality to automation.
Explore topics
Browse more articles on the topics covered here.