Skip to content

Instantly share code, notes, and snippets.

@jluisflo

jluisflo/MIGRACION_GITLAB_A_GITHUB.md

Created December 18, 2025 21:30
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jluisflo/963dcccccf59e823ef3a3f79e48f7be6 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jluisflo/963dcccccf59e823ef3a3f79e48f7be6 to your computer and use it in GitHub Desktop.
Download ZIP
MPAY - Analisis de Migracion GitLab a GitHub para DevOps
Raw
MIGRACION_GITLAB_A_GITHUB.md

MPAY - Analisis de Migracion GitLab a GitHub

Fecha: Diciembre 2025 Objetivo: Documentar dependencias y requisitos para migrar repositorios de GitLab a GitHub y configurar ambiente de desarrollo local.

1. Resumen Ejecutivo

MPAY es una plataforma BNPL (Buy Now Pay Later) compuesta por 5 microservicios con arquitectura event-driven. Actualmente los repositorios estan en GitLab con CI/CD configurado usando templates compartidos.

Servicios del Sistema

Servicio Tecnologia Puerto Funcion
api-laravel PHP 8.2 / Laravel 10 8051 API principal, logica de negocio
back-office PHP 8.2 / Laravel 10 + Nova + Vue 3 80 Panel de administracion
database-laravel Laravel Package - Migraciones y esquema DB compartido
documents-ocr Python 3.13 / FastAPI 8000 OCR con Google Gemini AI
onboarding Next.js 14 / React 18 3000 App de solicitud de credito

2. Dependencias Criticas de GitLab

2.1 Repositorio de Templates CI/CD

Ubicacion actual: elaniin/mercandu-pay/n1co/gitlab-configs

Los 4 servicios principales dependen de templates compartidos:

# Templates usados por api-laravel y back-office
- '/templates/php/Setup.gitlab-ci.yml'     # Instalacion de dependencias PHP
- '/templates/php/Scan.gitlab-ci.yml'      # Analisis estatico de codigo
- '/templates/php/Test-pest.gitlab-ci.yml' # Tests con Pest
- '/templates/php/Test.gitlab-ci.yml'      # Tests con PHPUnit
- '/templates/Security.gitlab-ci.yml'      # Escaneo de seguridad
- '/templates/Build.gitlab-ci.yml'         # Build de Docker
- '/templates/Deploy.gitlab-ci.yml'        # Deploy a Kubernetes

# Templates usados por onboarding y documents-ocr
- '/templates/Custom-Build.gitlab-ci.yml'  # Build personalizado
- '/templates/Deploy.gitlab-ci.yml'        # Deploy a Kubernetes

ACCION REQUERIDA:

  • Migrar repositorio gitlab-configs a GitHub
  • Convertir templates de GitLab CI a GitHub Actions

2.2 Imagenes Docker del Registry

Registry actual: registry.gitlab.com/elaniin/mercandu-pay/n1co/

Imagenes usadas en CI:

  • gitlab-ci-images:8.2.1-php-fpm (PHP para CI)

ACCION REQUERIDA:

  • Migrar imagenes a GitHub Container Registry (ghcr.io)
  • O usar Docker Hub / AWS ECR

2.3 Paquete Privado database-laravel

Ubicacion: git@gitlab.com:elaniin/mercandu-pay/n1co/database-laravel.git

Usado como dependencia Composer en:

  • api-laravel
  • back-office
// composer.json
"repositories": [
    {
        "type": "vcs",
        "url": "git@gitlab.com:elaniin/mercandu-pay/n1co/database-laravel.git"
    }
]

ACCION REQUERIDA:

  • Migrar repositorio a GitHub
  • Actualizar URL en composer.json de ambos proyectos
  • Configurar GitHub token para acceso privado

3. Secretos y Variables de CI/CD

3.1 Variables Globales (GitLab Group/Project)

Variable Uso Servicio
GITLAB_TOKEN Acceso a paquetes privados Composer api-laravel, back-office
NOVA_USERNAME Credenciales Laravel Nova back-office
NOVA_LICENSE_KEY Licencia Laravel Nova (paga) back-office

3.2 Variables de Ambiente por Servicio

api-laravel

# Base de datos
DB_CONNECTION=mysql
DB_HOST=
DB_PORT=3306
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=

# Servidor
SERVER_PORT=8051
SERVER_HOST=0.0.0.0
APP_KEY=              # Clave de encriptacion Laravel

# Cache/Queue
REDIS_HOST=
REDIS_PORT=6379
QUEUE_CONNECTION=redis  # Produccion

# SMS (Tigo)
TIGO_DOMAIN=
TIGO_REMITENTE=
TIGO_USERNAME=
TIGO_PASSWORD=

