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

---

Organización de GitHub

La jerarquía organizativa en GitHub Enterprise está diseñada para respetar estrictamente el principio de menor privilegio, permitiendo la autonomía de los equipos sin comprometer la seguridad empresarial.

---

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

GitLab	GitHub
Group	Team
Subgroup	Team
Project	Repository
Members	Team Members
CI/CD	GitHub Actions
Protected Branches	Branch Protection Rules
Variables	Secrets
Registry	GitHub 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

Beneficio	Impacto
Menor complejidad	Alto
Mejor gobierno	Alto
Menor curva de aprendizaje	Alto
Escalabilidad	Alto
Automatización	Alto
Seguridad	Alto
Integración GitHub Enterprise	Alto
Mantenimiento	Alto

---

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.