Alojar Forgejo en su VPS: guía completa 2025

Forgejo nació en 2022 de un fork de Gitea, motivado por las inquietudes sobre la gobernanza del proyecto. Su desarrollo es enteramente comunitario, bajo licencia MIT, sin dependencia de ninguna empresa comercial. Para los equipos que quieren controlar su código fuente, su pipeline CI/CD y sus artefactos sin pasar por GitHub, GitLab o Bitbucket, Forgejo representa la solución más ligera del mercado. La interfaz resulta familiar para cualquier desarrollador que haya usado GitHub, la migración desde Gitea es transparente y la compatibilidad con las GitHub Actions simplifica la adopción.

Antes de lanzar Forgejo, dimensione su VPS según el tamaño real de su equipo. Para 1 a 5 desarrolladores con algunas decenas de repositorios, 1 vCPU y 1 GB de RAM bastan; Forgejo en reposo consume unos 80 MB. Para 5 a 20 desarrolladores con CI/CD activa, prevea 2 vCPU y 2 GB de RAM. Por encima de 20 desarrolladores o para repositorios de gran tamaño (monorepos, binarios), 4 vCPU y 4 GB de RAM garantizan una experiencia fluida. En cuanto al almacenamiento, cuente el volumen de sus repositorios Git más un 20 % de margen para los artefactos y las copias de seguridad.

En el plano de red, deben abrirse tres puertos en su cortafuegos: el puerto 80 (HTTP, para la validación de Let's Encrypt), el puerto 443 (HTTPS, tráfico web) y el puerto 2222 (SSH Git, para evitar el conflicto con el SSH de administración en el 22). En cuanto al software, necesita Docker Engine ≥ 24, Docker Compose v2 y un nombre de dominio que apunte a su VPS.

La compatibilidad con la sintaxis de GitHub Actions es muy amplia. Cree el archivo .forgejo/workflows/ci.yml en la raíz de su repositorio:

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: |
          npm ci
          npm test

Las etiquetas runs-on corresponden a las etiquetas declaradas al registrar el runner. Puede definir varios runners con etiquetas diferentes (p. ej. arm64, gpu, high-memory) y apuntar al entorno adecuado en cada job. Los artefactos y la caché funcionan con las mismas actions oficiales que en GitHub.

Un Forgejo recién instalado es funcional, pero no está endurecido. Estos son los seis puntos que hay que tratar sin falta antes de abrir la forja a su equipo.

Desactivar el registro público. En *Administración del sitio → Configuración → Usuarios*, desmarque «Permitir el registro de usuarios». En una forja interna, nadie debe poder crear una cuenta sin invitación.

Activar la 2FA para los administradores. Cada cuenta de administrador debe activar la autenticación de doble factor en *Configuración → Seguridad*. Imponga la 2FA al conjunto de los usuarios mediante el parámetro REQUIRE_SIGNIN_VIEW y las políticas de seguridad de la organización.

SSH solo por clave. Desactive la autenticación por contraseña en el /etc/ssh/sshd_config del servidor anfitrión (PasswordAuthentication no). Para el SSH Git (puerto 2222), Forgejo solo acepta las claves públicas registradas en los perfiles de usuario: es su comportamiento por defecto.

Secretos de los webhooks. Al crear cada webhook (hacia su CI externa, Slack, etc.), rellene siempre el campo *Secret*. Forgejo firma la carga útil con HMAC-SHA256; su receptor debe verificar esa firma antes de procesar el evento.

Paquetes privados. Si utiliza el registro de paquetes integrado, configure la visibilidad por defecto en *Privado* en los ajustes de la organización. Los tokens de acceso para publicar deben tener un alcance mínimo (packages:write únicamente, nunca un token de administrador global).

Cortafuegos. Cierre todos los puertos salvo el 80, el 443 y el 2222. El puerto 3000 (Forgejo interno) nunca debe exponerse directamente; solo lo consume el reverse proxy en loopback.

El procedimiento de actualización con Docker es sencillo y solo exige unos segundos de indisponibilidad.

cd /opt/forgejo
# 1. Tirer la nouvelle image
docker compose pull forgejo

# 2. Sauvegarder la base avant toute migration
docker compose exec db pg_dump -U forgejo forgejo > backup-$(date +%Y%m%d).sql

# 3. Redémarrer le service
docker compose up -d forgejo

# 4. Vérifier les migrations de schéma
docker compose logs forgejo | grep -i migrat

Forgejo ejecuta sus migraciones automáticamente al arrancar. Compruebe que la línea Finished successfully aparece en los logs. Si se produce un error de migración, restaure la copia de seguridad SQL y comunique el problema en el tracker de Forgejo. Consulte las notas de versión antes de cada salto de versión mayor — las migraciones entre versiones mayores pueden exigir un paso intermedio.

Conexión SSH rechazada en el puerto 2222. Compruebe primero que Docker publica efectivamente el puerto (docker compose ps → columna Ports). Después, pruebe desde el cliente: ssh -p 2222 [email protected]. Si la respuesta es PTY allocation request failed, la conexión funciona: Forgejo responde Hi <utilisateur>! You've successfully authenticated. Si obtiene Connection refused, el cortafuegos bloquea el puerto: ufw allow 2222/tcp.

Runner mostrado como offline en la interfaz. El runner contacta con Forgejo por HTTPS saliente. Compruebe que el contenedor del runner puede resolver y alcanzar git.mondomaine.com. Un certificado autofirmado exige montar su CA dentro del contenedor. Reinicie el runner después de corregir la conectividad: docker compose restart runner.

Push rechazado por un hook pre-receive. Forgejo puede rechazar un push si hay activo un hook de protección de rama (revisión de código obligatoria, tests de CI obligatorios) o si se supera una regla de tamaño de archivo. El mensaje de error de git contiene el detalle. Para los binarios grandes (> 100 MB), utilice Git LFS: Forgejo admite el protocolo LFS de forma nativa.

Interfaz lenta al cabo de varios meses. Lance el recolector de basura de Git sobre los repositorios activos desde la administración: *Administración → Repositorios → Git Repositories → Run Git GC*. Para automatizarlo, configure la tarea programada en app.ini bajo [cron.run_task].