Woodpecker CI : CI/CD Auto-Hébergé et Léger avec Gitea

TL;DR — Résumé Rapide

Déployez Woodpecker CI pour un CI/CD auto-hébergé et léger. Configurez pipelines, secrets, agents et intégration forge avec Gitea, GitHub et GitLab.

Woodpecker CI est un système CI/CD léger et auto-hébergé, dérivé de Drone CI, qui exécute des pipelines natifs en conteneurs avec une utilisation minimale des ressources. Ce guide couvre l’installation complète, l’intégration avec Gitea, la syntaxe des pipelines, la gestion des secrets et un pipeline pratique pour déployer une application Go.

Prérequis

• Serveur Linux avec Docker et Docker Compose.
• Au moins 512 Mo de RAM pour serveur + agent (1 Go recommandé).
• Une instance Gitea, Forgejo, GitHub ou GitLab pour OAuth.
• Ports 8000 (HTTP) et 9000 (communication gRPC avec agents) ouverts.

---

Étape 1 : Architecture de Woodpecker

Woodpecker suit un modèle serveur + agent :

• Serveur — Gère l’UI web, l’API, les webhooks et la planification des pipelines.
• Agent — Interroge le serveur pour du travail et exécute les étapes dans des conteneurs Docker.
• Forge — Le fournisseur Git (Gitea, GitHub, GitLab) qui envoie les webhooks et l’authentification OAuth.
• Pipeline — Défini dans .woodpecker.yml à la racine du dépôt.

Étape 2 : Installer avec Docker Compose

Créer l’App OAuth dans Gitea

Dans Gitea : Paramètres → Applications → OAuth2 → Créer une application OAuth2

• Nom : Woodpecker CI
• URL de redirection : http://votre-serveur-woodpecker:8000/authorize

Copiez le Client ID et le Client Secret.

Configuration Docker Compose

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    container_name: woodpecker-server
    restart: always
    ports:
      - "8000:8000"
      - "9000:9000"
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_OPEN=false
      - WOODPECKER_HOST=http://votre-serveur:8000
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=http://votre-gitea:3000
      - WOODPECKER_GITEA_CLIENT=votre-client-id
      - WOODPECKER_GITEA_SECRET=votre-client-secret
      - WOODPECKER_AGENT_SECRET=secret-partage-fort

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    container_name: woodpecker-agent
    restart: always
    depends_on:
      - woodpecker-server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=secret-partage-fort
      - WOODPECKER_MAX_PROCS=2

volumes:
  woodpecker-server-data:

docker compose up -d

---

Étape 3 : Syntaxe du Pipeline (.woodpecker.yml)

Pipeline de Base

steps:
  - name: test
    image: golang:1.22
    commands:
      - go test ./...

  - name: build
    image: golang:1.22
    commands:
      - go build -o app .

  - name: notifier
    image: plugins/slack
    settings:
      webhook:
        from_secret: slack_webhook
    when:
      - status: [success, failure]

Services (Base de données, Redis)

services:
  - name: postgres
    image: postgres:16
    environment:
      POSTGRES_DB: testdb
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test

steps:
  - name: test
    image: golang:1.22
    environment:
      DATABASE_URL: "postgres://test:test@postgres/testdb?sslmode=disable"
    commands:
      - go test -tags integration ./...

Matrix Builds

matrix:
  GO_VERSION:
    - "1.21"
    - "1.22"

steps:
  - name: test
    image: "golang:${GO_VERSION}"
    commands:
      - go test ./...

---

Étape 4 : Gestion des Secrets

Portée	Défini par	Visible pour
Dépôt	Propriétaire du repo	Ce dépôt uniquement
Organisation	Admin de l’org	Tous les repos de l’org
Global	Admin du serveur	Tous les dépôts

steps:
  - name: deploy
    image: alpine
    environment:
      DEPLOY_KEY:
        from_secret: deploy_key
    commands:
      - echo "$DEPLOY_KEY" | base64 -d > /tmp/key
      - ./deploy.sh

---

Étape 5 : Plugins

