TL;DR — Kurzzusammenfassung

Woodpecker CI für leichtes self-hosted CI/CD einrichten. Pipelines, Secrets, Agents und Forge-Integration mit Gitea, GitHub und GitLab konfigurieren.

Woodpecker CI ist ein leichtes, self-hosted CI/CD-System, das aus Drone CI hervorgegangen ist und container-native Pipelines mit minimalem Ressourcenverbrauch ausführt. Diese Anleitung behandelt Installation, Gitea-Integration, Pipeline-Syntax, Secret-Verwaltung und eine praktische Go-Anwendungs-Pipeline.

Voraussetzungen

  • Linux-Server mit Docker und Docker Compose.
  • Mindestens 512 MB RAM für Server + Agent (1 GB empfohlen).
  • Eine laufende Gitea-, Forgejo-, GitHub- oder GitLab-Instanz für OAuth.
  • Ports 8000 (HTTP) und 9000 (gRPC-Agent-Kommunikation) geöffnet.

Schritt 1: Woodpecker-Architektur

Woodpecker folgt einem Server + Agent-Modell:

  • Server — Verwaltet Web-UI, API, Webhooks und Pipeline-Planung.
  • Agent — Fragt den Server nach Arbeit ab und führt Schritte in Docker-Containern aus.
  • Forge — Der Git-Anbieter (Gitea, GitHub, GitLab) für Webhooks und OAuth-Authentifizierung.
  • Pipeline — Definiert in .woodpecker.yml im Repository-Root.

Schritt 2: Installation mit Docker Compose

OAuth-App in Gitea erstellen

In Gitea: Einstellungen → Anwendungen → OAuth2 → OAuth2-Anwendung erstellen

  • Name: Woodpecker CI
  • Redirect-URL: http://dein-woodpecker-server:8000/authorize

Client ID und Client Secret kopieren.

Docker Compose Konfiguration

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://dein-server:8000
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=http://dein-gitea:3000
      - WOODPECKER_GITEA_CLIENT=deine-client-id
      - WOODPECKER_GITEA_SECRET=dein-client-secret
      - WOODPECKER_AGENT_SECRET=starkes-gemeinsames-secret

  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=starkes-gemeinsames-secret
      - WOODPECKER_MAX_PROCS=2

volumes:
  woodpecker-server-data:
docker compose up -d

Schritt 3: Pipeline-Syntax (.woodpecker.yml)

Einfache Pipeline

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

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

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

Services (Datenbank, 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 ./...

Schritt 4: Secret-Verwaltung

BereichGesetzt vonSichtbar für
RepositoryRepo-EigentümerNur dieses Repository
OrganisationOrg-AdminAlle Repos der Org
GlobalServer-AdminAlle Repositories
steps:
  - name: deploy
    image: alpine
    environment:
      DEPLOY_KEY:
        from_secret: deploy_key
    commands:
      - echo "$DEPLOY_KEY" | base64 -d > /tmp/key
      - ./deploy.sh

Schritt 5: Plugins

PluginImageZweck
Dockerwoodpeckerci/plugin-docker-buildxDocker-Images bauen und pushen
S3woodpeckerci/plugin-s3Artefakte zu S3 hochladen
Slackplugins/slackBuild-Benachrichtigungen
Webhookwoodpeckerci/plugin-webhookPOST an beliebige URLs

Schritt 6: Agents, CLI und Multi-Plattform-Builds

Agent-Labels

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://dein-server:8000
export WOODPECKER_TOKEN=dein-api-token

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

Geplante Aufgaben (Cron)

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

Woodpecker vs. Alternativen

FunktionWoodpeckerDrone OSSGitea ActionsJenkinsConcourse
LizenzMITApache 2.0MITMITApache 2.0
RAM (inaktiv)~50 MB~80 MB~100 MB~500 MB~200 MB
Matrix-BuildsJaNein (OSS)JaJaJa
Multi-PipelineJaNein (OSS)JaJaNein
Kubernetes-BackendJaJaNeinJaNein

Praxisbeispiel: Pipeline für Go-Anwendung

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

  - name: build-docker
    image: woodpeckerci/plugin-docker-buildx
    settings:
      repo: registry.beispiel.com/meinapp
      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: deployen
    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.beispiel.com/meinapp:latest && docker restart meinapp"
    when:
      - branch: main
        event: push

Häufige Probleme

ProblemLösung
Agent verbindet sich nichtPrüfen ob WOODPECKER_AGENT_SECRET übereinstimmt; Port 9000 geöffnet?
Pipeline bleibt ausstehendKein Agent verbunden oder Labels stimmen nicht überein; Agent-Status in UI prüfen
Webhook löst nicht ausPrüfen ob Gitea den Woodpecker-Server erreichen kann; Repo-Einstellungen > Hooks prüfen
Secrets nicht injiziertSecret-Name muss exakt übereinstimmen; Event-Filter des Secrets prüfen
Multi-Plattform-Build schlägt fehlQEMU installiert? Oder privileged: true verwenden

Zusammenfassung

  • Woodpecker CI ist ein leichter Drone-CI-Fork mit ~50 MB RAM und Server + Agent-Architektur.
  • Integration mit 6 Forges (Gitea, Forgejo, GitHub, GitLab, Bitbucket) über OAuth2.
  • Pipelines verwenden .woodpecker.yml mit Schritten, Services, Matrix-Builds und pfadbasiertem Multi-Pipeline.
  • Secrets sind nach Repository, Organisation oder global scopiert, mit externen Backends wie Vault.
  • woodpecker-cli ermöglicht Pipeline-, Secret- und Cron-Verwaltung über das Terminal.

Verwandte Artikel