Guía de repositorios, despliegue y cambios
Esta página registra el comportamiento declarado de lanzamiento en los commits revisados. Vuelva a leer las reglas actuales de CI antes de operar un carril; una canalización de origen en verde no establece por sí sola la activación del dispositivo o el procesamiento exitoso en segundo plano.
Mapa de repositorios y carriles de lanzamiento
| Repositorio | Integración / ruta de lanzamiento | Fuente |
|---|---|---|
riveroaks/portal |
MR de características/errores → dev → origen de desarrollo; dev aceptado → promoción a main → origen de producción |
portal · .gitlab-ci.yml, portal · .gitlab-ci.yml |
riveroaks/portal-api |
MR → dev, plan/aplicación/verificación automática; promoción revisada a main, la aplicación de producción requiere una puerta de enlace |
portal-api · CONTRIBUTING.md, portal-api · .gitlab-ci.yml |
riveroaks/portal-ios |
El trabajo de desarrollo apunta a dev; los trabajos de TestFlight y Portal-iPad Jamf protegidos para desarrolladores son automáticos. Los lanzamientos independientes del panel y de Utilidades son manuales; el calendario de caducidad de Utilidades no puede desplegarse. La configuración de lanzamiento por sí sola no es una publicación en la App Store |
portal-ios · CONTRIBUTING.md, portal-ios · .gitlab-ci.yml, portal-ios · Configuration/Release.xcconfig |
riveroaks/infra |
main posee manifiestos/scripts de host; los trabajos de despliegue son específicos del objetivo y están controlados. Inspeccione el trabajo seleccionado antes de ejecutarlo |
infra · .gitlab-ci.yml, infra · docs/deploy/gitlab-ci.md |
riveroaks/infrastructure/lyric-follower |
Validación/rueda main; firma de Mac controlada por operador/activación de Jamf. El despliegue del host observador es un trabajo de infraestructura separado |
infrastructure/lyric-follower · .gitlab-ci.yml, infrastructure/lyric-follower · docs/deployment-pipeline.md, infra · deploy/scripts/deploy-lyric-follower-shadow.sh |
riveroaks/infrastructure/service-timeline |
Validación/rueda main; despliegue y aceptación atendidos, sin despliegue automático |
infrastructure/service-timeline · .gitlab-ci.yml, infrastructure/service-timeline · README.md |
| Formularios, Correo electrónico, Enlaces cortos | Canalizaciones main independientes con IaC de desarrollo/producción y puertas de enlace de producción protegidas/manuales; no es una promoción de Portal de dev a main |
cloudflare-forms · .gitlab-ci.yml, cloudflare-email · .gitlab-ci.yml, cloudflare-short-links · .gitlab-ci.yml |
riveroaks/docs |
MR de características/errores → validación estricta → main; traducción, compilación estática, despliegue de Páginas, despliegue privado, publicación de imágenes |
docs · .gitlab-ci.yml, docs · README.md |
Promoción de imagen de documentación privada
El vhost actual de documentación privada actúa como proxy para el clúster. La CI principal de Documentos actualiza una versión local inmutable de reversión y publica una nueva imagen de sitio estático; cluster-image.txt proporciona el digest. Un MR revisado de riveroaks/infra debe actualizar el digest fijado del Deployment de Documentos antes de que Flux implemente la versión candidata. Un trabajo deploy_internal exitoso por sí solo no demuestra que el nombre de host privado esté sirviendo su nuevo contenido. Verifique una página cambiada después de la promoción de la imagen. Conserve el digest anterior para una reversión solo de la aplicación a través de la misma ruta GitOps.
Fuentes:
docs · tools/publish-cluster-image.sh,
docs · README.md,
infra · k3s/gitops/apps/docs/workload.yaml,
infra · nginx/hosts/rocc-db/sites-enabled/docs.riveroaks.cc.conf.
Lanzamiento de un cambio que abarca varios repositorios
- Implemente y despliegue cambios aditivos de adaptador/esquema PHP a través de Portal
dev. Confirme la aplicación/verificación de la migración y la salud en tiempo de ejecución. - Actualice el catálogo de API/comportamiento del borde a través de API
dev; verifique las verificaciones de borde y de origen privado y los fixtures de autenticación/RBAC. - Integre el cliente nativo en iOS
dev. Verifique su par de nombres de host configurado, decodificando fixtures y trabajos de lanzamiento reales antes de fusionar:devpuede alcanzar los iPads del campus administrados automáticamente. - Acepte en desarrollo con datos controlados. Los datos presupuestarios pueden ser datos reales del libro mayor de producción a pesar del nombre de host de desarrollo.
- Para un lanzamiento de producción web/API aprobado, promueva el origen del Portal antes de la API; inspeccione el plan de producción y la puerta de enlace. El lanzamiento de producción nativo es un proceso separado aprobado por el propietario.
Este orden es la secuencia de compatibilidad recomendada derivada del límite del adaptador
y los controles de lanzamiento. Fuentes: portal · .gitlab-ci.yml,
portal · docs/technology-budget-sql-ledger.md, portal-api · docs/MIGRATION.md,
portal-api · .gitlab-ci.yml, portal-ios · .gitlab-ci.yml.
Límites de activación y reversión
| Componente | Límite de recuperación | Libro de jugadas / implementación |
|---|---|---|
| API | Volver a desplegar la versión revisada anterior a través del carril; conservar los recursos de Worker/túnel e inspeccionar la compatibilidad del esquema | portal-api · docs/OPERATIONS.md, portal-api · infra/modules/portal-platform/main.tf |
| Portal | Reconciliar a través de CI y las migraciones requeridas; no revertir ciegamente el esquema aditivo. La falta de coincidencia de tokens/esquemas ha causado fallos de inicio de sesión | portal · .gitlab-ci.yml, portal · docs/PRODUCTION_API_SESSION_INCIDENT_2026-09-08.md |
| Daemons PHP de letras de canciones | Copiar código no reemplaza procesos en ejecución; reinicios de activación protegidos y verificación de servicios/sockets | portal · .gitlab/activate-lyrics-services.sh |
| Sombra de letras de canciones | El script de infraestructura fija las IDs de imagen candidata/anterior, conserva la unidad anterior e intenta la reversión en caso de fallo de activación | infra · deploy/scripts/deploy-lyric-follower-shadow.sh |
| Mac de captura | Conservar el paquete anterior firmado y la configuración compatible; activar inactivo/drenado y luego verificar la versión en ejecución, no solo los archivos instalados | infrastructure/lyric-follower · docs/deployment-pipeline.md |
| iPad | Verificar el estado de instalación de Jamf y la aceptación del dispositivo por separado; la evidencia de lanzamiento y el alcance del objetivo son importantes | portal-ios · docs/JAMF.md, portal-ios · docs/DASHBOARD_INSTALL_VERIFICATION.md |
| Sitio privado de Documentos | Directorio de lanzamiento inmutable + enlace simbólico atómico; fallos de salud/inicio restauran el lanzamiento anterior | docs · tools/deploy-internal.sh |
Dónde buscar cuando algo sale mal
Los impactos esperados a continuación siguen el grafo de dependencia de implementación. Comience con la salud de solo lectura y el carril correspondiente; siga el libro de jugadas enlazado antes de reiniciar, reproducir, migrar o desplegar.
| Síntoma / dependencia | Evidencia y primeras comprobaciones | Libro de jugadas |
|---|---|---|
| Todas las llamadas a la API del personal fallan | Compare el ID de lanzamiento/solicitud, la actividad de Worker, luego la preparación del origen privado; la actividad por sí sola no demuestra la compatibilidad de SQL o de todos los adaptadores | portal-api · src/index.ts, portal-api · docs/OPERATIONS.md |
| Fallo de inicio de sesión/actualización | Distinga invalid_grant de 503 del origen; verifique el par adaptador/esquema y los orígenes de API/web configurados |
portal · dashboard/api/mobile/v1/token.php, portal · docs/PRODUCTION_API_SESSION_INCIDENT_2026-09-08.md, portal-ios · docs/AUTHENTICATION.md |
| Falla un recurso | Correlacione el ID de solicitud con los registros de origen, la migración y las comprobaciones de permisos específicas del recurso | portal · docs/PORTAL_OBSERVABILITY.md, portal-api · docs/REGRESSION-TESTING.md |
| Falla el socket de tickets | La invalidación/recuperación genérica es independiente de las recuperaciones autorizadas de tickets | portal-api · docs/TICKETS_LIVE.md, portal · docs/ticket-portal-live-updates.md |
| Falla la puerta de enlace de tareas | Identidad del portal y luego enlace/afirmación del servicio de Tareas; el rechazo de la afirmación es 502, no un fallo de token de usuario |
portal-api · src/index.ts, portal-api · docs/TASKS.md |
| Congelación de letras de canciones | Verifique las observaciones de ProPresenter/actualidad de la caché, el sondeo y el socket de forma independiente; el latido no son letras de canciones actualizadas | portal · lyrics/poll_propresenter.php, portal · lyrics/server.php, infra · portal/hosts/rocc-db/files/usr/local/sbin/riveroaks-lyrics-watchdog |
| Comunicaciones/pánico estancados | Verifique la procedencia del editor de rama/desplegado, el resultado de la ingesta, la antigüedad de la instantánea de RAM, la opción de socket y la recuperación REST; no copie el texto de la transcripción | portal · dashboard/api/mobile/v1/lib/comms.php, portal · lyrics/docs/comms-push.md, portal-ios · RiverOaksServiceDashboard/Models/DashboardModels.swift |
| Panel de iPad ausente | Pruebe la alimentación de red local configurada del panel; la autorización de red local, Wi-Fi/VPN y la actualidad son independientes del inicio de sesión del personal | portal-ios · docs/IPAD_SERVICE_DASHBOARD.md, portal-ios · docs/QSYS_ROOM_CONTROLS.md |
| Alertas/push ausentes | Política del editor/RBAC/preferencias, luego ingesta y worker APNs; la recuperación en primer plano y APNs son rutas separadas | portal · docs/mobile-alerts.md, infra · docs/alerting/qsys-portal-alerts.md, infra · docs/alerting/grafana-portal-adapter.md |
| Horario de captura faltante | Generación de feed, ruta/backend del portador, feed en caché y horario seleccionado de Mac | infrastructure/lyric-follower · docs/planning-center-recording-feed.md |
| Cola de línea de tiempo | Capacidad de cola local, mTLS/HMAC, preparación del colector y brecha de secuencia; conservar la reproducción ordenada | infrastructure/service-timeline · docs/runbook.md |
| Entrega de sermones atascada | Estado de la bandeja de salida/worker/destino; conservar la idempotencia y el comportamiento seguro del receptor del servicio | portal · docs/SERMON_WORKFLOW_ALERT_RECOVERY.md, portal · docs/SERMON_PROPRESENTER_LIVE_DEPLOYMENT.md |
| Archivos no disponibles | Origen/montaje de almacenamiento, contrato de entrega y worker de salud del almacenamiento | portal · docs/files-storage-reliability.md, infra · docs/runbooks/multitracks-files-delivery.md |
| Proveedor de secretos de origen no disponible | Recuperar a través del procedimiento de tiempo de ejecución con ámbito; no imprimir archivos de secretos de tiempo de ejecución | infra · docs/deploy/portal-openbao-runtime-recovery.md |
| Fallo de formulario/correo electrónico/enlace corto | Almacenamiento/cola/cuota/autenticación del Worker independiente; la salud de la API central aún puede pasar | cloudflare-forms · docs/OPERATIONS.md, cloudflare-email · docs/OPERATIONS.md, cloudflare-short-links · README.md |
| Documentos no publicados | Validación, luego traducción/compilación/Páginas, luego despliegue privado/trabajos de imagen; la publicación de imágenes no es una promoción de Flux | docs · .gitlab-ci.yml, docs · README.md, Alojamiento de Documentos |
Carril de lanzamiento de documentación
La CI de MR/rama ejecuta comprobaciones de retención de lanzamiento y mkdocs build --strict. El trabajo de traducción/compilación de Main publica Páginas y confirma hermanos en español generados;
el trabajo privado recupera main, recompila estrictamente, activa la versión estática inmutable y publica una imagen de registro privada. El digest de la imagen necesita una promoción de infraestructura separada; esta tarea de documentación no cambia el enrutamiento o las cargas de trabajo del clúster. Fuentes: docs · .gitlab-ci.yml,
docs · tools/commit-translations.sh, docs · tools/deploy-internal.sh,
docs · tools/publish-cluster-image.sh, docs · README.md.
No verificado en esta revisión
La inspección de la fuente no demuestra el enrutamiento del nombre de host en vivo, la versión en ejecución de una prueba de captura, la aceptación del dispositivo, la puesta en servicio del editor actual o el filtrado de sockets públicos. La distinción exacta entre fuente/despliegue y las contradicciones conocidas se registran en Instantáneas de origen.