Plugin	Image	Objectif
Docker	woodpeckerci/plugin-docker-buildx	Construire et publier des images Docker
S3	woodpeckerci/plugin-s3	Envoyer des artefacts vers S3
Slack	plugins/slack	Notifications de build
Webhook	woodpeckerci/plugin-webhook	POST vers des URLs arbitraires

---

Étape 6 : Agents, CLI et Builds Multi-Plateforme

Labels d’Agents

WOODPECKER_FILTER_LABELS=platform=linux/arm64,type=build

labels:
  platform: linux/arm64

steps:
  - name: build-arm
    image: golang:1.22
    commands:
      - GOARCH=arm64 go build -o app-arm64 .

woodpecker-cli

export WOODPECKER_SERVER=http://votre-serveur:8000
export WOODPECKER_TOKEN=votre-token-api

woodpecker pipeline ls proprietaire/repo
woodpecker pipeline start proprietaire/repo --branch main
woodpecker secret add --repository proprietaire/repo --name deploy_key --value "$(cat key.pem)"

Tâches Planifiées (Cron)

woodpecker cron add --repository proprietaire/repo --name build-nocturne \
  --expr "0 2 * * *" --branch main

---

Woodpecker vs Alternatives

Fonctionnalité	Woodpecker	Drone OSS	Gitea Actions	Jenkins	Concourse
Licence	MIT	Apache 2.0	MIT	MIT	Apache 2.0
RAM (inactif)	~50 Mo	~80 Mo	~100 Mo	~500 Mo	~200 Mo
Matrix builds	Oui	Non (OSS)	Oui	Oui	Oui
Multi-pipeline	Oui	Non (OSS)	Oui	Oui	Non
Backend Kubernetes	Oui	Oui	Non	Oui	Non

---

Exemple Pratique : Pipeline pour Application Go

steps:
  - name: test
    image: golang:1.22
    commands:
      - go vet ./...
      - go test -race ./...

  - name: build-docker
    image: woodpeckerci/plugin-docker-buildx
    settings:
      repo: registry.exemple.com/monapp
      tags: ["latest", "${CI_COMMIT_SHA:0:8}"]
      platforms: "linux/amd64,linux/arm64"
      username:
        from_secret: registry_user
      password:
        from_secret: registry_password
    when:
      - branch: main
        event: push

  - name: deployer
    image: alpine
    environment:
      DEPLOY_KEY:
        from_secret: deploy_ssh_key
      DEPLOY_HOST:
        from_secret: deploy_host
    commands:
      - apk add --no-cache openssh-client
      - echo "$DEPLOY_KEY" | base64 -d > /tmp/key && chmod 600 /tmp/key
      - ssh -i /tmp/key -o StrictHostKeyChecking=no deploy@$DEPLOY_HOST
          "docker pull registry.exemple.com/monapp:latest && docker restart monapp"
    when:
      - branch: main
        event: push

---

Problèmes Courants

Problème	Solution
Agent ne se connecte pas	Vérifiez que WOODPECKER_AGENT_SECRET correspond ; confirmez que le port 9000 est ouvert
Pipeline bloqué en attente	Aucun agent connecté ou labels ne correspondent ; vérifiez le statut agent dans l’UI
Webhook ne se déclenche pas	Vérifiez que Gitea peut atteindre le serveur Woodpecker ; vérifiez Paramètres > Hooks
Secrets non injectés	Le nom du secret doit correspondre exactement ; vérifiez le filtre d’événements
Build multi-plateforme échoue	Vérifiez que QEMU est installé ou utilisez privileged: true

Résumé

• Woodpecker CI est un fork léger de Drone CI utilisant ~50 Mo de RAM avec architecture serveur + agent.
• S’intègre avec 6 forges (Gitea, Forgejo, GitHub, GitLab, Bitbucket) via OAuth2.
• Les pipelines utilisent .woodpecker.yml avec étapes, services, matrix builds et multi-pipeline par chemins.
• Les secrets sont scopés par dépôt, organisation ou globalement, avec backends externes comme Vault.
• woodpecker-cli permet de gérer pipelines, secrets et tâches cron depuis le terminal.

Articles Connexes

• Gitea : Serveur Git Auto-Hébergé
• Gitea : Alternative Auto-Hébergée à GitHub
• CI/CD Pipeline Security Best Practices
• Docker Persistent Volumes Troubleshooting