Migrar su CI/CD a Gitea o Forgejo: fuera de GitHub Actions

Lo que ha cambiado en los precios de GitHub Actions

Por qué migrar su CI/CD a una forja autoalojada

• Costo variable eliminado — el runner se ejecuta en su VPS: cada minuto de CI es un recurso ya pagado, no una línea de facturación adicional.
• Confidencialidad de los pipelines — el código fuente, los secretos de entorno y los artefactos de compilación no salen de su infraestructura.
• Compatibilidad YAML — .gitea/workflows/ci.yml sigue la misma sintaxis que .github/workflows/ci.yml; migrar un pipeline existente casi siempre se reduce a mover un archivo.
• Control total de las imágenes de runner — usted elige las versiones de PHP, Node, Python o Docker sin depender del catálogo de GitHub.
• Forja ligera — Gitea funciona con 200 a 300 MB de RAM para los repositorios y act_runner consume unos 50 MB por job; un VPS con 1 GB de RAM basta para un equipo pequeño.
• Independencia de servicio — sus pipelines siguen ejecutándose sea cual sea la disponibilidad o la política de precios de la plataforma upstream.
• Gestión unificada de los accesos — los permisos, los equipos y los webhooks viven en su instancia, sin delegar el acceso a un tercero.
• Almacenamiento de artefactos bajo su control — los binarios, las imágenes Docker y los informes de cobertura se guardan donde usted decida.

Requisitos previos

Gitea Actions vs Forgejo Actions vs Woodpecker CI

Desplace la tabla

Opción A: Gitea con act_runner

Instalación de Gitea y del runner

1. 01

   Crear el archivo Docker Compose

   Cree un directorio de trabajo y un archivo docker-compose.yml:

   services:
     gitea:
       image: gitea/gitea:latest
       container_name: gitea
       environment:
         - USER_UID=1000
         - USER_GID=1000
         - GITEA__actions__ENABLED=true
       volumes:
         - ./gitea-data:/data
         - /etc/timezone:/etc/timezone:ro
         - /etc/localtime:/etc/localtime:ro
       ports:
         - "3000:3000"
         - "222:22"
       restart: unless-stopped

   Active GITEA__actions__ENABLED=true desde el principio: sin esa variable, la pestaña Actions no aparece en la interfaz.

2. 02

   Iniciar Gitea y completar la instalación inicial

   Inicie el contenedor y abra http://<su-ip>:3000 en un navegador. El asistente de instalación le pide el tipo de base de datos (SQLite basta para una forja pequeña), el nombre del servidor y la URL externa. Introduzca la URL HTTPS que va a configurar (https://git.sudominio.com) — queda escrita en la configuración y sirve de base para las URL de clonado y los webhooks.

   Cree la cuenta de administrador desde ese asistente.

3. 03

   Configurar el reverse proxy y el TLS

   Coloque Gitea detrás de nginx con un certificado Let's Encrypt. Ejemplo de bloque server:

   server {
       listen 443 ssl;
       server_name git.sudominio.com;
       ssl_certificate /etc/letsencrypt/live/git.sudominio.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/git.sudominio.com/privkey.pem;
       location / {
           proxy_pass http://127.0.0.1:3000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

   Obtenga el certificado con certbot certonly --nginx -d git.sudominio.com y recargue nginx.

4. 04

   Crear un token de runner en Gitea

   Inicie sesión en su instancia Gitea como administrador. Vaya a Administración del sitio → Runners → Crear un runner. Copie el token mostrado — se usará en el paso siguiente para registrar act_runner.

5. 05

   Desplegar act_runner

   Añada el servicio act_runner a su docker-compose.yml:

     act_runner:
       image: gitea/act_runner:latest
       container_name: act_runner
       environment:
         - GITEA_INSTANCE_URL=https://git.sudominio.com
         - GITEA_RUNNER_REGISTRATION_TOKEN=<su-token>
         - GITEA_RUNNER_NAME=vps-runner
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
         - ./runner-data:/data
       restart: unless-stopped
       depends_on:
         - gitea

   Vuelva a lanzar con docker compose up -d. El runner aparece en la interfaz de Gitea en Administración del sitio → Runners con el estado Idle.

6. 06

   Enviar un workflow de prueba

   En uno de sus repositorios Gitea, cree el archivo .gitea/workflows/ci.yml:

   name: CI
   on: [push]
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Verificación
           run: echo "Pipeline activo en Gitea Actions"

   Haga push de un commit. El job aparece en la pestaña Actions del repositorio y se ejecuta en su runner VPS.

Opción B: Forgejo con act_runner

Diferencias de instalación respecto a Gitea

1. 07

   Sustituir la imagen Docker

   En su docker-compose.yml, sustituya la imagen de Gitea por la imagen oficial de Forgejo:

   services:
     forgejo:
       image: codeberg.org/forgejo/forgejo:latest
       container_name: forgejo
       environment:
         - USER_UID=1000
         - USER_GID=1000
         - FORGEJO__actions__ENABLED=true
       volumes:
         - ./forgejo-data:/data
       ports:
         - "3000:3000"
         - "222:22"
       restart: unless-stopped

   La variable de entorno pasa de GITEA__ a FORGEJO__ para los parámetros propios de Forgejo.

2. 08

   Usar el runner de Forgejo

   Forgejo mantiene su propia versión de act_runner. Use la imagen publicada en el registro de Codeberg:

     act_runner:
       image: code.forgejo.org/forgejo/runner:latest
       container_name: forgejo_runner
       environment:
         - FORGEJO_INSTANCE_URL=https://git.sudominio.com
         - FORGEJO_RUNNER_REGISTRATION_TOKEN=<su-token>
         - FORGEJO_RUNNER_NAME=vps-runner
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
         - ./runner-data:/data
       restart: unless-stopped

3. 09

   Obtener el token de runner en Forgejo

   El procedimiento es idéntico al de Gitea: Administración del sitio → Runners → Crear un runner. El token es de un solo uso — anótelo antes de cerrar la página.

4. 10

   Colocar sus workflows en `.gitea/workflows/`

   Forgejo lee los archivos de workflow en el mismo directorio que Gitea: .gitea/workflows/. Un workflow escrito para GitHub Actions o Gitea Actions funciona sin modificaciones. La única restricción: la acción actions/checkout@v4 y sus equivalentes se resuelven mediante la caché de acciones de su instancia — la primera ejecución las descarga y las siguientes las reutilizan.

Compatibilidad YAML con GitHub Actions

name: Tests
on:
  push:
    branches: [main, dev]
  pull_request:

jobs:
  phpunit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
      - run: composer install --no-interaction
      - run: vendor/bin/phpunit

Ventajas comparativas de un runner self-hosted

• Costo fijo y previsible — solo paga el VPS, sea cual sea la frecuencia de sus pipelines.
• Confidencialidad — el código fuente, las variables de entorno y los artefactos de compilación no pasan por un servicio de terceros.
• Personalización del runner — instale las dependencias del sistema, las herramientas propias de su stack o las imágenes Docker privadas directamente en el runner.
• Red interna accesible — un job puede alcanzar una base de datos de staging o un registry Docker privado en su red sin exposición pública.
• Despliegues sin tránsito de red — el runner se ejecuta en el mismo centro de datos que su servidor de destino; los artefactos de compilación se copian localmente, sin pasar por los servidores de GitHub.
• Archivado bajo su control — los logs de pipeline y los artefactos se conservan tanto tiempo como usted decida, sin límite impuesto por la plataforma.

Resolución de problemas — errores frecuentes

Recupere el control de su CI/CD