Skip to main content

Estándar Corporativo de Repositorios GitHub

Objetivo​

Definir un estándar corporativo para la organización de repositorios GitHub que permita:

  • Escalabilidad.
  • Gobierno centralizado.
  • Facilidad de búsqueda.
  • Automatización CI/CD.
  • Gestión de permisos.
  • Trazabilidad de componentes.
  • Integración con DevOps.
  • Incorporación rápida de nuevos colaboradores.

Problema Actual

Actualmente la estructura proviene de GitLab y está basada en grupos y subgrupos.

Ejemplo:

DevOps
├── alpura-devops-back-java-msa-consulta
├── alpura-devops-back-java-msa-dashboard
├── alpura-devops-back-java-msa-producto
├── alpura-devops-sienpro-back-java-msa-hcm
├── alpura-devops-sienpro-back-java-msa-transactions
└── alpura-devops-frontend-angular-mfe-remote-sienpro

Services
├── alpura-back-java-msa-dashboard
├── alpura-back-java-msa-producto
├── alpura-back-msa-interface-hcm
├── alpura-back-msa-transactions
└── alpura-frontend-angular-mfe-remote-sienpro

Shared Libraries
└── alpura-back-java-lib-model-sienpro

Limitación de GitHub

GitHub no soporta jerarquías profundas de grupos como GitLab.

GitHub está diseñado para trabajar mediante:

  • Organizations
  • Teams
  • Repositories
  • Topics
  • CODEOWNERS

Por lo tanto, intentar replicar exactamente la estructura de GitLab suele generar:

  • Nombres excesivamente largos.
  • Difícil navegación.
  • Duplicidad de información.
  • Problemas de búsqueda.

Arquitectura Recomendada

Organización Principal​

github.com/alpura-ti

Equipos (Teams)​

Estructura Recomendada

Convención de Nombres

Formato General​

<dominio>-<capa>-<tipo>-<nombre>

Ejemplos​

Backend​

sienpro-back-ms-hcm
sienpro-back-ms-producto
sienpro-back-ms-dashboard
sienpro-back-ms-transactions

Frontend​

sienpro-front-mfe-remote
sienpro-front-mfe-entrega
sienpro-front-mfe-consulta

Batch​

sienpro-back-batch-sync-tickets
sienpro-back-batch-update-employees
sienpro-back-batch-block-product

Librerías​

shared-lib-model-sienpro
shared-lib-security
shared-lib-observability

DevOps​

devops-terraform-gcp
devops-kubernetes-manifests
devops-pipelines
devops-helm-charts

Documentación​

docs-arquitectura
docs-plataforma
docs-desarrollo

Mapeo GitLab → GitHub

GitLabGitHub
GroupTeam
SubgroupTeam
ProjectRepository
MembersTeam Members
CI/CDGitHub Actions
Protected BranchesBranch Protection Rules
VariablesSecrets
RegistryGitHub Packages

Ventajas del Estándar

1. Nombres más Cortos​

Antes​

alpura-devops-sienpro-back-java-msa-transactions

Después​

sienpro-back-ms-transactions

Reducción:

47 caracteres
↓
28 caracteres

2. Mejor Búsqueda​

GitHub permite localizar fácilmente:

sienpro-back-ms-*

o

topic:spring-boot

o

topic:angular

3. Menor Acoplamiento​

La tecnología deja de formar parte del nombre.

Incorrecto​

sienpro-back-java-msa-producto

Correcto​

sienpro-back-ms-producto

Si mañana migra a:

  • Java 21
  • Quarkus
  • Kotlin
  • NodeJS

el repositorio conserva su nombre.

4. Automatización Más Simple​

Todos los proyectos pueden heredar el mismo estándar.

Uso de Topics

GitHub Topics reemplaza información innecesaria dentro del nombre.

Ejemplo​

Repositorio:

sienpro-back-ms-hcm

Topics:

spring-boot
java21
microservice
gcp
kubernetes
hcm
sienpro

CODEOWNERS

Cada repositorio debe tener:

.github/CODEOWNERS

Ejemplo:

* @alpura-ti/backend

Estructura Interna Recomendada

.
├── README.md
├── CHANGELOG.md
├── CODEOWNERS
├── .github
│   ├── workflows
│   │   ├── ci.yml
│   │   ├── cd-dev.yml
│   │   ├── cd-uat.yml
│   │   └── cd-prod.yml
│   │
│   └── pull_request_template.md
│
├── docs
├── src
├── helm
├── k8s
├── Dockerfile
└── Jenkinsfile

Errores Comunes

Error 1​

Incorrecto​

alpura-devops-sienpro-back-java-msa-hcm

Problemas:

  • Nombre excesivamente largo.
  • Información duplicada.
  • Difícil búsqueda.

Correcto​

sienpro-back-ms-hcm

Error 2​

Incorrecto​

java-producto

Problema:

No identifica dominio funcional.

Correcto​

sienpro-back-ms-producto

Error 3​

Incorrecto​

backend-hcm

Problema:

No indica plataforma ni contexto.

Correcto​

sienpro-back-ms-hcm

Error 4​

Incorrecto​

Crear repositorios por ambiente.

sienpro-back-ms-producto-dev
sienpro-back-ms-producto-uat
sienpro-back-ms-producto-prod

Problemas:

  • Duplicidad.
  • Drift de código.
  • Mantenimiento complejo.

Correcto​

sienpro-back-ms-producto

Y usar:

GitHub Environments
DEV
UAT
PROD

Estrategia de Branches

Estrategia de Ambientes

Despliegues gestionados mediante:

  • GitHub Actions
  • ArgoCD
  • Helm
  • Kubernetes

Estándar Oficial Propuesto

Organization:
alpura-ti

Teams:
arquitectura
devops
backend
frontend
qa
seguridad
integraciones

Repositorios:

api-gateway-wso2
config-server

devops-terraform-gcp
devops-kubernetes-manifests
devops-pipelines

sienpro-back-ms-dashboard
sienpro-back-ms-producto
sienpro-back-ms-hcm
sienpro-back-ms-transactions

sienpro-front-mfe-remote

sienpro-back-batch-sync-tickets
sienpro-back-batch-block-product
sienpro-back-batch-update-employee-tickets

shared-lib-model-sienpro
shared-lib-observability
shared-lib-security

docs-arquitectura

Beneficios Esperados

BeneficioImpacto
Menor complejidadAlto
Mejor gobiernoAlto
Menor curva de aprendizajeAlto
EscalabilidadAlto
AutomatizaciónAlto
SeguridadAlto
Integración GitHub EnterpriseAlto
MantenimientoAlto

Este estándar busca desacoplar la organización funcional de la tecnología utilizada, permitiendo una evolución tecnológica continua sin afectar la estructura de repositorios ni los procesos de gobierno corporativo.