# AWS S3
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=

# URLs internas
DASHBOARD_URL=
PAYMENT_URL=

back-office

# Todo lo anterior de api-laravel, mas:

# Conexion a API core
APP_CORE_URL=http://localhost:8051

# Laravel Nova
NOVA_LICENSE_KEY=
NOVA_STORAGE_DISK=

# Keycloak SSO
KEYCLOAK_CLIENT_ID=
KEYCLOAK_CLIENT_SECRET=
KEYCLOAK_REDIRECT_URI=
KEYCLOAK_BASE_URL=
KEYCLOAK_REALM=
KEYCLOAK_CACHE_TOKEN=
KEYCLOAK_PUBLIC_KEY_NAME=keycloak-public.key

onboarding (Next.js)

# Build-time variables (prefijo NEXT_PUBLIC_)
NEXT_PUBLIC_CORE_URL=
NEXT_PUBLIC_WEB_URL=
NEXT_PUBLIC_PUBLIC_URL=
NEXT_PUBLIC_API_URL=
NEXT_PUBLIC_PAY_WEB=
NEXT_PUBLIC_AVAILABLE_COUNTRIES=SV,HN
NEXT_PUBLIC_APP_DOMAIN=
NEXT_PUBLIC_MIXPANEL_TOKEN=
NEXT_PUBLIC_PRODUCT_ID=
NEXT_PUBLIC_PRODUCT_NAME=

documents-ocr (Python)

# Google Cloud
PROJECT_ID=
LOCATION=us-central1
BUCKET_NAME=
GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json

4. Secretos de Kubernetes

Los deployments requieren secretos montados como volumenes:

# api-laravel deployment
volumes:
  - name: keycloak-public-key
    secret:
      secretName: dev-keycloak-public-key
  - name: oauth-private-key
    secret:
      secretName: dev-oauth-private-key
  - name: oauth-public-key
    secret:
      secretName: dev-oauth-public-key

Secretos K8s requeridos:

  1. {env}-keycloak-public-key - Llave publica de Keycloak
  2. {env}-oauth-private-key - Llave privada OAuth (Passport)
  3. {env}-oauth-public-key - Llave publica OAuth
  4. {env}-pay-api-laravel-config - ConfigMap con variables de entorno
  5. {env}-pay-back-office-config - ConfigMap para back-office

5. Servicios Externos

5.1 Infraestructura

Servicio Proposito Proveedor
MySQL 8.0 Base de datos AWS RDS / DigitalOcean
Redis Cache y colas AWS ElastiCache / DO Redis
Kubernetes Orquestacion AWS EKS / DigitalOcean K8s
Container Registry Imagenes Docker GitLab Registry -> GitHub/AWS ECR

5.2 Servicios de Terceros

Servicio Proposito Configuracion
Keycloak OAuth 2.0 / SSO Self-hosted o Keycloak Cloud
Equifax Buro de credito API con credenciales
Tigo SMS El Salvador API con credenciales
Twilio SMS alternativo API con credenciales
AWS S3 Almacenamiento documentos Access key + Secret
Google Cloud OCR con Gemini AI Service Account JSON
Mixpanel Analytics Token publico
Sentry Error tracking DSN

6. Arquitectura de CI/CD Actual

6.1 Stages del Pipeline

setup -> sca -> test -> build -> security -> deploy
  1. setup: Instalar dependencias (Composer/npm)
  2. sca: Static Code Analysis (linting)
  3. test: Unit tests (Pest/PHPUnit/Jest)
  4. build: Docker build + push a registry
  5. security: Escaneo de vulnerabilidades
  6. deploy: Deploy a Kubernetes

6.2 Ambientes de Deploy

