Por qué autoalojar Gitea en un VPS
Gitea consume apenas 200 a 300 MB de RAM en reposo, lo que la convierte en una de las forjas Git más eficientes para autoalojar. En un VPS, usted conserva el control total de su código fuente: ningún dato es analizado por un tercero, ninguna limitación arbitraria sobre el número de repositorios privados o de colaboradores, y ningún coste que crezca con su equipo. Para una agencia o un desarrollador independiente, un único VPS puede alojar el conjunto de los proyectos de clientes con permisos aislados por organización. Gitea integra de forma nativa un CI/CD compatible con los flujos de trabajo de GitHub Actions (Gitea Actions), un registro de paquetes y un editor web, lo que cubre la casi totalidad de un ciclo de desarrollo sin dependencia externa.
Beneficios concretos de un Gitea autoalojado
- Huella de memoria mínima: funciona con holgura en un VPS de 2 GB de RAM incluso con varias decenas de usuarios.
- Repositorios privados sin facturación por puesto ni límite impuesto, a diferencia de los planes SaaS.
- Gitea Actions integrado para ejecutar sus pipelines CI/CD sin servicio externo.
- Registro de paquetes (Docker, npm, Composer, Maven) alojado en la misma instancia.
- Autenticación granular: LDAP, OAuth2, tokens de acceso personales y claves SSH por usuario.
- Copia de seguridad trivial: todo cabe en un volumen de datos y una base de datos.
Requisitos de hardware y software
Gitea es muy frugal. Para un equipo pequeño (hasta 20 usuarios), un VPS con 2 vCPU y 2 GB de RAM basta de sobra; prevea 4 GB si activa Gitea Actions con runners locales que compilan código. Reserve al menos 20 a 40 GB de almacenamiento SSD según el tamaño de sus repositorios. En cuanto al software: Docker Engine y el plugin Docker Compose instalados, un nombre de dominio (o subdominio del tipo git.votredomaine.com) que apunte a la IP del VPS mediante un registro A, y el puerto 22 reservado al SSH del servidor — Gitea expondrá su propio SSH en otro puerto para evitar el conflicto.
Desplegar Gitea con Docker y SSL
Preparar el VPS y Docker
Conéctese por SSH, actualice el sistema y luego instale Docker y el plugin Compose. Cree un directorio dedicado:
mkdir -p /opt/gitea && cd /opt/gitea. Cree también un volumen de datos que sobreviva a las actualizaciones del contenedor.Redactar el docker-compose.yml
Defina dos servicios:
gitea(imagengitea/gitea:latest) y una basepostgres:16. Monte./gitea:/datapara la persistencia, fijeUSER_UID/USER_GIDen 1000, y mapee el SSH de Gitea al puerto 2222 del host:"2222:22". Deje el puerto HTTP 3000 interno, será servido por el reverse proxy.Lanzar los contenedores
Ejecute
docker compose up -dy luegodocker compose logs -f giteapara seguir la inicialización. Compruebe que la conexión a PostgreSQL funciona antes de continuar.Configurar el reverse proxy
Con Caddy, basta una sola línea:
git.votredomaine.com { reverse_proxy localhost:3000 }. Caddy obtiene y renueva automáticamente el certificado Let's Encrypt. Con Nginx, cree un bloqueserverque haga de proxy haciahttp://127.0.0.1:3000y utilicecertbot --nginxpara el SSL.Finalizar la instalación web
Abra
https://git.votredomaine.com, complete el asistente indicando la URL base HTTPS y el host de la base de datos (db:5432). Defina correctamente elROOT_URL, de lo contrario los enlaces de clonado serán erróneos.Asegurar el SSH de los repositorios
Configure sus clientes para clonar mediante
ssh://[email protected]:2222/..., o añada un bloqueHosten~/.ssh/configpara ocultar el puerto. Desactive el registro público en la administración si la instancia es privada.Conectarse por primera vez
Abra la URL: Gitea muestra su página de instalación, con la base de datos ya rellenada previamente — no la toque. Despliegue «Ajustes opcionales > Ajustes de la cuenta de administrador», cree allí su cuenta de administrador y valide.
Active Gitea Actions desde la instalación añadiendo [actions] ENABLED = true en app.ini, y luego registre un runner act_runner en un contenedor separado en el mismo VPS. Limite su RAM mediante mem_limit para que una compilación exigente no ahogue a Gitea. Para pipelines pesados (compilación, pruebas de integración), dedique más bien un segundo VPS al runner y conéctelo al token de registro — así mantiene la forja reactiva incluso durante las compilaciones.
Gitea o Forgejo en 2026: ¿cuál elegir?
Desplace la tabla
| Criterio | Gitea | Forgejo v16 |
|---|---|---|
| Gobernanza | Sociedad comercial (Gitea Ltd) | Asociación sin ánimo de lucro (Codeberg e.V.) |
| Licencia | MIT | MIT — 100 % software libre, sin edición empresarial |
| Recomendado por Awesome-Selfhosted | No (retirado en 2022) | Sí — recomendación por defecto desde 2024 |
| Federación ActivityPub | No prevista | En despliegue progresivo desde Forgejo v7 |
| Compatibilidad con la API de Gitea | Referencia | Compatible: misma API, mismos webhooks, mismo formato de datos |
| Seguridad — auditorías públicas | Escasas | Auditorías de código publicadas por la comunidad Codeberg |
| Hoja de ruta comunitaria | Dirigida por Gitea Ltd | Gobernanza abierta, RFC públicas, voto de los contribuidores |
| Migración desde Gitea | N/A | Sin pérdida de datos: mismo esquema de base y mismo formato de volumen |
Migrar de Gitea a Forgejo
Hacer una copia de seguridad de la instancia Gitea
Antes de cualquier operación, haga un dump completo:
docker exec -u git gitea gitea admin dump -c /data/gitea/conf/app.ini. Recupere el archivo generado fuera del contenedor y compruebe que el volumen./giteaestá incluido en su snapshot del VPS.Comprobar la compatibilidad de versión
Forgejo v16 admite la migración desde Gitea 1.20 y posteriores. Si su instancia funciona con una versión anterior, suba primero a Gitea 1.21 o 1.22 mediante
docker compose pull && docker compose up -d, y luego compruebe la ausencia de errores en los logs antes de continuar.Sustituir la imagen Docker
En su
docker-compose.yml, sustituyaimage: gitea/gitea:latestporimage: codeberg.org/forgejo/forgejo:latest. El volumen de datos (./gitea:/data) y la base PostgreSQL permanecen sin cambios — Forgejo lee el mismo esquema y el mismoapp.ini.Reiniciar y dejar que migre
Ejecute
docker compose pull && docker compose up -d. Forgejo aplica automáticamente las migraciones de esquema necesarias al arrancar. Sigadocker compose logs -f forgejohasta el mensaje que indica que el servidor HTTP escucha en el puerto 3000.Regenerar las claves SSH
Como en toda actualización que cambia el binario referenciado en
authorized_keys, regenere las entradas:docker exec -u git forgejo forgejo admin regenerate keys. Compruebe después que ungit clonepor SSH funciona desde un puesto cliente.Probar y validar
Abra la interfaz web, compruebe los repositorios, los webhooks y los runners de Forgejo Actions. Los runners
act_runnerregistrados con Gitea son compatibles — vuelva a conectarlos al nuevo token de registro si la clave ha cambiado.
Forgejo v16: las novedades clave (julio de 2026)
Forgejo v16.0.0 introduce la federación ActivityPub en disponibilidad general para las issues y las pull requests: una issue abierta en una instancia Forgejo puede recibir comentarios de usuarios de otra instancia, sin cuenta compartida. La versión integra también un gestor de secretos de instancia (cifrado AES-256 en reposo), un nuevo motor de búsqueda de código basado en el índice Bleve v2 con soporte de expresiones regulares, y mejoras significativas del planificador de tareas en segundo plano. En el plano de la seguridad, los tokens de API se almacenan ahora hasheados en base de datos (bcrypt) y no en texto plano — una migración automática al arrancar convierte los tokens existentes.
Pasar a Gitea 1.27 sin perder los accesos SSH
La versión 1.27 modifica la ruta interna del binario gitea referenciado en authorized_keys. Durante la actualización, las entradas existentes apuntan a la ruta antigua: cualquier intento de clonado o de push por SSH falla en silencio con Permission denied (publickey), sin mensaje de error del lado del servidor que apunte a la actualización. El servicio Gitea responde con normalidad por HTTPS, lo que enmascara el problema. La causa no es la clave del usuario sino el wrapper de comando que Gitea inyecta en authorized_keys. Después de cada actualización a la 1.27 (o a cualquier versión que cambie esa ruta), ejecute dentro del contenedor: docker exec -u git gitea gitea admin regenerate keys. El comando reescribe todas las entradas authorized_keys con la ruta correcta del binario. Compruebe después que un git clone por SSH funciona antes de dar por terminada la actualización.
Solución de problemas: errores frecuentes durante la migración
Permission denied (publickey) tras la migración a Forgejo. El binario referenciado en authorized_keys ha cambiado. Regenere las entradas con docker exec -u git forgejo forgejo admin regenerate keys.
Database migration failed: column already exists. La base ya ha recibido una migración parcial (parada durante la actualización). Restaure el dump completo realizado en el paso 1, parta de un volumen limpio y vuelva a lanzar.
Los webhooks ya no se disparan tras la migración. Forgejo v16 refuerza la validación de las URL de webhook: las URL que apuntan a localhost o a rangos RFC-1918 están bloqueadas por defecto. Active la opción ALLOWED_HOST_LIST en la sección [webhook] de app.ini si sus runners están en la misma red privada.
Los runners act_runner informan de token invalid. Forgejo v16 hashea los tokens de runner en base de datos. Elimine el runner antiguo en la interfaz de administración, vuelva a registrarlo con act_runner register y el nuevo token generado.
JWT_SECRET_URI y JWT_SECRET no deben coexistir en app.ini. Si ambas claves están presentes, Gitea o Forgejo carga una u otra según el orden de lectura, lo que invalida en silencio todos los tokens OAuth2 y Actions emitidos antes de la actualización. Los usuarios ven errores de autenticación intermitentes, sin ningún mensaje que señale app.ini como causa. Elija un solo mecanismo: JWT_SECRET (valor en texto plano) o JWT_SECRET_URI (ruta hacia un archivo secreto), y elimine el otro. Reinicie el contenedor tras la modificación.
La documentación oficial
Para la configuración avanzada y las opciones propias de la herramienta, consulte la documentación oficial de Gitea o la documentación de Forgejo. Esta guía cubre la puesta en línea en un VPS y la migración; las documentaciones de los editores siguen siendo la referencia para los ajustes finos y los casos de uso específicos.
