Migrar sus repositorios de GitHub a Gitea en un VPS

Por qué dejar GitHub por una forja self-hosted

Lo que aporta Gitea self-hosted en concreto

• Historial completo preservado: la importación mediante la API de Gitea consume un archivo tar.gz de GitHub — commits, ramas y tags intactos.
• Issues y labels migrados: el endpoint POST /api/v1/repos/migrate transfiere issues, milestones y labels en una sola pasada.
• Runner de CI nativo: gitea-runner (basado en act) entiende la sintaxis de los workflows de GitHub Actions — la mayoría de los pipelines funcionan sin reescritura.
• Coste previsible: un VPS con 1 vCPU y 1 GB de RAM basta para un equipo pequeño; el software es open source, sin licencia ni cuota de minutos.
• Webhooks compatibles: Gitea expone los mismos eventos (push, pull_request, release) que GitHub — las integraciones de terceros (Slack, Woodpecker CI) siguen conectadas sin modificación.
• Token de API local: los accesos se gestionan en su propia interfaz, nunca en la de un tercero.

Requisitos previos

Migración paso a paso

1. 01

   Crear la organización Gitea de destino

   En la interfaz de Gitea, vaya a + → New Organization y elija un nombre idéntico al de su organización GitHub (esto simplificará la actualización de los remotes).

   O mediante la API:

   curl -s -X POST https://git.votre-domaine.com/api/v1/orgs \
     -H "Authorization: token VOTRE_TOKEN_GITEA" \
     -H "Content-Type: application/json" \
     -d '{"username":"mon-org","visibility":"private"}'

2. 02

   Listar y exportar los repositorios de GitHub

   Recupere la lista de sus repositorios (paginada a 100 por página):

   curl -s -H "Authorization: token VOTRE_TOKEN_GITHUB" \
     "https://api.github.com/orgs/MON_ORG/repos?per_page=100&page=1" \
     | jq -r '.[].name' > repos.txt

   El endpoint de GitHub utilizado aquí es GET /repos/{owner}/{repo}/tarball/{ref} para el archivo completo, y GET /orgs/{org}/repos para el inventario. Consulte la documentación oficial en docs.github.com.

3. 03

   Importar cada repositorio mediante la API de Gitea

   El endpoint POST /api/v1/repos/migrate de la API de Gitea v1 acepta una URL de origen GitHub (documentación oficial: gitea.io). Para cada repositorio:

   while IFS= read -r REPO; do
     curl -s -X POST https://git.votre-domaine.com/api/v1/repos/migrate \
       -H "Authorization: token VOTRE_TOKEN_GITEA" \
       -H "Content-Type: application/json" \
       -d "{\n      \\\"clone_addr\\\": \\\"https://github.com/MON_ORG/$REPO\\\",\n      \\\"auth_token\\\": \\\"VOTRE_TOKEN_GITHUB\\\",\n      \\\"uid\\\": 2,\n      \\\"repo_name\\\": \\\"$REPO\\\",\n      \\\"issues\\\": true,\n      \\\"labels\\\": true,\n      \\\"milestones\\\": true,\n      \\\"mirror\\\": false\n    }"
   done < repos.txt

   uid es el identificador numérico de su organización Gitea (visible en la API GET /api/v1/orgs/mon-org). El campo mirror: false indica una importación puntual: póngalo en true si desea una sincronización continua durante la fase de transición.

4. 04

   Redirigir los remotes locales

   Para cada repositorio clonado en su equipo:

   git remote set-url origin https://git.votre-domaine.com/mon-org/mon-repo.git

   O por SSH si ha añadido su clave pública en Gitea (Settings → SSH / GPG Keys):

   git remote set-url origin [email protected]:mon-org/mon-repo.git

   Compruébelo con git remote -v y después pruebe un git fetch para confirmar que el remote responde.

5. 05

   Actualizar los webhooks

   En Gitea, para cada repositorio: Settings → Webhooks → Add Webhook. Pegue la URL de su CI o de su servicio de terceros (Slack, Woodpecker CI, etc.) sustituyendo github.com por git.votre-domaine.com.

   Los eventos disponibles (push, pull_request, issues, release) son idénticos a los de GitHub: los payloads tienen la misma estructura de base para la mayoría de las integraciones.

6. 06

   Migrar el pipeline de CI a gitea-runner

   Instale el runner oficial en su VPS:

   wget -O gitea-runner https://dl.gitea.com/act_runner/latest/act_runner-latest-linux-amd64
   chmod +x gitea-runner
   ./gitea-runner register --no-interactive \
     --instance https://git.votre-domaine.com \
     --token VOTRE_TOKEN_RUNNER \
     --name vps-runner \
     --labels ubuntu-latest:docker://node:20-bullseye
   ./gitea-runner daemon &

   El token del runner se genera en Gitea: Site Administration → Runners → Create new Runner Token.

   Sus archivos .github/workflows/*.yml existentes los entiende gitea-runner sin modificación para las acciones habituales (actions/checkout, actions/setup-node, etc.). Renombre la carpeta .github/workflows/ como .gitea/workflows/ para activar el runner de Gitea de forma limpia (ambas rutas están soportadas, pero .gitea/ es la ruta nativa).

Verificaciones posteriores a la migración

Resolución de problemas — errores habituales

1. 07

   SSH: `Permission denied (publickey)`

   Síntoma: git clone [email protected]:… falla con Permission denied (publickey).

   Comprobación: en Gitea, Settings → SSH / GPG Keys — la clave pública que utiliza debe figurar ahí. Añádala si falta (cat ~/.ssh/id_ed25519.pub | pbcopy o xclip).

   Si la clave está presente pero el error persiste, compruebe que el puerto SSH de Gitea es efectivamente el 22 (o el puerto configurado): ssh -vT [email protected] -p 22 mostrará la negociación y el mensaje de aceptación de Gitea si la clave se reconoce.

2. 08

   Remote: `fatal: repository not found`

   Síntoma: git fetch devuelve fatal: repository 'https://git.votre-domaine.com/…' not found.

   Diagnóstico: git remote -v — compruebe que la URL apunta realmente a su instancia de Gitea y no a github.com. Si la URL es correcta, conéctese a la interfaz de Gitea y confirme que el repositorio existe con el nombre de organización correcto. Un POST /api/v1/repos/migrate que ha fallado en silencio deja el repositorio ausente, sin mensaje de error en el remote local.

3. 09

   Webhooks silenciosos tras la migración

   Síntoma: un git push no dispara ninguna build en su CI.

   Diagnóstico: en Gitea, Site Administration → System Settings → Git Hooks — active el registro de los hooks. Después, en el repositorio, Settings → Webhooks → última entrega: el campo «Response» muestra el código HTTP devuelto por su CI. Un 404 significa que la URL del webhook apunta a una ruta inexistente; un 401 significa un secreto HMAC mal configurado.

   Active el modo debug del runner: en el archivo de configuración de gitea-runner, ponga log_level en debug y reinicie el daemon. Los logs mostrarán la recepción de cada evento y el código de activación del job.

Alojar Gitea en un VPS ServOrbit