Cómo instalar Gitea o Forgejo en un VPS

Diferencias clave

Forgejo es un fork de Gitea con énfasis en gobernanza comunitaria. Ambos comparten la API, los clientes y el formato de configuración. Para nuevas instalaciones, cualquiera de los dos funciona; este artículo usa Forgejo porque mantiene compatibilidad total con Gitea.

Requisitos

Ubuntu 22.04, Docker instalado, dominio o subdominio apuntando al VPS, y el puerto 22 disponible para SSH de Git (o mapear Gitea a otro puerto).

Instalación con Docker Compose

Crea el directorio:

mkdir -p ~/forgejo && cd ~/forgejo

Crea docker-compose.yml:

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

Iniciamos con el puerto SSH mapeado al 222 del host para no interferir con el SSH del sistema operativo.

docker compose up -d

Configurar Nginx con SSL

sudo apt install -y nginx certbot python3-certbot-nginx

Crea /etc/nginx/sites-available/forgejo:

server {
    listen 80;
    server_name git.tudominio.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 100M;
    }
}

sudo ln -s /etc/nginx/sites-available/forgejo /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d git.tudominio.com

Asistente de instalación

Abre https://git.tudominio.com en el navegador. Aparece el asistente de configuración inicial:

• Base de datos: SQLite para equipos pequeños; PostgreSQL para carga mayor.
• URL base: https://git.tudominio.com
• Puerto SSH del servidor: 222 (el que mapeamos en Docker)
• Dominio SSH: git.tudominio.com
• Crear cuenta de administrador en la parte inferior del formulario.

Guarda la configuración. Forgejo reinicia y queda listo.

Configurar SSH para clonar repositorios

Agrega tu clave pública en Perfil → Ajustes → Claves SSH. Para clonar usando el puerto 222, configura ~/.ssh/config en tu máquina local:

Host git.tudominio.com
    HostName git.tudominio.com
    User git
    Port 222
    IdentityFile ~/.ssh/id_ed25519

Ahora puedes clonar directamente:

git clone [email protected]:usuario/repositorio.git

Migrar repositorios desde GitHub

Desde la interfaz web, haz clic en + → Migrar repositorio → selecciona GitHub. Ingresa tu token de acceso personal de GitHub y el nombre del repositorio. Forgejo importa el código, las ramas, los issues y los pull requests.

Para migración masiva por línea de comandos:

# Ejemplo con la API de Forgejo
curl -X POST https://git.tudominio.com/api/v1/repos/migrate \
  -H "Authorization: token TU_TOKEN_FORGEJO" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_addr": "https://github.com/usuario/repo",
    "auth_token": "TU_TOKEN_GITHUB",
    "uid": 1,
    "repo_name": "repo"
  }'

Configurar Forgejo Actions (CI/CD)

Descarga el runner en el servidor:

# Verifica la última versión en el repositorio oficial de Forgejo
wget https://code.forgejo.org/forgejo/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64
chmod +x act_runner-0.2.11-linux-amd64
sudo mv act_runner-0.2.11-linux-amd64 /usr/local/bin/act_runner

Registra el runner en tu instancia:

act_runner register \
  --instance https://git.tudominio.com \
  --token TOKEN_DEL_RUNNER \
  --name "mi-runner" \
  --labels ubuntu-latest:docker://node:20

Obtén el token en Administración del sitio → Runners. Crea el servicio systemd para que el runner arranque automáticamente.

Ejemplo de workflow en .forgejo/workflows/ci.yml:

on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

Backup

docker exec forgejo forgejo dump -c /data/gitea/conf/app.ini

Esto genera un ZIP con la base de datos, repositorios, adjuntos y configuración. Copia el archivo fuera del VPS.