Branch Ambiente Dominio
develop, feature/* development *.mdu.dev
staging staging *.mdu.stg
main production *.mercandu.com

6.3 Subdominios por Servicio

Servicio Desarrollo Produccion
api-laravel backend.pay.mdu.dev backend.pay.mercandu.com
back-office dashboard.pay.mdu.dev dashboard.pay.mercandu.com
onboarding onboarding.pay.mdu.dev onboarding.pay.mercandu.com
documents-ocr documents-ocr-api.mdu.dev documents-ocr-api.mercandu.com

7. Dependencias por Servicio

7.1 api-laravel (PHP)

Composer dependencies principales:

{
  "php": "^8.2",
  "laravel/framework": "^10.0",
  "laravel/octane": "^1.3",        // Servidor Swoole
  "laravel/horizon": "^5.10",      // Job queues
  "laravel/passport": "^11.0",     // OAuth2
  "firebase/php-jwt": "^6.3",
  "mercandu-pay/database-laravel": "dev-develop",  // Paquete privado
  "sentry/sentry-laravel": "^3.1",
  "twilio/sdk": "^6.43",
  "spatie/laravel-permission": "^5.5",
  "maatwebsite/excel": "^3.1",
  "spatie/laravel-google-cloud-storage": "^2.3"
}

Extensiones PHP requeridas:

  • redis, openswoole
  • intl, gd, pdo_mysql, mysqli
  • zip, gmp, pcntl, bcmath

7.2 back-office (PHP + Node)

Composer adicionales:

{
  "laravel/nova": "~4.0",          // Panel admin (licencia paga)
  "socialiteproviders/keycloak": "^5.2"
}

npm dependencies:

  • Vue 3, Inertia.js, TailwindCSS
  • Vite para build de assets

Nova Components personalizados:

nova-components/
├── PermissionPicker/
├── Picker/
├── DecisionRuleField/
└── ConditionalBuilder/

7.3 onboarding (Node.js)

{
  "next": "14.2.4",
  "react": "^18",
  "tailwindcss": "^3.4.1",
  "react-hook-form": "^7.52.1",
  "zod": "^3.23.8",
  "mixpanel-browser": "^2.55.0",
  "framer-motion": "^11.2.13",
  "@radix-ui/react-*": "varios"
}

7.4 documents-ocr (Python)

fastapi
uvicorn
google-cloud-storage
google-genai
python-magic
python-multipart

8. Configuracion de Desarrollo Local

8.1 Requisitos del Sistema

- Docker & Docker Compose
- PHP 8.2 + Composer 2.7 (opcional, para CLI)
- Node.js 16+ y npm
- Python 3.13
- MySQL 8.0 o Docker container
- Redis o Docker container

8.2 Pasos para Levantar el Ambiente

1. Clonar repositorios

git clone git@github.com:org/mpay.git
cd mpay

2. Base de datos y Redis

# Opcion A: Usar docker-compose de api-laravel
cd api-laravel
docker-compose up -d mysql redis

# Opcion B: Docker standalone
docker run -d --name mysql -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=laravel \
  mysql:8.0

docker run -d --name redis -p 6379:6379 redis:alpine

3. api-laravel

cd api-laravel

# Copiar .env
cp .env.example .env

# Configurar acceso a paquete privado
composer config gitlab-token.gitlab.com YOUR_TOKEN
# O para GitHub:
composer config github-oauth.github.com YOUR_GITHUB_TOKEN

# Instalar dependencias
composer install

# Generar key y migrar
php artisan key:generate
php artisan vendor:publish --tag=mercandu-pay-database
php artisan migrate

# Iniciar servidor (development)
php artisan serve --port=8051
# O con Octane (produccion-like)
php artisan octane:start --port=8051

4. back-office

cd back-office

cp .env.example .env

# Credenciales Nova
composer config http-basic.nova.laravel.com "$NOVA_USERNAME" "$NOVA_LICENSE_KEY"
composer config gitlab-token.gitlab.com YOUR_TOKEN

composer install
npm install
npm run dev  # Compilar assets

php artisan key:generate
php artisan vendor:publish --tag=mercandu-pay-database
php artisan migrate

php artisan serve --port=8050

5. onboarding

cd onboarding

# Crear .env.local con variables NEXT_PUBLIC_*
npm install
npm run dev  # Puerto 3000

6. documents-ocr

cd documents-ocr

python -m venv venv
source venv/bin/activate  # Linux/Mac
pip install -r requirements.txt

# Configurar credenciales Google Cloud
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json
export PROJECT_ID=your-project
export BUCKET_NAME=your-bucket

python main.py  # Puerto 8000

9. Plan de Migracion a GitHub

Fase 1: Preparacion (Semana 1-2)

Tarea Complejidad Responsable
Crear organizacion/repos en GitHub Baja DevOps
Migrar repositorio gitlab-configs Media DevOps
Migrar repositorio database-laravel Baja DevOps
Crear GitHub Actions equivalentes a templates Alta DevOps
Configurar GitHub Container Registry Baja DevOps
Configurar secretos en GitHub Baja DevOps

Fase 2: Migracion de Servicios (Semana 2-3)

Servicio Complejidad Notas
documents-ocr Baja Sin dependencias GitLab especiales
onboarding Baja Solo variables de build
api-laravel Media Dependencia de database-laravel
back-office Alta Nova license + Keycloak + database-laravel

Fase 3: CI/CD (Semana 3-4)

Tarea Complejidad Detalle
Crear workflows de GitHub Actions Alta 4 servicios x 3 ambientes
Configurar deploy a K8s desde GitHub Media Secrets de kubeconfig
Testing de pipelines en desarrollo Media
Cutover a produccion Alta Coordinacion con equipo

10. Conversion de GitLab CI a GitHub Actions

Ejemplo: api-laravel

GitLab CI actual (.gitlab-ci.yml):

image: registry.gitlab.com/elaniin/mercandu-pay/n1co/gitlab-ci-images:8.2.1-php-fpm

stages:
  - setup
  - test
  - build
  - deploy

include:
  - project: elaniin/mercandu-pay/n1co/gitlab-configs
    file: '/templates/php/Setup.gitlab-ci.yml'

GitHub Actions equivalente (.github/workflows/ci.yml):

name: CI/CD

on:
  push:
    branches: [main, develop, 'feature/**']
  pull_request:
    branches: [main, develop]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  setup:
    runs-on: ubuntu-latest
    container:
      image: php:8.2-fpm
    steps:
      - uses: actions/checkout@v4
      - name: Install Composer
        run: curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
      - name: Configure Composer
        run: |
          composer config github-oauth.github.com ${{ secrets.COMPOSER_GITHUB_TOKEN }}
      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader
      - uses: actions/cache@v4
        with:
          path: vendor
          key: vendor-${{ hashFiles('composer.lock') }}

  test:
    needs: setup
    runs-on: ubuntu-latest
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: password
          MYSQL_DATABASE: testing
        ports:
          - 3306:3306
    steps:
      - uses: actions/checkout@v4
      - uses: actions/cache@v4
        with:
          path: vendor
          key: vendor-${{ hashFiles('composer.lock') }}
      - name: Run tests
        run: vendor/bin/pest

  build:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          build-args: |
            GITHUB_TOKEN=${{ secrets.COMPOSER_GITHUB_TOKEN }}
            DATABASE_PROJECT_BRANCH=develop

  deploy-dev:
    needs: build
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    environment: development
    steps:
      - name: Deploy to K8s
        uses: azure/k8s-deploy@v4
        with:
          manifests: .k8s/dev/
          images: ghcr.io/${{ github.repository }}:${{ github.sha }}

11. Estimacion de Esfuerzo

Por Actividad

Actividad Horas Estimadas Equipo
Crear estructura en GitHub 4h DevOps
Migrar repositorios (5) 2h DevOps
Convertir 6 templates CI a Actions 24h DevOps
Crear workflows por servicio (4) 16h DevOps
Configurar secretos/variables 4h DevOps
Migrar Container Registry 4h DevOps
Actualizar referencias en codigo 8h Dev
Testing de pipelines (dev) 16h DevOps + Dev
Testing de pipelines (stg/prd) 8h DevOps
Documentacion 8h DevOps + Dev
TOTAL 94h (~12 dias)

Por Complejidad de Servicio

Servicio Complejidad Razon
documents-ocr Baja Python simple, sin dependencias privadas
onboarding Baja Next.js estandar, solo env vars
api-laravel Media Paquete privado, Kubernetes config
back-office Alta Nova license, Keycloak, paquete privado, Vue build

12. Riesgos y Mitigaciones

Riesgo Impacto Mitigacion
Licencia Nova expira durante migracion Alto Verificar renovacion antes de migrar
Secrets perdidos o mal configurados Alto Documentar todos los secrets, backup
Downtime durante cutover Medio Hacer cutover en horario de baja carga
Falla en deploy a K8s desde GitHub Medio Mantener GitLab funcional como fallback
Dependencias no resueltas en GitHub Alto Probar build local antes de migrar CI

13. Checklist de Migracion

Pre-Migracion

  • Crear organizacion en GitHub
  • Crear todos los repositorios vacios
  • Configurar GitHub Container Registry
  • Obtener/renovar licencia Laravel Nova
  • Documentar todos los secretos actuales
  • Exportar variables de CI/CD de GitLab

Migracion

  • Push de codigo a GitHub (todos los repos)
  • Migrar database-laravel primero
  • Actualizar composer.json con nueva URL
  • Crear GitHub Actions workflows
  • Configurar secrets en GitHub
  • Build y test en desarrollo

Post-Migracion

  • Verificar deploys a development
  • Verificar deploys a staging
  • Cutover de produccion
  • Deshabilitar pipelines de GitLab
  • Actualizar documentacion interna
  • Archivar repositorios en GitLab

14. Contactos y Recursos

Documentacion

Archivos de Referencia en el Repo

  • MPAY_DOCUMENTATION.md - Documentacion general del sistema
  • api-laravel/.k8s/ - Manifiestos Kubernetes
  • */Dockerfile - Configuracion de contenedores
  • */.gitlab-ci.yml - Pipelines actuales (referencia)

Documento generado automaticamente - Diciembre 2025

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment