Woodpecker CI: CI/CD Autoalojado y Ligero con Gitea

TL;DR — Resumen Rápido

Instala Woodpecker CI para CI/CD autoalojado y ligero. Configura pipelines, secretos, agentes e integración con Gitea, GitHub y GitLab desde cero.

Woodpecker CI es un sistema CI/CD autoalojado y ligero, derivado de Drone CI, que ejecuta pipelines nativos en contenedores con un consumo mínimo de recursos. Esta guía cubre la instalación completa, integración con Gitea, sintaxis de pipelines, gestión de secretos y un pipeline práctico para desplegar una aplicación Go.

Requisitos Previos

• Servidor Linux con Docker y Docker Compose.
• Al menos 512 MB de RAM para servidor + agente (se recomienda 1 GB).
• Una instancia de Gitea, Forgejo, GitHub o GitLab para OAuth.
• Puertos 8000 (HTTP) y 9000 (comunicación gRPC con agentes) abiertos.

---

Paso 1: Arquitectura de Woodpecker

Woodpecker sigue un modelo servidor + agente:

• Servidor — Gestiona la UI web, API, webhooks y programación de pipelines.
• Agente — Consulta el servidor en busca de trabajo y ejecuta los pasos dentro de contenedores Docker.
• Forge — El proveedor Git (Gitea, GitHub, GitLab) que envía webhooks y autenticación OAuth.
• Pipeline — Definido en .woodpecker.yml en la raíz del repositorio.

Paso 2: Instalar con Docker Compose

Crear la App OAuth en Gitea

En Gitea: Ajustes → Aplicaciones → OAuth2 → Crear aplicación OAuth2

• Nombre: Woodpecker CI
• URL de redirección: http://tu-servidor-woodpecker:8000/authorize

Copia el Client ID y el Client Secret.

Configuración con 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://tu-servidor:8000
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=http://tu-gitea:3000
      - WOODPECKER_GITEA_CLIENT=tu-client-id
      - WOODPECKER_GITEA_SECRET=tu-client-secret
      - WOODPECKER_AGENT_SECRET=secreto-compartido-fuerte

  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=secreto-compartido-fuerte
      - WOODPECKER_MAX_PROCS=2

volumes:
  woodpecker-server-data:

docker compose up -d

---

Paso 3: Sintaxis del Pipeline (.woodpecker.yml)

Pipeline Básico

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

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

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

Ejecución Condicional con when

steps:
  - name: desplegar
    image: alpine
    commands:
      - ./deploy.sh
    when:
      - branch: main
        event: push

Servicios (Base de Datos, 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 ./...

---

Paso 4: Gestión de Secretos

Ámbito	Configurado por	Visible para
Repositorio	Propietario del repo	Solo ese repositorio
Organización	Admin de la org	Todos los repos de la org
Global	Admin del servidor	Todos los repositorios

Referencia un secreto en el pipeline:

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

---

Paso 5: Plugins

Plugin	Imagen	Propósito
Docker	woodpeckerci/plugin-docker-buildx	Construir y publicar imágenes Docker
S3	woodpeckerci/plugin-s3	Subir artefactos a S3
Slack	plugins/slack	Notificaciones de build
Webhook	woodpeckerci/plugin-webhook	POST a URLs arbitrarias

---

Paso 6: Agentes, CLI y Builds Multiplataforma

Etiquetas de Agentes

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

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

Tareas Programadas (Cron)

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

---

Woodpecker vs Alternativas

Característica	Woodpecker	Drone OSS	Gitea Actions	Jenkins	Concourse
Licencia	MIT	Apache 2.0	MIT	MIT	Apache 2.0
RAM (en reposo)	~50 MB	~80 MB	~100 MB	~500 MB	~200 MB
Formato pipeline	YAML	YAML	YAML (GHA)	Groovy/YAML	YAML
Matrix builds	Sí	No (OSS)	Sí	Sí	Sí
Multi-pipeline	Sí	No (OSS)	Sí	Sí	No
Backend Kubernetes	Sí	Sí	No	Sí	No

---

Ejemplo Práctico: Pipeline para Aplicación 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.ejemplo.com/miapp
      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: desplegar
    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.ejemplo.com/miapp:latest && docker restart miapp"
    when:
      - branch: main
        event: push

---

Problemas Comunes

Problema	Solución
Agente no se conecta	Verifica que WOODPECKER_AGENT_SECRET coincida; comprueba que el puerto 9000 esté abierto
Pipeline en estado pendiente	Ningún agente conectado o etiquetas no coinciden; revisa el estado del agente en la UI
Webhook no se dispara	Verifica que Gitea pueda alcanzar el servidor Woodpecker; revisa Ajustes > Hooks del repo
Secretos no inyectados	El nombre del secreto debe coincidir exactamente con el pipeline; revisa el filtro de eventos
Build multiplataforma falla	Verifica que QEMU esté instalado o usa privileged: true

Resumen

• Woodpecker CI es un fork ligero de Drone CI que usa ~50 MB de RAM con arquitectura servidor + agente.
• Se integra con 6 forges (Gitea, Forgejo, GitHub, GitLab, Bitbucket) via OAuth2.
• Los pipelines usan .woodpecker.yml con pasos, servicios, matrix builds y multi-pipeline por rutas.
• Los secretos se gestionan por repositorio, organización o globalmente, con backends externos como Vault.
• El CLI woodpecker-cli permite gestionar pipelines, secretos y tareas cron desde la terminal.

Artículos Relacionados

• Gitea: Servidor Git Autoalojado
• Gitea: Alternativa a GitHub Autoalojada
• CI/CD Pipeline Security Best Practices
• Docker Persistent Volumes Troubleshooting