Woodpecker CI, ganz ohne SaaS im Weg

Woodpecker CI mit Docker Compose installieren

Server und Agent auf einem Host, in diesem Beispiel mit GitHub verdrahtet. Tauschen Sie den Forge-Block gegen die Variablen für Gitea, Forgejo, GitLab oder Bitbucket, wenn Ihre Forge eine davon ist.

1. 1

   Docker und Compose installieren

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

   Beide Container und jeder Pipeline-Schritt laufen auf diesem Daemon, das ist also die einzige Abhängigkeit, die der Host braucht.

2. 2

   Eine OAuth-Anwendung in Ihrer Forge registrieren

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

   Woodpecker meldet Benutzer über die Forge an und liest mit dieser Berechtigung Repositories, die zurückgegebene Client-ID und das Secret sind also das, was der Server braucht. Jede unterstützte Forge hat ein entsprechendes Formular.

3. 3

   Das gemeinsame Agent-Secret erzeugen

   openssl rand -hex 32

   Server und Agents authentifizieren sich mit dieser Zeichenkette gegeneinander, und die Woodpecker-Dokumentation nennt genau diesen Befehl zu ihrer Erzeugung. Halten Sie sie aus der Compose-Datei heraus - legen Sie sie in eine .env-Datei daneben.

4. 4

   Die Compose-Datei schreiben

   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:

   Das ist das Beispiel von upstream. WOODPECKER_HOST ist die öffentliche URL, die Benutzer und Webhooks erreichen, Port 8000 ist die Weboberfläche und 9000 der gRPC-Port, auf dem sich Agents verbinden. WOODPECKER_OPEN=true lässt jeden mit einem Forge-Konto anmelden - schalten Sie es ab, sobald Ihr Team registriert ist.

5. 5

   Starten

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

   Der Agent verbindet sich mit dem gemeinsamen Secret zum Server und registriert sich beim ersten Kontakt selbst. Läuft er in einer Authentifizierungsschleife, stimmen die beiden Secrets nicht überein - meist, weil die .env-Datei nicht gelesen wurde.

6. 6

   Eine Pipeline hinzufügen

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

   Committen Sie das als .woodpecker.yaml, aktivieren Sie das Repository in der Weboberfläche, damit der Webhook angelegt wird, und pushen Sie. Jeder Schritt ist ein Container - deshalb braucht der Agent den Docker-Socket.

Geprüft anhand der offiziellen Dokumentation am 2026-08-15 — Quelle lesen