Remplacer GitHub Actions par Woodpecker CI sur VPS

Jusqu'en 2025, les dépôts privés bénéficiaient d'un quota mensuel de minutes incluses. Le 16 décembre 2025, GitHub a annoncé une tarification à la minute pour l'utilisation des runners — y compris les runners auto-hébergés sur vos propres machines. La discussion GitHub #182089 (ouverte ce même mois, 72 upvotes) résume l'inquiétude : les équipes auraient payé GitHub pour l'orchestration d'un job tournant sur leur propre infrastructure, à 0,002 $ la minute.

Face à une réaction communautaire massive, GitHub a suspendu cette tarification dans les 48 heures. Au 1er septembre 2026, les runners self-hosted sur dépôts privés restent gratuits — la mesure n'a jamais été appliquée. Mais l'annonce a mis en évidence une dépendance structurelle : GitHub peut modifier ses conditions à tout moment. Migrer la chaîne CI/CD vers une forge auto-hébergée, c'est s'affranchir de cette incertitude. Woodpecker CI est conçu précisément pour cet usage : un moteur de pipeline léger, open source (Apache 2.0), qui s'installe aux côtés de Gitea ou Forgejo et ne connaît pas de compteur de minutes.

Pour déployer Woodpecker CI dans de bonnes conditions, vérifiez les points suivants.

VPS : 1 vCPU et 1 Go de RAM suffisent pour le serveur Woodpecker, un agent et une forge Gitea ou Forgejo légère. Comptez 2 Go si vous lancez plusieurs builds en parallèle ou si vos jobs compilent des images Docker.

Logiciels : Docker et Docker Compose doivent être installés. Si vous partez d'un VPS vierge, le guide Démarrer avec Docker sur VPS couvre cette étape.

Forge git : Woodpecker CI s'appuie sur OAuth2 pour l'authentification. Il vous faut une instance Gitea ou Forgejo déjà en place et accessible via HTTPS (par exemple sur git.votre-domaine.com). Les guides Héberger Gitea et Héberger Forgejo détaillent cette installation.

Domaine : prévoyez un sous-domaine dédié à Woodpecker — par exemple ci.votre-domaine.com — pointant vers l'IP de votre VPS, avec le port 443 ouvert. Ce sous-domaine sert de WOODPECKER_HOST et d'URL de redirection OAuth2.

Woodpecker CI a sa propre syntaxe YAML — elle n'est pas compatible GitHub Actions. La bonne nouvelle : elle est plus courte. Voici la migration d'un workflow Node.js classique.

Avant — .github/workflows/ci.yml :

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test

Après — .woodpecker.yml :

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

Les différences clés : Woodpecker utilise directement une image Docker comme environnement d'exécution (pas besoin de setup-node), et chaque étape est déclarée comme un service de conteneur. L'action checkout est implicite — Woodpecker clone automatiquement le dépôt dans le workspace partagé entre les étapes.

L'agent n'apparaît pas dans le dashboard. Vérifiez que WOODPECKER_AGENT_SECRET est identique dans les deux services du docker-compose.yml. Si vous avez modifié le .env après le premier démarrage, relancez avec docker compose down && docker compose up -d.

La connexion OAuth2 échoue. L'URL de redirection enregistrée dans Gitea doit correspondre exactement à https://ci.votre-domaine.com/authorize. Une barre oblique finale, une faute d'orthographe ou un protocole HTTP au lieu de HTTPS suffisent à bloquer le flux OAuth2. Vérifiez également que WOODPECKER_GITEA_URL dans le docker-compose.yml pointe bien vers l'URL publique de votre Gitea — le conteneur Woodpecker doit pouvoir la résoudre depuis l'intérieur du réseau Docker.

Le webhook ne se déclenche pas. Ouvrez le dépôt dans Gitea → Paramètres → Webhooks et vérifiez que le webhook Woodpecker est bien présent et que les livraisons récentes n'ont pas d'erreur 4xx. Si l'URL de webhook pointe sur http:// au lieu de https://, Gitea peut refuser de l'appeler. Reconfigurez WOODPECKER_HOST avec l'URL complète en HTTPS et réactivez le dépôt dans Woodpecker pour forcer la mise à jour du webhook.

Les builds échouent par manque de mémoire. Le serveur et l'agent Woodpecker consomment moins de 50 Mo au repos — mais chaque étape de build lance un conteneur Docker supplémentaire. Sur un VPS à 1 Go, limitez les builds concurrents à 1 ou 2 en ajoutant WOODPECKER_MAX_PROCS=2 dans l'environnement du service woodpecker-agent.

Une fois le pipeline de base fonctionnel, plusieurs optimisations valent le détour.

Multi-runner. Ajoutez un second service woodpecker-agent dans votre docker-compose.yml (même image, même WOODPECKER_AGENT_SECRET) pour paralléliser les builds. Chaque agent est indépendant et peut tourner sur un VPS séparé si votre charge le justifie.

Cache Docker entre builds. Montez un volume Docker dans l'agent et activez le cache des layers Docker pour éviter de retélécharger les images à chaque build. Woodpecker supporte le cache de pipeline natif via le plugin woodpecker-ci/cache — ajoutez-le comme étape dédiée dans votre .woodpecker.yml.

Notifications. Woodpecker peut notifier un canal de messagerie à chaque build. Des plugins communautaires couvrent Matrix, Slack, Telegram et Mattermost — cherchez woodpecker-ci/notify-matrix ou appleboy/drone-telegram dans la documentation officielle.

Pipeline conditionnel. La syntaxe Woodpecker permet de restreindre une étape à une branche ou à un événement précis :

steps:
  - name: deploy
    image: alpine
    when:
      branch: main
      event: push
    commands:
      - ./deploy.sh

Pour approfondir la mise en place des pipelines, le guide Woodpecker CI et Forgejo : pipeline CI/CD sur VPS détaille les étapes avancées, notamment l'intégration Forgejo et les pipelines multi-étapes. Le guide Checklist Docker Compose en production couvre les bonnes pratiques pour sécuriser vos stacks Docker en production.