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 GPLv3+ desde la v9.0 (agosto de 2024; antes 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 es una de las soluciones más ligeras. 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. 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. Si no lo hizo en el asistente, añada FORGEJO__service__DISABLE_REGISTRATION=true a las variables de entorno del contenedor (o DISABLE_REGISTRATION = true en la sección [service] de app.ini): solo un administrador podrá entonces crear cuentas. 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*. Para imponerla, configure GLOBAL_TWO_FACTOR_REQUIREMENT en la sección [security] de app.ini (admin para los administradores, all para todos los usuarios). El parámetro REQUIRE_SIGNIN_VIEW solo obliga a iniciar sesión para consultar la forja.

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, recuerde que un paquete hereda la visibilidad de su propietario: publíquelo bajo una organización o una cuenta privada para reservarlo a sus miembros. Los tokens de acceso para publicar deben tener un alcance mínimo (write:package ú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, por eso el compose lo publica en 127.0.0.1:3000. Un puerto publicado por Docker elude las reglas de ufw: solo esta vinculación a 127.0.0.1 lo mantiene fuera de Internet.

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 los logs no señalan ningún error de migración. Si se produce un error de migración, restaure la copia de seguridad SQL y comunique el problema en el tracker de Forgejo. La etiqueta 17 solo sigue las versiones 17.x: para pasar a la siguiente versión mayor, cambie la etiqueta en el compose tras una copia de seguridad completa, y consulte las notas de versión antes de cada salto de versión mayor. Forgejo se niega a arrancar sobre una base más reciente que él: la vuelta atrás pasa por restaurar la copia de seguridad.

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 del sitio → Panel → Operaciones de mantenimiento*, tarea de recolección de basura de los repositorios. Para automatizarlo, active la tarea programada [cron.git_gc_repos] en app.ini (ENABLED = true; se ejecuta cada 72 h por defecto).