scripts/docs/playbooks/gitops-commit-workflow.md

Playbook: fix de inconsistencia y flujo de commit en repos GitOps

Reconstruido a partir del fix real ejecutado el 2026-08-09 en apps-registry sobre repoURL (http vs https). Úsalo como referencia reproducible para cualquier fix similar (inconsistencias de configuración, typos en manifiestos, etc.) en apps-registry, platform-infra o scripts.

Caso real de referencia

• Repo: devops/apps-registry
• Síntoma: apps/ecommerce-app.yaml apuntaba a repoURL: http://gitea.cruzcloud.net/... mientras que application.yaml (raíz, App of Apps) usaba https://. Argo CD trataba ambos como fuentes distintas por el esquema, generando drift/ambigüedad en el App of Apps.
• Rama: fix/repo-url-consistency
• Commit: a90c0a7 — fix(gitops): usar https en repoURL de ecommerce-app para consistencia con application.yaml
• PR: #1 — fix(gitops): unificar repoURL a https en ecommerce-app

1. Detectar la inconsistencia

Antes de tocar nada, confirma el alcance real del problema comparando el repoURL de la Application raíz contra todas las Applications hijas:

grep -rn "repoURL" application.yaml apps/

En este caso mostró la mezcla http:// / https:// sobre el mismo host (gitea.cruzcloud.net), lo que confirmó que era un problema de consistencia y no de configuración intencional por app.

2. Crear la rama de fix

Nunca se edita ni se commitea directo sobre main (regla del repo). Se parte siempre de main actualizado:

git checkout main
git pull origin main
git checkout -b fix/repo-url-consistency

3. Aplicar el cambio y commitear

Edita solo el/los archivo(s) afectado(s) — cambio mínimo, sin tocar nada más:

# apps/ecommerce-app.yaml
spec:
  source:
-   repoURL: http://gitea.cruzcloud.net/devops/apps-registry.git
+   repoURL: https://gitea.cruzcloud.net/devops/apps-registry.git

git add apps/ecommerce-app.yaml
git commit -m "fix(gitops): usar https en repoURL de ecommerce-app para consistencia con application.yaml"

4. Intento de push por SSH (falló) y por qué

El primer intento fue generar clave SSH y cambiar el remote para pushear por SSH:

ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_ed25519
git remote set-url origin [email protected]:devops/apps-registry.git
git push -u origin fix/repo-url-consistency

Resultado: timeout/conexión rechazada en el puerto 22. Causa raíz: gitea.cruzcloud.net está detrás de Cloudflare en modo proxy (nube naranja), que solo reenvía tráfico HTTP/HTTPS (80/443). El puerto 22 (SSH) no está expuesto a través del proxy, así que cualquier clon/push por SSH contra ese hostname fallará mientras el registro DNS siga proxied.

Alternativas si en el futuro se necesita SSH de verdad: usar un puerto SSH alterno expuesto directamente (sin proxy Cloudflare), un registro DNS "solo DNS" (nube gris) para un subdominio dedicado a Git, o simplemente quedarse con HTTPS (ver siguiente paso) — es la opción soportada aquí.

5. Fallback a HTTPS con credential helper

Se revirtió el remote a HTTPS y se configuró un credential helper para no tener que reautenticar en cada push:

git remote set-url origin https://gitea.cruzcloud.net/devops/apps-registry.git

git config --global credential.helper store
git config --global credential.username devops
git config --global credential.usehttppath false

# Blindaje extra: reescribe cualquier referencia http:// a https:// para
# este host a nivel de git, para que un remote/URL mal escrito con http
# nunca vuelva a intentar una ruta insegura o inconsistente.
git config --global url."https://gitea.cruzcloud.net/".insteadOf "http://gitea.cruzcloud.net/"

El primer git push después de esto pide usuario/token una única vez y lo persiste (en texto plano) en ~/.git-credentials — de ahí en adelante los pushes son no interactivos.

6. Push de la rama

git push -u origin fix/repo-url-consistency

7. Abrir y mergear el PR

Vía UI de Gitea (http://gitea.cruzcloud.net/devops/apps-registry/pulls) o, de forma reproducible, vía API:

curl -sk -u devops:$GITEA_TOKEN \
  -X POST "https://gitea.cruzcloud.net/api/v1/repos/devops/apps-registry/pulls" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "fix(gitops): unificar repoURL a https en ecommerce-app",
    "body": "Corrige inconsistencia http/https en repoURL detectada entre application.yaml y apps/ecommerce-app.yaml.",
    "base": "main",
    "head": "fix/repo-url-consistency"
  }'

Revisar el diff en el PR (regla del repo: nunca merge/push a main sin mostrar el diff primero) y, tras aprobarlo:

curl -sk -u devops:$GITEA_TOKEN \
  -X POST "https://gitea.cruzcloud.net/api/v1/repos/devops/apps-registry/pulls/1/merge" \
  -H "Content-Type: application/json" \
  -d '{"Do": "merge"}'

Tras el merge, Argo CD (con selfHeal:true) reconcilia automáticamente y el App of Apps deja de reportar la inconsistencia de repoURL.

Checklist reproducible para el próximo fix similar

1. grep -rn "<campo a validar>" application.yaml apps/ para confirmar el alcance real del problema.
2. git checkout main && git pull && git checkout -b fix/<slug-descriptivo>
3. Cambio mínimo + commit con mensaje fix(gitops): ... en español, describiendo el qué y el porqué.
4. Si el push falla por SSH contra gitea.cruzcloud.net: es casi seguro el proxy de Cloudflare bloqueando el puerto 22 — no perder tiempo debuggeando SSH, volver a HTTPS directamente.
5. Confirmar credential.helper=store y url.<https>.insteadOf=<http> ya configurados globalmente (si no, configurarlos una sola vez, no por repo).
6. git push -u origin fix/<slug-descriptivo>
7. Abrir PR, mostrar el diff, esperar aprobación, mergear.
8. Verificar en Argo CD que la Application correspondiente vuelve a Synced.