--- title: "Cómo instalar Woodpecker CI con Gitea en Ubuntu 24.04" description: "Instala Woodpecker CI con Docker Compose en Ubuntu 24.04, conéctalo a Gitea o Forgejo por OAuth, publícalo con Nginx y HTTPS y ejecuta tu primer pipeline." category: "Herramientas de Desarrollo" language: es source: https://cubepath.com/es/docs/herramientas-de-desarrollo/instalacion-y-configuracion-de-woodpecker-ci updated: 2026-09-25 --- # Cómo instalar Woodpecker CI con Gitea en Ubuntu 24.04 Woodpecker CI es un sistema de integración continua autoalojado en el que cada paso de un pipeline se ejecuta dentro de un contenedor. Se compone de un servidor (interfaz web, API y cola de trabajos) y de uno o varios agentes que ejecutan los pipelines. En este tutorial instalarás el servidor y un agente con Docker Compose en Ubuntu 24.04, los conectarás a una instancia de Gitea o Forgejo mediante OAuth2, publicarás la interfaz detrás de Nginx con HTTPS y ejecutarás un pipeline de prueba. ## Requisitos previos Para seguir esta guía necesitas: - Un servidor con Ubuntu 24.04 LTS y al menos 2 GB de RAM, por ejemplo un VPS de CubePath. - Un usuario no root con privilegios `sudo`. - Docker Engine y el plugin de Docker Compose instalados desde el repositorio oficial de Docker. - Nginx y Certbot instalados (`sudo apt install nginx certbot python3-certbot-nginx`). - Una instancia de Gitea o Forgejo accesible por HTTPS en la que tengas una cuenta, por ejemplo `https://git.your_domain`. - Un subdominio para Woodpecker, como `ci.your_domain`, con un registro DNS A apuntando a la IP del servidor. - Los puertos 80 y 443 abiertos en el cortafuegos. A lo largo de la guía, sustituye `ci.your_domain` y `git.your_domain` por tus dominios reales y `your_gitea_user` por tu nombre de usuario en Gitea o Forgejo. ## Paso 1: Crear la aplicación OAuth2 en Gitea o Forgejo Woodpecker no tiene usuarios propios: los usuarios inician sesión con su cuenta de Gitea o Forgejo y Woodpecker usa ese acceso para leer repositorios y registrar webhooks. Para ello necesitas una aplicación OAuth2. En la interfaz web de Gitea o Forgejo: 1. Abre tu avatar y ve a **Configuración** > **Aplicaciones**. 2. En la sección **Administrar aplicaciones OAuth2**, escribe `Woodpecker CI` como nombre de la aplicación. 3. En **URI de redirección**, introduce `https://ci.your_domain/authorize`. 4. Pulsa **Crear aplicación**. Gitea mostrará un **ID de cliente** y un **Secreto de cliente**. Cópialos ahora, porque el secreto no se vuelve a mostrar. > Nota: Forgejo es un fork de Gitea y expone la misma API OAuth2, así que la configuración de Woodpecker para Gitea que usarás en el siguiente paso funciona igual con Forgejo. ## Paso 2: Preparar el directorio y los secretos Crea un directorio para la instalación y entra en él: ```bash sudo mkdir -p /opt/woodpecker cd /opt/woodpecker ``` El servidor y los agentes se autentican entre sí con un secreto compartido. Genera uno aleatorio: ```bash openssl rand -hex 32 ``` ```output 3f9c1b0d6e2a4c7f8b5e9d1a2c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d ``` Guarda los valores sensibles en un fichero `.env`, que Docker Compose lee automáticamente. Así no quedan escritos en el `docker-compose.yml`: ```bash sudo nano /opt/woodpecker/.env ``` ```ini WOODPECKER_HOST=https://ci.your_domain WOODPECKER_ADMIN=your_gitea_user WOODPECKER_AGENT_SECRET=your_agent_secret WOODPECKER_GITEA_URL=https://git.your_domain WOODPECKER_GITEA_CLIENT=your_oauth_client_id WOODPECKER_GITEA_SECRET=your_oauth_client_secret ``` Sustituye `your_agent_secret` por el valor generado con `openssl` y los dos últimos por el ID y el secreto de cliente del paso 1. Restringe los permisos del fichero: ```bash sudo chmod 600 /opt/woodpecker/.env ``` ## Paso 3: Definir el servidor y el agente con Docker Compose Crea el fichero de Compose: ```bash sudo nano /opt/woodpecker/docker-compose.yml ``` ```yaml services: woodpecker-server: image: woodpeckerci/woodpecker-server:v3 restart: unless-stopped ports: - "127.0.0.1:8000:8000" volumes: - woodpecker-server-data:/var/lib/woodpecker/ environment: - WOODPECKER_HOST=${WOODPECKER_HOST} - WOODPECKER_OPEN=false - WOODPECKER_ADMIN=${WOODPECKER_ADMIN} - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - WOODPECKER_GITEA=true - WOODPECKER_GITEA_URL=${WOODPECKER_GITEA_URL} - WOODPECKER_GITEA_CLIENT=${WOODPECKER_GITEA_CLIENT} - WOODPECKER_GITEA_SECRET=${WOODPECKER_GITEA_SECRET} woodpecker-agent: image: woodpeckerci/woodpecker-agent:v3 command: agent restart: unless-stopped 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} - WOODPECKER_MAX_WORKFLOWS=2 volumes: woodpecker-server-data: woodpecker-agent-config: ``` Algunos detalles de esta configuración: - El puerto web `8000` solo escucha en `127.0.0.1`, porque el acceso público pasará por Nginx con HTTPS. - El agente llega al servidor por la red interna de Compose (`woodpecker-server:9000`), así que el puerto gRPC `9000` no se publica. - `WOODPECKER_OPEN=false` impide que cualquier usuario de tu Gitea se registre en Woodpecker. `WOODPECKER_ADMIN` concede permisos de administrador a tu usuario. - El servidor usa SQLite en el volumen `woodpecker-server-data`, suficiente para un equipo pequeño. - `WOODPECKER_MAX_WORKFLOWS` limita cuántos workflows ejecuta el agente en paralelo. Ajústalo a la CPU y RAM del servidor. > Advertencia: el agente monta `/var/run/docker.sock`, lo que equivale a acceso root al host. Ejecuta solo pipelines de repositorios en los que confíes. Arranca los contenedores: ```bash cd /opt/woodpecker sudo docker compose up -d ``` Comprueba que ambos servicios están en marcha: ```bash sudo docker compose ps ``` ```output NAME IMAGE STATUS woodpecker-woodpecker-agent-1 woodpeckerci/woodpecker-agent:v3 Up 10 seconds woodpecker-woodpecker-server-1 woodpeckerci/woodpecker-server:v3 Up 11 seconds ``` Revisa los logs del agente para confirmar que se ha conectado al servidor. No debe haber errores de autenticación repetidos: ```bash sudo docker compose logs woodpecker-agent --tail 20 ``` ## Paso 4: Publicar Woodpecker con Nginx y HTTPS Gitea solo redirigirá a la URL registrada en la aplicación OAuth2, así que Woodpecker debe responder en `https://ci.your_domain`. Crea un bloque de servidor de Nginx: ```bash sudo nano /etc/nginx/sites-available/woodpecker ``` ```nginx server { listen 80; listen [::]:80; server_name ci.your_domain; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_buffering off; proxy_read_timeout 3600s; } } ``` `proxy_buffering off` y el `proxy_read_timeout` largo permiten que los logs de los pipelines se muestren en tiempo real en el navegador. Activa el sitio, valida la sintaxis y recarga Nginx: ```bash sudo ln -s /etc/nginx/sites-available/woodpecker /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx ``` ```output nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful ``` Si usas UFW, permite el tráfico web: ```bash sudo ufw allow 'Nginx Full' ``` Obtén el certificado de Let's Encrypt. Certbot modificará el bloque de servidor para escuchar en el puerto 443 y redirigir HTTP a HTTPS: ```bash sudo certbot --nginx -d ci.your_domain ``` Verifica que Woodpecker responde por HTTPS: ```bash curl -sI https://ci.your_domain | head -n 1 ``` ```output HTTP/2 200 ``` ## Paso 5: Iniciar sesión y activar un repositorio Abre `https://ci.your_domain` en el navegador y pulsa **Login**. Serás redirigido a Gitea, que te pedirá autorizar la aplicación **Woodpecker CI**. Tras aceptar, volverás a Woodpecker con la sesión iniciada. Para que Woodpecker ejecute pipelines de un repositorio: 1. Pulsa **Add repository** (o el botón **+**) en la lista de repositorios. 2. Elige el repositorio y pulsa **Enable**. Woodpecker registrará automáticamente un webhook en Gitea. Puedes comprobarlo en Gitea, en **Configuración** del repositorio > **Webhooks**, donde aparecerá una entrada apuntando a `https://ci.your_domain/api/hook`. ## Paso 6: Crear el primer pipeline Woodpecker busca los pipelines en el fichero `.woodpecker.yaml` de la raíz del repositorio o en ficheros `.yaml` dentro del directorio `.woodpecker/`. Cada fichero del directorio se ejecuta como un workflow independiente. En tu repositorio, crea `.woodpecker/ci.yaml` con este contenido: ```yaml when: - event: [push, pull_request] steps: - name: info image: alpine:3.20 commands: - echo "Repositorio ${CI_REPO}, rama ${CI_COMMIT_BRANCH}" - uname -a - name: test image: node:22-alpine commands: - node --version - echo "console.log('Pipeline OK')" > check.js - node check.js ``` Cada paso se ejecuta en un contenedor nuevo de la imagen indicada, con el código del repositorio montado como directorio de trabajo, y los pasos se ejecutan en orden. Variables como `CI_REPO` o `CI_COMMIT_BRANCH` las inyecta Woodpecker automáticamente. Haz commit y push del fichero: ```bash git add .woodpecker/ci.yaml git commit -m "Añadir pipeline de Woodpecker" git push ``` En la interfaz de Woodpecker aparecerá un pipeline nuevo. Al abrirlo verás los logs de cada paso y, si todo va bien, los dos pasos en verde, con la salida `Pipeline OK` en el paso `test`. ## Paso 7: Usar secretos en los pipelines Las credenciales (tokens de un registro de contenedores, claves de despliegue) no deben ir en el YAML. Woodpecker las guarda cifradas y las inyecta como variables de entorno. Para crear un secreto, abre el repositorio en Woodpecker, ve a **Settings** > **Secrets** y pulsa **Add secret**. Por ejemplo, crea uno llamado `deploy_token` con el valor del token. Referéncialo en un paso con `from_secret`: ```yaml steps: - name: deploy image: alpine:3.20 environment: DEPLOY_TOKEN: from_secret: deploy_token commands: - test -n "$DEPLOY_TOKEN" && echo "Token disponible" when: - event: push branch: main ``` Woodpecker oculta el valor de los secretos en los logs. La condición `when` hace que este paso solo se ejecute en los push a `main`, no en las pull requests, que es donde conviene limitar el acceso a credenciales de despliegue. ## Paso 8: Añadir agentes en otros servidores (opcional) Si necesitas más capacidad de ejecución, puedes instalar agentes en otros servidores con Docker. En ese caso el agente se conecta al servidor por el puerto gRPC `9000`, así que debes publicarlo en el `docker-compose.yml` del servidor añadiendo `- "9000:9000"` a la lista `ports` de `woodpecker-server` y reiniciando con `sudo docker compose up -d`. Limita el acceso a ese puerto a la IP del agente, porque la conexión gRPC no va cifrada con esta configuración: ```bash sudo ufw allow from agent_server_ip to any port 9000 proto tcp ``` > Importante: Docker publica puertos insertando reglas propias en iptables, que pueden saltarse las reglas de UFW. Si el servidor tiene IP pública, usa además el cortafuegos de red de tu proveedor para restringir el puerto `9000`, o conecta los servidores por una red privada y publica el puerto solo en la IP privada (`"10.0.0.10:9000:9000"`). En el servidor del agente, crea `/opt/woodpecker-agent/docker-compose.yml`: ```yaml services: woodpecker-agent: image: woodpeckerci/woodpecker-agent:v3 command: agent restart: unless-stopped volumes: - woodpecker-agent-config:/etc/woodpecker - /var/run/docker.sock:/var/run/docker.sock environment: - WOODPECKER_SERVER=woodpecker_server_ip:9000 - WOODPECKER_AGENT_SECRET=your_agent_secret - WOODPECKER_MAX_WORKFLOWS=2 volumes: woodpecker-agent-config: ``` Arráncalo con `sudo docker compose up -d` desde ese directorio. El nuevo agente aparecerá en la interfaz de Woodpecker, en **Settings** > **Agents** del panel de administración. ## Solución de problemas **Gitea muestra un error de URI de redirección no válida.** La URI registrada en la aplicación OAuth2 debe coincidir exactamente con `WOODPECKER_HOST` seguido de `/authorize`, incluido el esquema `https://` y sin barra final en `WOODPECKER_HOST`. Corrige la que no coincida y, si cambias el `.env`, recrea el servidor con `sudo docker compose up -d`. **El pipeline se queda en estado pendiente.** Significa que ningún agente ha tomado el trabajo. Revisa los logs del agente: ```bash sudo docker compose logs woodpecker-agent --tail 50 ``` Los errores de autenticación indican que `WOODPECKER_AGENT_SECRET` no coincide entre servidor y agente. Los errores de conexión en un agente remoto suelen deberse al puerto `9000` cerrado. **Los pushes no lanzan pipelines.** Abre en Gitea el webhook del repositorio y revisa las entregas recientes. Si Gitea no puede alcanzar `https://ci.your_domain/api/hook`, comprueba el DNS y el certificado. Si Gitea tiene activada la lista de hosts permitidos para webhooks (`ALLOWED_HOST_LIST` en la sección `[webhook]` de su `app.ini`), añade el dominio de Woodpecker. ## Conclusión Tienes Woodpecker CI funcionando con Docker Compose, integrado con Gitea o Forgejo mediante OAuth2, publicado con HTTPS y ejecutando pipelines definidos en `.woodpecker/`. Como siguientes pasos, puedes migrar la base de datos de SQLite a PostgreSQL cuando crezca el número de usuarios, construir y publicar imágenes con el plugin `docker-buildx` de Woodpecker, o añadir agentes en otros servidores para repartir la carga.