Woodpecker CI : un pipeline CI/CD léger sans quota de minutes

GitHub Actions gratuit alloue 2000 minutes par mois sur les dépôts privés — largement suffisant pour un petit projet, nettement moins pour une équipe qui build et teste plusieurs fois par heure sur plusieurs branches. Woodpecker CI supprime cette contrainte à la racine : les pipelines tournent sur des runners que vous hébergez, donc il n'y a rien à quotifier.

Woodpecker CI est un moteur d'intégration continue né du fork communautaire de Drone CI, après que ce dernier a restreint sa licence open-source. Chaque pipeline est une suite d'étapes exécutées dans des containers Docker isolés, définie en YAML — build, tests, déploiement — déclenchée par un push, une pull request, ou un tag Git. Il s'intègre nativement avec GitHub, GitLab, Gitea/Forgejo et Bitbucket comme source de dépôts.

Installation avec Docker Compose

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    restart: always
    ports:
      - "8000:8000"
    environment:
      WOODPECKER_OPEN: "false"
      WOODPECKER_HOST: "https://ci.mondomaine.fr"
      WOODPECKER_GITEA: "true"
      WOODPECKER_GITEA_URL: "https://git.mondomaine.fr"
      WOODPECKER_GITEA_CLIENT: "CLIENT_ID_OAUTH"
      WOODPECKER_GITEA_SECRET: "CLIENT_SECRET_OAUTH"
      WOODPECKER_AGENT_SECRET: "un-secret-partagé"
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker
 
  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    restart: always
    depends_on:
      - woodpecker-server
    environment:
      WOODPECKER_SERVER: woodpecker-server:9000
      WOODPECKER_AGENT_SECRET: "un-secret-partagé"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
 
volumes:
  woodpecker-server-data:

Le serveur orchestre les pipelines, l'agent les exécute réellement en montant le socket Docker — architecture qui sépare la coordination de l'exécution, permettant d'ajouter plusieurs agents sur des machines différentes pour paralléliser les builds.

L'exemple ci-dessus s'authentifie contre Gitea via OAuth — créer une application OAuth dans Gitea (Paramètres > Applications) pour obtenir CLIENT_ID/CLIENT_SECRET. La même config fonctionne avec GitHub ou GitLab en changeant les variables WOODPECKER_GITHUB_* ou WOODPECKER_GITLAB_*.

Écrire un pipeline

steps:
  install:
    image: node:20-alpine
    commands:
      - npm ci
 
  test:
    image: node:20-alpine
    commands:
      - npm test
 
  build:
    image: node:20-alpine
    commands:
      - npm run build
    when:
      branch: main
 
  deploy:
    image: alpine
    commands:
      - apk add openssh-client
      - ssh -o StrictHostKeyChecking=no deploy@monserveur "cd /app && git pull && docker compose up -d --build"
    when:
      branch: main
    secrets: [ssh_key]

Chaque étape est un container isolé — image définit l'environnement d'exécution, commands les instructions shell à exécuter dedans. La clause when restreint une étape à certaines branches, exactement comme les conditions if de GitHub Actions.

Secrets

woodpecker-cli secret add \
  --repository monorg/monrepo \
  --name ssh_key \
  --value "$(cat ~/.ssh/deploy_key)"

Les secrets se déclarent par dépôt ou globalement au niveau de l'organisation, jamais en clair dans le fichier YAML versionné — le pipeline y accède uniquement par référence (secrets: [ssh_key]), la valeur réelle restant côté serveur.

Matrices de build

Comme GitHub Actions, Woodpecker supporte les builds matriciels pour tester contre plusieurs versions en parallèle :

matrix:
  NODE_VERSION:
    - 18
    - 20
    - 22
 
steps:
  test:
    image: node:${NODE_VERSION}-alpine
    commands:
      - npm ci
      - npm test

Trois pipelines s'exécutent en parallèle, un par version de Node listée — utile pour garantir la compatibilité d'une librairie publiée sur plusieurs versions runtime supportées.

Woodpecker vs GitHub Actions vs Drone

Le point faible réel de Woodpecker face à GitHub Actions : pas de marketplace d'actions préconstruites à réutiliser en une ligne (uses: actions/checkout@v4). Chaque étape Woodpecker est un container Docker générique — plus universel, mais demande d'écrire soi-même la logique qu'une action GitHub toute faite couvrirait en une ligne.

Migrer depuis GitHub Actions

La conversion d'un pipeline .github/workflows/ci.yml vers .woodpecker/ci.yml suit un principe simple : chaque uses: actions/xxx se remplace par une image Docker équivalente et des commandes shell explicites. Un actions/setup-node devient simplement image: node:20-alpine, la version étant directement dans le nom de l'image plutôt que dans une action séparée.

Woodpecker CI demande de gérer soi-même les runners — pas de "GitHub-hosted runners" gratuits ici, juste vos machines. Mais sur une infrastructure qui héberge déjà Gitea et Docker, brancher un pipeline CI qui ne dépend d'aucun quota externe ferme la boucle : code, revue, tests et déploiement, tout sous votre toit.