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](http://gitea.cruzcloud.net/devops/apps-registry/pulls/1)

## 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:

```bash
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:

```bash
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:

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

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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`.