Woodpecker CI et Forgejo : pipeline CI/CD sur VPS

Les offres CI cloud facturent à la minute de build et imposent des files d'attente partagées dont le temps d'attente augmente avec le volume. Dès que les dépôts grossissent ou que les tests se multiplient, la facture dépasse rapidement le coût d'un VPS dédié. Héberger Forgejo et Woodpecker CI sur le même serveur supprime cette latence réseau : le runner lit le code en local, sans transit par une infrastructure tierce. Vous gardez aussi la maîtrise du cycle de mise à jour — aucun changement de tarification ou de règles de rétention de logs ne s'applique sans votre accord. Pour les équipes soumises à des contraintes réglementaires ou de confidentialité, c'est un avantage décisif : les secrets d'intégration (clés SSH de déploiement, tokens d'accès registre) ne franchissent jamais le périmètre de votre réseau. Enfin, la licence Apache 2.0 garantit que le code source reste auditable et que le projet ne peut basculer derrière une offre commerciale exclusive.

Woodpecker CI s'installe sur le même VPS que Forgejo ou sur un serveur dédié. Pour les deux services combinés, prévoyez 1 Go de RAM minimum et 2 Go pour un usage confortable avec plusieurs dépôts actifs en parallèle. Côté logiciel : Docker Engine 24 ou supérieur, Docker Compose v2 (la commande docker compose, pas docker-compose), un sous-domaine dédié à Woodpecker — par exemple ci.votre-domaine.com — pointant vers l'IP du VPS, le port 443 ouvert pour HTTPS et un accès SSH. Forgejo doit être accessible depuis le conteneur Woodpecker : soit via le réseau Docker interne si les deux services partagent le même hôte, soit via son URL publique HTTPS si Woodpecker est sur un VPS distinct. Woodpecker CI v3 est compatible avec Forgejo v1.20 et supérieur (la version qui a introduit Forgejo Actions) ; les versions antérieures de Forgejo utilisent le endpoint Gitea, qui reste supporté.

Forgejo Actions — disponible depuis Forgejo v1.19 en mode expérimental, stabilisé progressivement — reproduit la syntaxe GitHub Actions : si vos équipes ont déjà des workflows .github/workflows/ en production, la migration est quasi transparente. Forgejo Actions est le choix naturel pour un parc de dépôts qui cohabite avec GitHub ou qui réutilise des actions publiques du marketplace. Woodpecker CI répond à des besoins différents : sa syntaxe YAML est plus directe, moins chargée de concepts hérités de GitHub, et son architecture serveur-agent permet de découpler la forge git du moteur de CI — utile lorsque plusieurs forges (Forgejo, Gitea, GitLab) doivent partager le même parc de runners. Woodpecker est également plus adapté aux scénarios de build multi-architecture, où l'on veut aiguiller explicitement un job vers un agent ARM ou x86. En résumé : choisissez Forgejo Actions si la compatibilité GitHub Actions est prioritaire, et Woodpecker CI si vous préférez une syntaxe épurée, un déploiement découplé, ou un parc de runners hétérogènes.

Un fichier .woodpecker.yaml décrit une suite d'étapes exécutées séquentiellement dans des conteneurs Docker distincts. Chaque étape possède un nom, une image et une liste de commandes. Les étapes peuvent partager le workspace (répertoire cloné) via un volume monté automatiquement par Woodpecker. Pour un projet Node.js, un pipeline de base comprend une étape lint (node:20, npm ci && npm run lint), une étape test (node:20, npm test) et une étape build (node:20, npm run build). Pour un projet Docker, ajoutez une étape qui utilise le plugin officiel woodpeckerci/plugin-docker-buildx pour construire et pousser l'image vers un registre. Le déclenchement conditionnel s'exprime avec le bloc when : when: { branch: main, event: push } limite l'étape de déploiement à la branche principale sur les push directs, en excluant les pull requests.

Woodpecker distingue deux niveaux de secrets : les secrets de dépôt (visibles uniquement dans les pipelines du dépôt concerné) et les secrets globaux (accessibles à tous les dépôts, à créer avec prudence). Un secret est déclaré dans le dashboard — section Secrets du dépôt — puis référencé dans le pipeline avec la syntaxe from_secret. Par exemple, une clé SSH de déploiement nommée deploy_key s'injecte dans une étape via environment: { SSH_KEY: { from_secret: deploy_key } }. Les secrets ne sont jamais transmis aux pull requests externes par défaut, ce qui évite l'exfiltration par un contributeur malveillant. Pour les variables non sensibles qui doivent être partagées entre plusieurs dépôts, utilisez la variable WOODPECKER_ENVIRONMENT au niveau du serveur : les paires CLE=valeur renseignées là sont disponibles dans tous les pipelines sans déclaration dans le YAML.

Woodpecker CI v3 supporte nativement les agents multi-architecture : chaque agent annonce sa plateforme au serveur (linux/amd64, linux/arm64, linux/arm/v7) et le serveur route les jobs vers l'agent dont la plateforme correspond. Pour déclarer un job ARM64, ajoutez platform: linux/arm64 au niveau du pipeline dans .woodpecker.yaml. Si vous disposez d'un VPS ARM (Ampere, Raspberry Pi 4 ou serveur Hetzner ARM) et d'un VPS x86_64, déployez un agent sur chacun avec le même WOODPECKER_AGENT_SECRET et laissez le serveur répartir les builds. Ce mécanisme est utile pour cross-compiler des binaires, tester la compatibilité d'une image Docker sur plusieurs architectures, ou valider un package système. Le plugin woodpeckerci/plugin-docker-buildx s'appuie sur QEMU pour aller plus loin et produire des images multi-arch depuis un seul agent, mais les builds natifs sur l'architecture cible sont toujours plus rapides.

Cinq problèmes reviennent régulièrement lors de l'installation ou de l'utilisation de Woodpecker CI. Premier : l'agent ne se connecte pas au serveur (agent could not auth). Cause la plus fréquente : WOODPECKER_AGENT_SECRET n'est pas identique dans les deux services. Vérifiez les variables avec docker compose exec woodpecker-server env | grep AGENT_SECRET. Deuxième : la connexion OAuth2 échoue avec Error while authenticating against OAuth provider. Cause probable : l'URL de redirection dans l'application OAuth2 Forgejo ne correspond pas exactement à WOODPECKER_HOST. Vérifiez l'absence de barre oblique finale et la cohérence du schéma HTTPS. Troisième : les pipelines restent bloqués en pending. L'agent est peut-être connecté mais son label de plateforme ne correspond à aucun pipeline ; retirez la clause platform si elle n'est pas nécessaire. Quatrième : les secrets ne sont pas injectés dans les étapes. Les secrets ne sont transmis qu'aux pipelines déclenchés sur des branches internes, jamais sur les PR de forks externes par défaut. Vérifiez que l'événement déclencheur est bien push ou tag. Cinquième : après une montée de version v3.18, les logs de builds anciens sont absents. Cette version inclut une migration du stockage des logs ; si la migration est interrompue, relancez le conteneur serveur avec les droits d'écriture sur le volume de données pour qu'elle reprenne.

ServOrbit propose Woodpecker CI dans son marketplace : l'application s'installe sur un VPS Cloud avec Docker préconfiguré et IP fixe, en quelques clics depuis l'espace client. Une fois le VPS provisionné, il suffit de pointer l'URL WOODPECKER_FORGEJO_URL vers votre forge Forgejo existante et de renseigner les clés OAuth2 pour que les pipelines commencent à s'exécuter. Cette intégration est particulièrement utile pour les agences ou les équipes techniques qui souhaitent isoler le moteur CI du serveur de forge : Forgejo sur un VPS, Woodpecker sur un second, les deux communiquant via HTTPS. Les ressources du VPS sont ajustables à tout moment depuis l'espace client — ajout de RAM ou de vCPU sans réinstallation — ce qui permet de dimensionner le parc de runners en fonction de la charge réelle des builds.

Forgejo gère le code, les issues et les revues de PR ; Woodpecker CI orchestre les pipelines de test et de déploiement. Les deux communiquent par OAuth2 et webhooks sur votre propre réseau, sans dépendance à GitHub, GitLab ou à un service d'intégration cloud. Cette stack auto-hébergée répond aux contraintes de souveraineté des agences et des équipes techniques qui ne souhaitent pas voir leur propriété intellectuelle ou leurs secrets d'intégration transiter par des plateformes externes. Avec Woodpecker CI v3 et Forgejo v1.20 ou supérieur, vous disposez d'un environnement de développement complet — forge git, CI/CD, registry Docker si nécessaire — entièrement maîtrisé, sur un ou deux VPS, pour un coût mensuel prévisible et sans quota de minutes de build.