Woodpecker CI, sans aucun SaaS sur le chemin

Comment installer Woodpecker CI avec Docker Compose

Serveur et agent sur un hôte, reliés à GitHub dans cet exemple. Remplacez le bloc de la forge par les variables Gitea, Forgejo, GitLab ou Bitbucket si votre forge est l'une de celles-là.

1. 1

   Installer Docker et Compose

   sudo apt install docker.io docker-compose-v2
   sudo systemctl enable --now docker

   Les deux conteneurs et chaque étape de pipeline tournent sur ce démon, c'est donc la seule dépendance dont l'hôte a besoin.

2. 2

   Enregistrer une application OAuth sur votre forge

   # GitHub: Settings -> Developer settings -> OAuth Apps -> New OAuth App
   # Homepage URL:     https://ci.example.com
   # Authorization callback: https://ci.example.com/authorize

   Woodpecker authentifie les utilisateurs via la forge et lit les dépôts avec cette autorisation, l'identifiant client et le secret qu'elle rend sont donc ce dont le serveur a besoin. Chaque forge prise en charge possède un formulaire équivalent.

3. 3

   Générer le secret partagé de l'agent

   openssl rand -hex 32

   Le serveur et les agents s'authentifient mutuellement avec cette chaîne, et la documentation Woodpecker nomme exactement cette commande pour la produire. Gardez-la hors du fichier compose - mettez-la dans un fichier .env à côté.

4. 4

   Écrire le fichier compose

   services:
     woodpecker-server:
       image: woodpeckerci/woodpecker-server:v3
       ports:
         - 8000:8000
       volumes:
         - woodpecker-server-data:/var/lib/woodpecker/
       environment:
         - WOODPECKER_OPEN=true
         - WOODPECKER_HOST=${WOODPECKER_HOST}
         - WOODPECKER_GITHUB=true
         - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
         - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
         - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
     woodpecker-agent:
       image: woodpeckerci/woodpecker-agent:v3
       command: agent
       restart: always
       depends_on:
         - woodpecker-server
       volumes:
         - woodpecker-agent-config:/etc/woodpecker
         - /var/run/docker.sock:/var/run/docker.sock
       environment:
         - WOODPECKER_SERVER=woodpecker-server:9000
         - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
   volumes:
     woodpecker-server-data:
     woodpecker-agent-config:

   C'est l'exemple officiel. WOODPECKER_HOST est l'URL publique que joignent utilisateurs et webhooks, le port 8000 est l'interface web et le 9000 le port gRPC sur lequel les agents se connectent. WOODPECKER_OPEN=true laisse entrer quiconque possède un compte sur la forge - désactivez-le une fois votre équipe enregistrée.

5. 5

   Le démarrer

   docker compose up -d
   docker compose logs -f woodpecker-agent

   L'agent se connecte au serveur avec le secret partagé et s'enregistre lui-même au premier contact. S'il boucle sur une erreur d'authentification, les deux secrets ne concordent pas - le plus souvent parce que le fichier .env n'a pas été pris en compte.

6. 6

   Ajouter une pipeline

   when:
     - event: push
   
   steps:
     - name: smoke
       image: alpine:latest
       commands:
         - cat /etc/os-release
         - echo "built on $CI_MACHINE"

   Committez ceci en tant que .woodpecker.yaml, activez le dépôt dans l'interface web pour que le webhook soit créé, et poussez. Chaque étape est un conteneur, et c'est pourquoi l'agent a besoin du socket Docker.

Vérifié sur la documentation officielle le 2026-08-15 — lire la source