wiki/Catalogue-Self-Hosted/apps/app-woodpecker-ci.md

---
title: Woodpecker CI
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, development, ci-cd, pipeline, docker]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=Development, https://github.com/woodpecker-ci/woodpecker]
---

# 💻 Woodpecker CI

> **Serveur CI/CD open source léger**, fork communautaire de Drone CI. Orchestration de pipelines par conteneurs Docker, parfait pour l'auto-hébergement des projets Git.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | [woodpecker-ci.org](https://woodpecker-ci.org/) |
| **GitHub** | [woodpecker-ci/woodpecker](https://github.com/woodpecker-ci/woodpecker) |
| **License** | Apache-2.0 |
| **Langage** | Go |
| **Étoiles GitHub** | 7 216 ⭐ |
| **Catégorie** | [[cat-development\|Development]] |
| **Note** | ⚠️ **Fork de Drone CI**, créé en 2022 quand Drone a basculé en licence propriétaire. Woodpecker reste **100% open source** et **community-driven**. |

## 📝 Description

**Woodpecker CI** est un **serveur d'intégration continue / déploiement continu** inspiré de Drone CI. Il exécute vos pipelines de build/test/deploy dans des **conteneurs Docker éphémères**, configurés via un fichier `.woodpecker.yaml` à la racine du repo.

**Origines** :

- **Drone CI** (fondateur : Brad Rydzewski) est devenu **propriétaire en 2022** (entreprise Harness)
- **Woodpecker** est un **fork** créé par la communauté pour conserver un CI/CD **libre et auto-hébergeable**
- Mêmes concepts (`.drone.yml` ↔ `.woodpecker.yml`), **drop-in replacement** possible

**Caractéristiques** :

- **Multi-agents** : distribuer la charge sur plusieurs runners
- **Multi-forges** : [[app-gitea]], [[app-forgejo]], GitLab, GitHub, Bitbucket, Gogs
- **Multi-OS** : agents Linux, Windows, macOS, ARM (Raspberry Pi)
- **Plugins** : un plugin est juste une image Docker, ecosystem infini
- **Secrets** chiffrés au repos
- **UI web** : visualiser les builds, logs en temps réel
- **Cron jobs** : pipelines planifiés
- **Webhooks** : déclenchement sur push, tag, PR, release
- **Prometheus metrics**

**Cas d'usage** :

- Auto-héberger ses pipelines pour des projets GitLab/Forgejo
- CI/CD pour projets open source (gratuit à l'infini)
- Build d'images Docker multi-arch
- Déploiement automatique sur cluster Kubernetes, VPS

**Différence avec GitLab CI / Gitea Actions** : Woodpecker est **léger, dédié CI/CD** (pas une forge complète) et **repose uniquement sur Docker** (pas de runners shell complexes).

## 🚀 Installation

### Via Docker Compose (serveur + agent)

```yaml
# docker-compose.yml
version: '3.8'
services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    container_name: woodpecker-server
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=https://ci.example.com
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=https://gitea.example.com
      - WOODPECKER_GITEA_CLIENT=***      - WOODPECKER_GITEA_SECRET=***      - WOODPECKER_AGENT_SECRET=***      - WOODPECKER_ADMIN=velli
    volumes:
      - woodpecker-data:/var/lib/woodpecker
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.woodpecker.rule=Host(`ci.example.com`)"
      - "traefik.http.routers.woodpecker.entrypoints=websecure"
      - "traefik.http.services.woodpecker.loadbalancer.server.port=8000"
    networks:
      - proxy

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    container_name: woodpecker-agent
    restart: unless-stopped
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=***      - WOODPECKER_MAX_WORKFLOWS=4
    depends_on:
      - woodpecker-server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - proxy

volumes:
  woodpecker-data:

networks:
  proxy:
    external: true
```

### Exemple de pipeline `.woodpecker.yaml`

```yaml
# .woodpecker.yaml
when:
  event: [push, pull_request]

steps:
  build:
    image: node:20
    commands:
      - npm ci
      - npm run build
      - npm test

  docker:
    image: plugins/docker
    settings:
      repo: velli/mon-app
      tags: latest
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
```

## ⚙️ Configuration

1. **OAuth2** avec la forge (Gitea, Forgejo, GitHub, GitLab)
2. **Repos activés** : par repo, autoriser l'accès à Woodpecker
3. **Secrets** : variables chiffrées (par repo ou globales)
4. **Agents** : scaler horizontalement (ajouter des agents)
5. **RBAC** : `admin` (peut tout), `user` (ses repos)
6. **Limites** : `WOODPECKER_MAX_WORKFLOWS=2` par agent (selon vos ressources)

## 🔗 Alternatives

- **[[app-gitlab]]** — Forge complète avec CI intégré (plus lourd)
- **[[app-gitea]] / [[app-forgejo]] + Gitea Actions** — Intégré, plus simple
- **Drone CI** — Fork originel, désormais **propriétaire**
- **Jenkins** — Référence historique, très complexe
- **Gitea/Forgejo Actions** — Suffisant pour beaucoup, natif
- **Argo Workflows** — Pour Kubernetes natif
- **Concourse CI** — Pipelines déclaratifs YAML, mais moins populaire

## 🔒 Sécurité

- **OAuth via la forge** : pas de mot de passe à gérer
- **Secrets chiffrés** au repos (clé AES stockée sur le serveur)
- **Agents isolés** : un build malicieux ne touche que son conteneur
- **Volumes read-only** sur les agents pour limiter les fuites
- **HTTPS obligatoire** (reverse proxy)
- **Log audit** : qui a déclenché quel build, depuis quelle IP

## 📚 Ressources

- [Documentation officielle](https://woodpecker-ci.org/docs/intro)
- [GitHub woodpecker-ci/woodpecker](https://github.com/woodpecker-ci/woodpecker)
- [Migration depuis Drone CI](https://woodpecker-ci.org/docs/migrations)
- [Marketplace de plugins](https://woodpecker-ci.org/plugins)

## 🔗 Pages Liées

- [[cat-development]] — Catégorie Development
- [[app-forgejo]] / [[app-gitea]] — Forges supportées
- [[app-gitlab]] — Concurrent + alternative
- [[app-traefik]] — Reverse proxy
- [[securisation-home-lab]] — Bonnes pratiques
- [[recettes-docker-compose]] — Templates Docker