From f59f8b3c9dabac6533e945ed097e1ebdf64f7218 Mon Sep 17 00:00:00 2001 From: Coatl <121911012+2-Coatl@users.noreply.github.com> Date: Tue, 18 Nov 2025 17:33:57 -0600 Subject: [PATCH 1/2] docs(workflows): especificar estrategia por ambiente --- .github/workflows/PLAN_CORRECCION.md | 59 ++++++++++++++++++++++ WORKFLOW_AUDIT.md | 74 ++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 .github/workflows/PLAN_CORRECCION.md create mode 100644 WORKFLOW_AUDIT.md diff --git a/.github/workflows/PLAN_CORRECCION.md b/.github/workflows/PLAN_CORRECCION.md new file mode 100644 index 00000000..c3d43188 --- /dev/null +++ b/.github/workflows/PLAN_CORRECCION.md @@ -0,0 +1,59 @@ +# Plan de corrección de workflows de GitHub Actions + +Este plan resume las acciones necesarias para corregir y optimizar los workflows bajo `.github/workflows/`, priorizando triggers completos (`push`, `pull_request`, `workflow_dispatch`), permisos mínimos, caching de dependencias, matrices de pruebas y controles de seguridad. + +## Principios generales +- **Triggers consistentes**: cada workflow debe soportar `push`, `pull_request` y `workflow_dispatch` salvo que exista una restricción explícita. +- **Permisos mínimos**: definir `permissions` explícitos a nivel de workflow con el mínimo necesario (p. ej., `contents: read`, `pull-requests: write` solo cuando aplique). +- **Caching**: habilitar `actions/cache` o cachés nativas (pip/npm) según el stack para reducir tiempos. +- **Matrices de pruebas**: cubrir versiones soportadas (Python 3.10-3.12, Node 18-20) y SO donde aplique. +- **Seguridad**: fijar versiones de acciones (SHA/digest cuando aplique), evitar secretos inline y añadir `concurrency` para evitar solapes. +- **Observabilidad**: añadir upload de artefactos y resultados (coverage, logs) cuando aporte valor al debug. + +## Estrategia por ambiente (producción, QA y desarrollo) +- **Workflows por entorno**: definir tres pipelines alineados a ramas y entornos (`main` → producción, `release/*` o `qa/*` → QA, `develop` → desarrollo). Cada pipeline debe heredar los principios generales anteriores. +- **Configuración diferenciada**: + - **Producción**: jobs protegidos con `environment: production`, `concurrency` por tag o ref, `required_reviewers`/`protection rules`, y despliegue mediante MCP/Codex; ejecución en `push` a `main` + `workflow_dispatch` con inputs para rollback. + - **QA**: `environment: qa` con despliegue a entornos de staging, tests extendidos (smoke + integración), matrices completas de versiones, y `concurrency` por rama de release; triggers en `push` a `qa/*` y `workflow_dispatch` para validaciones manuales. + - **Desarrollo**: `environment: development` orientado a feedback rápido (lint + unit + cobertura), caching agresivo y matrices mínimas; triggers en `push`/`pull_request` hacia `develop` y `workflow_dispatch` opcional. +- **Notificaciones**: usar comentarios en PR/commit status en lugar de Slack; habilitar `actions/github-script` para anotar fallos por entorno. +- **Variables y secretos**: centralizar variables comunes en `env` y secretos por entorno en `environment secrets`; validar su presencia con `if: env.SECRET != ''` antes de usarlos. +- **Plantillas reutilizables**: crear un workflow reusable (p. ej., `.github/workflows/reusable-ci.yml`) con matrices, caching y permisos mínimos, que reciba como inputs el entorno (`environment`), la rama y el modo (`deploy`/`validate`). + +## Acciones transversales +1. Añadir plantilla base reutilizable para permisos mínimos y estrategia de caching (composite o reusable workflow). +2. Incorporar `concurrency` para despliegue, incident-response y pipelines largos. +3. Revisar secretos: documentar requeridos y validar existencia antes de usarlos (ej. `if: env.SECRET != ''`). +4. Añadir validaciones de seguridad ligeras (Semgrep/Trivy) en ramas principales si no duplican CodeQL. +5. Documentar en README de workflows los triggers esperados y variables. + +## Acciones por workflow +- **actionlint.yml**: fijar digest del contenedor y añadir cache para dependencias de verificación si aplica. +- **agents-ci.yml**: añadir `permissions` mínimos; declarar `CODECOV_TOKEN` como `env` opcional con guardas; revisar que `bandit` falle en hallazgos críticos y habilitar cache pip. +- **backend-ci.yml**: agregar `workflow_dispatch`; definir permisos mínimos; usar secretos no triviales para MySQL y cerrar puerto con `ports: ["3306:3306"]` solo si es estrictamente necesario; cache pip y matiz de Python 3.10-3.12; añadir `concurrency` por ref. +- **code-quality.yml**: incluir `push` y `workflow_dispatch`; permisos mínimos; cache según herramienta (npm/pip); revisar matrices si hay múltiples linters. +- **codeql.yml**: agregar `workflow_dispatch`; permisos mínimos (`security-events: write`, `contents: read`); cache de dependencias del lenguaje y fijar versiones de `actions/checkout`/`setup-*` por SHA. +- **dependency-review.yml**: añadir `push` y `workflow_dispatch`; permisos mínimos (`contents: read`); documentar política de bloqueo. +- **deploy.yml**: habilitar `pull_request` (dry-run), permisos mínimos; reusar artefactos de build con checksum; cache de dependencias; añadir `concurrency` por entorno y validaciones previas. +- **docs-validation.yml**: sumar `workflow_dispatch`; permisos mínimos; cache pip y Sphinx; paralelizar validaciones si posible. +- **docs.yml**: incorporar cache de dependencias y `concurrency` por ref; revisar publicación segura (sin write innecesario). +- **emoji-validation.yml**: añadir `workflow_dispatch` y permisos mínimos; cache de dependencias y fijar versiones de acciones. +- **frontend-ci.yml**: agregar `workflow_dispatch` y permisos mínimos; cache npm/pnpm; matriz Node 18-20; considerar `concurrency` por ref. +- **incident-response.yml**: sumar `push`/`pull_request` si aplica; permisos mínimos; cache de herramientas; añadir `concurrency` para evitar ejecuciones paralelas. +- **infrastructure-ci.yml**: añadir `workflow_dispatch`; permisos mínimos; cache de proveedores/Terraform; proteger `terraform apply` con `environment`; validar backend remoto. +- **lint.yml**: agregar `workflow_dispatch`; permisos mínimos; cache de dependencias; fijar versiones de acciones. +- **meta-architecture-check.yml**: definir permisos mínimos; cache de dependencias; fijar versiones. +- **migrations.yml**: añadir `workflow_dispatch`; permisos mínimos; eliminar credenciales inline (`testpass`); cerrar puertos o usar servicios internos; cache pip; considerar matrices de DB si soportadas. +- **pr-review.yml**: evaluar añadir `push`/`pull_request` o mantener sólo comentario pero con filtro `if: github.event.issue.pull_request` para limitar; cache dependencias; revisar permisos mínimos. +- **python_ci.yml**: definir permisos mínimos; cache pip; añadir `concurrency`; ampliar matriz Python 3.10-3.12. +- **release.yml**: incluir `pull_request` (dry-run); permisos explícitos; verificar integridad de artefactos; cache dependencias; añadir `concurrency` por versión/tag. +- **requirements_index.yml**: añadir cache pip y matriz Python adicional; mantener permisos explícitos. +- **requirements_validate_traceability.yml**: definir permisos mínimos; cache pip; fijar acciones. +- **security-scan.yml**: sumar `workflow_dispatch`; permisos mínimos; cache cuando sea seguro; fijar versiones y limitar scope de escaneos. +- **sync-docs.yml**: agregar `push`/`pull_request`; permisos mínimos; validar PAT/SSH presentes; cache dependencias; añadir `concurrency`. +- **test-pyramid.yml**: añadir `workflow_dispatch`; permisos mínimos; cache pip; ampliar matriz Python; fijar acciones. +- **validate-guides.yml**: definir permisos mínimos; cache dependencias; fijar versiones de acciones. + +## Entregables +- PRs incrementales por workflow o por categoría (permisos, triggers, caching) para reducir riesgo. +- Documentación de cambios y secretos requeridos en cada PR. diff --git a/WORKFLOW_AUDIT.md b/WORKFLOW_AUDIT.md new file mode 100644 index 00000000..33874a4c --- /dev/null +++ b/WORKFLOW_AUDIT.md @@ -0,0 +1,74 @@ +# GitHub Actions Workflow Audit + +## Inventory +| Workflow | Triggers | Jobs | Cache (actions/cache) | Explicit permissions | +| --- | --- | ---: | :---: | :---: | +| actionlint.yml | push, pull_request, workflow_dispatch | 1 | No | Yes | +| agents-ci.yml | push, pull_request, workflow_dispatch | 7 | No | No | +| backend-ci.yml | push, pull_request | 6 | Yes | No | +| code-quality.yml | pull_request, workflow_dispatch | 1 | No | No | +| codeql.yml | push, pull_request, schedule | 1 | No | No | +| dependency-review.yml | pull_request | 1 | No | No | +| deploy.yml | push, workflow_dispatch | 7 | No | No | +| docs-validation.yml | pull_request, push | 6 | No | No | +| docs.yml | push, pull_request, workflow_dispatch | 3 | No | Yes | +| emoji-validation.yml | pull_request, push | 1 | No | No | +| frontend-ci.yml | push, pull_request | 8 | No | No | +| incident-response.yml | workflow_dispatch | 5 | No | No | +| infrastructure-ci.yml | push, pull_request | 7 | No | No | +| lint.yml | pull_request, push | 1 | No | No | +| meta-architecture-check.yml | pull_request, push, workflow_dispatch | 2 | No | No | +| migrations.yml | pull_request, push | 5 | No | No | +| pr-review.yml | issue_comment | 1 | No | Yes | +| python_ci.yml | push, pull_request, workflow_dispatch | 5 | No | No | +| release.yml | push, workflow_dispatch | 7 | No | Yes | +| requirements_index.yml | push, pull_request, workflow_dispatch | 1 | No | Yes | +| requirements_validate_traceability.yml | pull_request, push, workflow_dispatch | 1 | No | No | +| security-scan.yml | push, pull_request, schedule | 11 | No | No | +| sync-docs.yml | schedule, workflow_dispatch | 2 | No | No | +| test-pyramid.yml | push, pull_request, schedule | 3 | No | No | +| validate-guides.yml | pull_request, push, workflow_dispatch | 5 | No | No | + +## Quick findings +- Total workflows: 25. +- Workflows with `workflow_dispatch`: 13/25. +- Missing `workflow_dispatch`: backend-ci.yml, codeql.yml, dependency-review.yml, docs-validation.yml, emoji-validation.yml, frontend-ci.yml, infrastructure-ci.yml, lint.yml, migrations.yml, pr-review.yml, security-scan.yml, test-pyramid.yml +- Missing `push` trigger: code-quality.yml, dependency-review.yml, incident-response.yml, pr-review.yml, sync-docs.yml +- Missing `pull_request` trigger: deploy.yml, incident-response.yml, pr-review.yml, release.yml, sync-docs.yml +- Lacking explicit top-level `permissions`: agents-ci.yml, backend-ci.yml, code-quality.yml, codeql.yml, dependency-review.yml, deploy.yml, docs-validation.yml, emoji-validation.yml, frontend-ci.yml, incident-response.yml, infrastructure-ci.yml, lint.yml, meta-architecture-check.yml, migrations.yml, python_ci.yml, requirements_validate_traceability.yml, security-scan.yml, sync-docs.yml, test-pyramid.yml, validate-guides.yml +- Workflows without `actions/cache`: actionlint.yml, agents-ci.yml, code-quality.yml, codeql.yml, dependency-review.yml, deploy.yml, docs-validation.yml, docs.yml, emoji-validation.yml, frontend-ci.yml, incident-response.yml, infrastructure-ci.yml, lint.yml, meta-architecture-check.yml, migrations.yml, pr-review.yml, python_ci.yml, release.yml, requirements_index.yml, requirements_validate_traceability.yml, security-scan.yml, sync-docs.yml, test-pyramid.yml, validate-guides.yml + +## Recommendations +- Add `workflow_dispatch` to workflows that currently only run on PR/push to enable manual runs during incidents or hotfix validation. +- Define explicit, least-privilege `permissions` blocks to avoid default write scopes (e.g., contents: read, pull-requests: write only where needed). +- Introduce dependency caching where missing (pip, npm, etc.) to speed up jobs; most workflows reinstall dependencies from scratch. +- Expand test matrices for Python/Node where appropriate (e.g., backend/agents run single Python 3.11, frontend fixed to Node 18). +- Consider a lightweight security gate (e.g., Semgrep or Trivy) on push to main/develop to complement existing CodeQL and security scans. +- Add concurrency keys to long-running workflows (deploy, incident-response) to prevent overlapping runs per ref/environment. + +## Per-workflow issues and gaps +- **actionlint.yml**: Uses explicit permissions and manual trigger is present, but there is no caching and the Docker action is not pinned to a digest. +- **agents-ci.yml**: Lacks an explicit permissions block, requires `CODECOV_TOKEN` to run coverage uploads, and the Bandit step ignores findings by design (`|| true`). +- **backend-ci.yml**: Missing `workflow_dispatch`; no permissions block; database service uses default MySQL root credentials and exposes 3306. +- **code-quality.yml**: Only runs on `pull_request` and `workflow_dispatch` is absent; no explicit permissions; no dependency caching. +- **codeql.yml**: Lacks `workflow_dispatch`; permissions not explicitly narrowed for code scanning upload; no cache for Python setup. +- **dependency-review.yml**: Only trigger is `pull_request`; no manual trigger; permissions block present but default read/write not narrowed to minimal contents/read. +- **deploy.yml**: Does not run on `pull_request`; no permissions block; re-runs full test suite without caching, slowing deployments. +- **docs-validation.yml**: Missing `workflow_dispatch` and explicit permissions; no caching for Python or Sphinx deps. +- **docs.yml**: Triggers are complete and permissions are explicit, but there is no dependency cache and no concurrency control for doc publishes. +- **emoji-validation.yml**: Missing manual trigger; no permissions block; re-installs dependencies every run. +- **frontend-ci.yml**: Missing `workflow_dispatch`; no permissions block; npm/node dependencies are not cached and only Node 18 is covered. +- **incident-response.yml**: Manual-only trigger with no `push`/`pull_request`; lacking permissions block and dependency caching. +- **infrastructure-ci.yml**: Missing `workflow_dispatch` and permissions block; Terraform steps lack a backend/cache and may need environment protection. +- **lint.yml**: Missing `workflow_dispatch` and permissions block; no caching for lint dependencies. +- **meta-architecture-check.yml**: Triggers present, but no permissions block and no dependency caching. +- **migrations.yml**: Missing `workflow_dispatch`; no permissions block; seeds data with inline secrets (`testpass`) and exposes MySQL port 3306. +- **pr-review.yml**: Triggered only by `issue_comment` with no `push`/`pull_request`; permissions are constrained but there is no validation to limit to PR comments; no caching. +- **python_ci.yml**: Triggers present but lacks permissions block; no cache for Python dependencies and no concurrency control. +- **release.yml**: No `pull_request` trigger; permissions rely on defaults; reuses build artifacts without checksum verification. +- **requirements_index.yml**: Triggers present and permissions explicit, but there is no cache and the Python job runs only on a single version. +- **requirements_validate_traceability.yml**: Triggers present but no permissions block; no dependency caching. +- **security-scan.yml**: Missing `workflow_dispatch` and permissions block; no caching and uses broad third-party actions without digests. +- **sync-docs.yml**: Missing `push`/`pull_request` triggers; no permissions block; relies on PAT/SSH secrets without validation and lacks caching. +- **test-pyramid.yml**: Missing `workflow_dispatch`; no permissions block; Python jobs reuse `pip install` without cache and matrix lacks latest versions. +- **validate-guides.yml**: Triggers are complete, but permissions are not explicit and there is no dependency caching. From ab9c255f6056293f26c9e019e9da4c1735ae5452 Mon Sep 17 00:00:00 2001 From: Nestor Monroy <46802445+NestorMonroy@users.noreply.github.com> Date: Tue, 18 Nov 2025 17:43:52 -0600 Subject: [PATCH 2/2] Update .github/workflows/PLAN_CORRECCION.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/workflows/PLAN_CORRECCION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/PLAN_CORRECCION.md b/.github/workflows/PLAN_CORRECCION.md index c3d43188..f5b16bd6 100644 --- a/.github/workflows/PLAN_CORRECCION.md +++ b/.github/workflows/PLAN_CORRECCION.md @@ -30,7 +30,7 @@ Este plan resume las acciones necesarias para corregir y optimizar los workflows ## Acciones por workflow - **actionlint.yml**: fijar digest del contenedor y añadir cache para dependencias de verificación si aplica. - **agents-ci.yml**: añadir `permissions` mínimos; declarar `CODECOV_TOKEN` como `env` opcional con guardas; revisar que `bandit` falle en hallazgos críticos y habilitar cache pip. -- **backend-ci.yml**: agregar `workflow_dispatch`; definir permisos mínimos; usar secretos no triviales para MySQL y cerrar puerto con `ports: ["3306:3306"]` solo si es estrictamente necesario; cache pip y matiz de Python 3.10-3.12; añadir `concurrency` por ref. +- **backend-ci.yml**: agregar `workflow_dispatch`; definir permisos mínimos; usar secretos no triviales para MySQL y cerrar puerto con `ports: ["3306:3306"]` solo si es estrictamente necesario; cache pip y matriz de Python 3.10-3.12; añadir `concurrency` por ref. - **code-quality.yml**: incluir `push` y `workflow_dispatch`; permisos mínimos; cache según herramienta (npm/pip); revisar matrices si hay múltiples linters. - **codeql.yml**: agregar `workflow_dispatch`; permisos mínimos (`security-events: write`, `contents: read`); cache de dependencias del lenguaje y fijar versiones de `actions/checkout`/`setup-*` por SHA. - **dependency-review.yml**: añadir `push` y `workflow_dispatch`; permisos mínimos (`contents: read`); documentar política de bloqueo.