# 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 as a script file and run:

## 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 |

## 常见问题

**Q: Woodpecker 和 Drone 有什么关系？**
A: Woodpecker 是 Drone CI 的社区 fork，创建于 Drone 转向更商业化的方向之后。Woodpecker 保持了 100% 开源、社区治理，并持续添加新功能（如多管道、Cron、改进的 UI）。

**Q: 可以和 Gitea 配合使用吗？**
A: 非常适合。Woodpecker + Gitea 是最流行的自托管 Git + CI/CD 组合。配置简单，资源消耗低，是 GitHub + Actions 的完美自托管替代。

**Q: 支持 Kubernetes 执行器吗？**
A: 支持。除了 Docker agent，Woodpecker 还提供 Kubernetes backend，将 pipeline 步骤作为 K8s Pod 运行。

## 来源与致谢

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

---
Source: https://tokrepo.com/en/workflows/a22e63ee-34d0-11f1-9bc6-00163e2b0d79
Author: Script Depot