# Woodpecker CI — Simple Yet Powerful CI/CD Engine

> Woodpecker is a lightweight, container-based CI/CD engine forked from Drone. Simple YAML pipelines, Docker-native execution, and multi-platform support.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
docker run -d --name woodpecker-server 
  -p 8000:8000 
  -v woodpecker-data:/var/lib/woodpecker 
  -e WOODPECKER_OPEN=true 
  -e WOODPECKER_HOST=http://localhost:8000 
  -e WOODPECKER_GITHUB=true 
  -e WOODPECKER_GITHUB_CLIENT=your-client-id 
  -e WOODPECKER_GITHUB_SECRET=your-client-secret 
  woodpeckerci/woodpecker-server:latest
```

Open `http://localhost:8000` — login with GitHub and activate your repositories.

## Intro

**Woodpecker CI** is a community-driven, lightweight CI/CD engine that runs pipelines in containers. Originally forked from Drone CI, Woodpecker focuses on simplicity, extensibility, and community governance. It uses simple YAML pipeline definitions and executes every step in an isolated Docker container.

With 6.8K+ GitHub stars and Apache-2.0 license, Woodpecker is popular among self-hosters and small teams who want a simple, self-hosted CI/CD solution without the complexity of Jenkins or GitLab CI.

## What Woodpecker Does

- **Container-Native**: Every pipeline step runs in its own Docker container
- **YAML Pipelines**: Simple, readable pipeline definitions in `.woodpecker.yml`
- **Multi-Platform**: Build for linux/amd64, arm64, arm, and windows
- **Git Integration**: GitHub, GitLab, Gitea, Forgejo, and Bitbucket support
- **Parallel Execution**: Run steps and pipelines in parallel
- **Matrix Builds**: Test across multiple versions/configurations
- **Secrets Management**: Encrypted secrets per repository or organization
- **Plugins**: 100+ community plugins for Docker, Slack, S3, etc.
- **Cron Jobs**: Schedule periodic pipeline runs

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Git Forge   │────▶│  Woodpecker  │────▶│  Woodpecker  │
│  (GitHub/    │webhook│  Server     │     │  Agent(s)    │
│  Gitea/etc)  │     │  (Go)        │     │  (Docker)    │
└──────────────┘     └──────────────┘     └──────────────┘
```

- **Server**: Handles webhooks, manages pipelines, serves web UI
- **Agent**: Executes pipeline steps in Docker containers (can run on multiple machines)

## Self-Hosting

### Docker Compose

```yaml
services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    ports:
      - "8000:8000"
    environment:
      WOODPECKER_OPEN: "true"
      WOODPECKER_HOST: https://ci.yourdomain.com
      WOODPECKER_GITHUB: "true"
      WOODPECKER_GITHUB_CLIENT: your-github-oauth-client-id
      WOODPECKER_GITHUB_SECRET: your-github-oauth-client-secret
      WOODPECKER_AGENT_SECRET: your-shared-agent-secret
    volumes:
      - woodpecker-data:/var/lib/woodpecker

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

volumes:
  woodpecker-data:
```

### With Gitea

```yaml
environment:
  WOODPECKER_GITEA: "true"
  WOODPECKER_GITEA_URL: https://gitea.yourdomain.com
  WOODPECKER_GITEA_CLIENT: your-gitea-oauth-client-id
  WOODPECKER_GITEA_SECRET: your-gitea-oauth-client-secret
```

## Pipeline Examples

### Basic CI

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

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

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

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

### With Services (Database Testing)

```yaml
steps:
  - name: test
    image: python:3.12
    commands:
      - pip install -r requirements.txt
      - pytest --db-url=postgresql://test:test@postgres:5432/testdb

services:
  - name: postgres
    image: postgres:16
    environment:
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
      POSTGRES_DB: testdb
```

### Docker Build & Push

```yaml
steps:
  - name: build-and-push
    image: woodpeckerci/plugin-docker-buildx
    settings:
      repo: myregistry.com/myapp
      tags: latest,${CI_COMMIT_SHA:0:8}
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
    when:
      branch: main
      event: push
```

### Matrix Builds

```yaml
matrix:
  GO_VERSION:
    - "1.21"
    - "1.22"
  DATABASE:
    - postgres
    - mysql

steps:
  - name: test
    image: golang:${GO_VERSION}
    commands:
      - go test ./... -db=${DATABASE}
```

### Multi-Pipeline (Parallel)

```yaml
# .woodpecker/test.yml
steps:
  - name: test
    image: node:20
    commands:
      - npm test

# .woodpecker/deploy.yml
depends_on:
  - test
steps:
  - name: deploy
    image: alpine
    commands:
      - ./deploy.sh
    when:
      branch: main
```

## Woodpecker vs Alternatives

| Feature | Woodpecker | Drone | GitHub Actions | Jenkins | Gitea Actions |
|---------|-----------|-------|----------------|---------|---------------|
| Open Source | Yes (Apache-2.0) | Yes (mixed) | No | Yes (MIT) | Yes |
| Container-native | Yes | Yes | Yes | Plugin | Yes |
| Self-hosted | Yes | Yes | Enterprise | Yes | Yes (with Gitea) |
| Config | YAML | YAML | YAML | Groovy | YAML (GH compat) |
| Complexity | Low | Low | Medium | High | Low |
| Resource usage | ~50MB | ~50MB | N/A | ~1GB+ | Part of Gitea |
| Community | Growing | Declining | Large | Very large | Growing |

## FAQ

**Q: What's the relationship between Woodpecker and Drone?**
A: Woodpecker is a community fork of Drone CI, created after Drone moved in a more commercial direction. Woodpecker stays 100% open source and community-governed, and continues to add new features (multi-pipeline, Cron, UI improvements).

**Q: Does it work well with Gitea?**
A: It's a great fit. Woodpecker + Gitea is the most popular self-hosted Git + CI/CD combo — simple to configure, low resource consumption, and a perfect self-hosted alternative to GitHub + Actions.

**Q: Does it support Kubernetes executors?**
A: Yes. In addition to the Docker agent, Woodpecker offers a Kubernetes backend that runs pipeline steps as K8s Pods.

## Sources & Credits

- GitHub: [woodpecker-ci/woodpecker](https://github.com/woodpecker-ci/woodpecker) — 6.8K+ ⭐ | Apache-2.0
- Website: [woodpecker-ci.org](https://woodpecker-ci.org)

---
Source: https://tokrepo.com/en/workflows/woodpecker-ci-simple-yet-powerful-ci-cd-engine-a22e63ee
Author: Script Depot