Alojar Gitea en su propio VPS en 2026

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.

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.yourdomain.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.

Gitea Actions es el motor CI/CD nativo de Gitea, compatible con la sintaxis de los flujos de trabajo de GitHub Actions. Permite ejecutar pipelines directamente en su infraestructura, sin dependencia de ningún servicio externo.

Para activarlo, añada a su app.ini:

[actions]
ENABLED = true

Registre después 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 un segundo VPS al runner.

Un flujo de trabajo mínimo para un proyecto Node.js va en .gitea/workflows/ci.yml:

on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm test

El runner ejecuta este flujo de trabajo en cada push. Puede combinar múltiples trabajos, usar matrices de versiones y compartir artefactos entre pasos — exactamente como GitHub Actions, pero en su propio servidor.

Una vez Gitea en producción, vuelven regularmente algunas operaciones de mantenimiento.

Gestionar los webhooks. Gitea registra el historial de cada envío en «Configuración del repositorio → Webhooks → Entregas recientes». Un webhook fallido (timeout, error HTTP 5xx) puede reproducirse manualmente desde ese historial. Si sus runners están en la misma red privada que Gitea, añada sus rangos IP a ALLOWED_HOST_LIST en la sección [webhook] de app.ini — de lo contrario las llamadas hacia localhost se bloquean por defecto desde Gitea 1.20.

Purgar los repositorios huérfanos. Un repositorio eliminado mediante la interfaz deja sus datos Git (objects/) en disco hasta la próxima ejecución de las tareas en segundo plano. Fuerce un paso inmediato desde el admin: «Administración del sitio → Tareas en segundo plano → Ejecutar: Purgar repos eliminados». El espacio liberado solo es visible tras docker exec -u git gitea gitea admin storage --remove-unlisted.

Cuota de almacenamiento por organización. Para instancias multi-inquilino, fije una cuota de repositorios por organización en app.ini bajo [repository]: MAX_CREATION_LIMIT = 50. Esto impide que una cuenta cree cientos de repositorios sin supervisión y llene el volumen de datos.

Permission denied (publickey) tras una actualización. La ruta del binario referenciado en authorized_keys ha cambiado (comprobado en 1.27). El servicio Gitea responde con normalidad por HTTPS, lo que enmascara el problema. Corrija con: docker exec -u git gitea gitea admin regenerate keys. Compruebe que un git clone por SSH funciona antes de dar por terminada la actualización.

Timeout o error SSL al clonar por HTTPS. Tres causas comunes: el ROOT_URL en app.ini no coincide con el dominio HTTPS real (enlaces rotos + posible bucle de redirección), el reverse proxy no reenvía la cabecera X-Forwarded-Proto: https (Gitea genera entonces URLs en HTTP), o el certificado Let's Encrypt ha caducado (Caddy y certbot lo renuevan automáticamente, pero solo si el DNS sigue apuntando al VPS). Verifique ROOT_URL primero: es la causa más frecuente tras una migración de dominio.

Clonado SSH lento o que se bloquea. El upload-pack SSH usa el mismo proceso Git que las operaciones web. Si su act_runner está utilizando todos los núcleos de CPU disponibles durante una compilación, las operaciones Git pueden quedar a la espera. Añada cpus: '1.5' al runner en el compose para reservarle núcleos sin privarlo por completo.

Database migration failed: column already exists. La base recibió una migración parcial (parada durante la actualización). Restaure el dump realizado antes de la actualización, parta de un volumen limpio y vuelva a lanzar.

Tras actualizar a Gitea 28.1.0, la vista de comparación de pull requests falla silenciosamente en repositorios grandes (superiores a 1,4 GB) con el error exit 128 "unable to fetch head branch". La causa raíz es un archivo de bloqueo obsoleto (commit-graph.lock) dejado por un git fetch ejecutado sin el indicador --no-write-commit-graph — comportamiento introducido en esta versión (issue upstream #39795, reportada el 15 de octubre de 2026).

Diagnóstico. Compruebe la presencia del archivo de bloqueo en el repositorio afectado:

docker exec -u git gitea find /data/gitea/repositories -name 'commit-graph.lock'

Corrección inmediata. Elimine el archivo de bloqueo obsoleto:

docker exec -u git gitea find /data/gitea/repositories -name 'commit-graph.lock' -delete

La comparación de PR se restaura de inmediato sin necesidad de reiniciar el contenedor.

Recomendación. La corrección definitiva fue integrada en PR #39798 y se incluye en Gitea 28.1.1+. Planifique la actualización a 28.1.1 o superior cuanto antes; las instancias que gestionan repositorios de gran tamaño se ven afectadas sistemáticamente tras un fetch concurrente.

Desde Gitea v28, los escalares de bloque plegado YAML (>) utilizados en campos with: de pasos de flujo de trabajo son malinterpretados en ejecución: los valores multilínea se truncan o concatenan sin saltos de línea, produciendo errores silenciosos difíciles de diagnosticar (issue upstream #39775, reportada el 15 de octubre de 2026).

Síntoma típico. Un parámetro with: definido en varias líneas con >:

- uses: some-action@v1
  with:
    config: >
      línea uno
      línea dos
      línea tres

…es recibido por la acción como línea uno línea dos línea tres (los saltos de línea se pierden), en lugar del valor esperado con separación por líneas.

Soluciones alternativas. Dos enfoques equivalentes:

1. Reemplace > (plegado) por | (literal) — los saltos de línea se conservan tal cual:

  with:
    config: |
      línea uno
      línea dos
      línea tres

2. Utilice una cadena entre comillas con \n explícitos si el valor debe permanecer en una sola línea lógica.

Este comportamiento afecta a todos los flujos de trabajo que usan bloques > dentro de with: desde la migración a v28; los bloques | y los escalares en línea no se ven afectados. Se está evaluando una corrección oficial en el repositorio upstream.

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. 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.

Si desea profundizar en la automatización alrededor de su forja Git, el artículo Alojar Forgejo en su VPS detalla la configuración de una instancia Forgejo con runners Actions dedicados, la configuración del registro OCI integrado y el endurecimiento de la seguridad (fail2ban, restricción de rangos IP). Para equipos que quieran una cadena de despliegue continuo completa, es el complemento natural de esta guía.