Controles de calidad en GitHub Actions: configuraciones para 10 stacks
Matt · · Última actualización · 13 min de lectura · Guías
Controles de calidad para GitHub Actions en 10 stacks, listos para copiar: pruebas, mínimo de cobertura, SBOM, licencias y secretos, con el ajuste equivalente en AI CodeOps.
En esta página
Un control de calidad en GitHub Actions es un job que hace fallar el pull request cuando no se cumple una regla, convertido en comprobación obligatoria para que el botón de fusión siga bloqueado hasta que se supere. Las recetas de abajo dan a diez stacks los mismos cinco controles: pruebas, un mínimo de cobertura, un SBOM CycloneDX, una política de licencias y un escaneo de secretos, cada uno con su ajuste equivalente en AI CodeOps. Copia una vez los jobs compartidos, añade el job de pruebas de tu stack y exige las comprobaciones.
Qué necesita un control de fusión
Cuando los agentes de IA abren pull requests, la revisión deja de ser el cuello de botella y pasa a ser el punto débil. Un equipo que revisaba cinco cambios al día ahora puede recibir cincuenta. Las personas se cansan. Un control, no. Cada receta de este artículo bloquea un pull request por cinco motivos:
- Pruebas. La suite tiene que pasar.
- Un mínimo de cobertura. Una cobertura de líneas por debajo del mínimo hace fallar el control. Todas las recetas usan 80%; elige el tuyo.
- Un SBOM. Para cada cambio se genera un SBOM CycloneDX que se guarda como artefacto. Si está vacío, falla.
- Una política de licencias. Falla un pull request que añade una dependencia con una licencia que no has permitido.
- Un escaneo de secretos. Falla si un commit del cambio contiene un secreto.
Los hallazgos de gravedad alta también bloquean: el job de licencias falla ante vulnerabilidades conocidas en las dependencias nuevas y, en los cambios de AI CodeOps, el control de publicación bloquea si hay hallazgos abiertos.
Son flujos de trabajo normales. No dependen de ningún producto, ni siquiera del nuestro. Cada versión de action y cada input de abajo se comprobó con el README de esa action el 24 de octubre de 2026, y los mínimos de Node y Go se ejecutaron en local por encima y por debajo del umbral. Aun así, ejecuta cada uno en una rama antes de convertirlo en comprobación obligatoria. La guía de controles de calidad explica qué es un control y cómo diseñarlo; este artículo son las configuraciones.
Dos reglas detrás de cada receta
Fallar en cerrado (fail closed). Un control que no puede ejecutarse debe fallar, no pasar. No hay ningún continue-on-error ni ningún || true en estos archivos. Si la herramienta de SBOM no encuentra nada, el job falla. Si no se puede leer la cifra de cobertura, el job falla.
Mantén el mínimo en el flujo de trabajo. La mayoría de las herramientas te dejan fijar un umbral de cobertura en un archivo de configuración: vitest.config.ts, pyproject.toml, .coveragerc. Ese archivo vive junto al código, así que el cambio que baja la cobertura puede bajar el mínimo en el mismo diff. Un agente de IA al que se le pide «haz que pase la CI» a veces hace exactamente eso. Cuando una herramienta tiene un flag de línea de comandos o una variable de entorno, estas recetas fijan ahí el mínimo, en .github/workflows/. Después añade .github/ a CODEOWNERS, para que cambiar un control requiera la revisión de un propietario.
Los tres jobs compartidos
Secretos, SBOM y licencias son iguales en todos los stacks, así que aquí aparecen una sola vez. Cada receta termina con estos tres jobs, sin cambios.
secrets:
name: Secrets scan
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
persist-credentials: false
- name: gitleaks
env:
RANGE: ${{ github.event_name == 'pull_request' && format('{0}..{1}', github.event.pull_request.base.sha, github.event.pull_request.head.sha) || format('{0}..{1}', github.event.before, github.sha) }}
run: >-
docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:v8.30.1
git /repo --redact --verbose --log-opts="$RANGE"
sbom:
name: SBOM (CycloneDX)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: anchore/sbom-action@v0
with:
path: .
format: cyclonedx-json
output-file: sbom.cdx.json
upload-artifact: false
- name: The SBOM lists components
run: jq -e '(.components // []) | length > 0' sbom.cdx.json
- uses: actions/upload-artifact@v7
with:
name: sbom-cyclonedx
path: sbom.cdx.json
licenses:
name: License policy
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: actions/dependency-review-action@v5
with:
config-file: ./.github/dependency-review-config.yml
Algunas de estas decisiones merecen una explicación.
Gitleaks desde su imagen, no desde su action. El binario de gitleaks tiene licencia MIT y no necesita clave. La GitHub Action de gitleaks pide una clave de licencia a las organizaciones. Ejecutar la imagen oficial, fijada a una versión, evita la clave y deja la versión bajo tu control. El escaneo cubre solo los commits que añade el cambio, desde la base del pull request hasta su cabecera, así que una fuga antigua en otro punto del historial no bloquea el cambio de hoy. Pon un .gitleaks.toml en la raíz del repositorio para ajustar las reglas; la imagen lo detecta.
Syft para todos los SBOM. anchore/sbom-action ejecuta Syft sobre el checkout y escribe JSON CycloneDX. Syft lee los lockfiles de todos los stacks de este artículo: package-lock.json, requirements.txt, go.sum, Gemfile.lock, pom.xml, packages.lock.json y Cargo.lock. El paso jq -e hace fallar el job cuando el SBOM no tiene componentes, lo que significa que no se encontró ningún lockfile. Un SBOM vacío que pasa es peor que no tener ninguno.
Dependency review para las licencias. compara el pull request con su base y falla ante cualquier dependencia nueva cuya licencia no esté en tu lista. Conviene saber tres cosas. Necesita el gráfico de dependencias de GitHub, que está activado en los repositorios públicos y requiere GitHub Advanced Security en los privados. Comprueba las dependencias que el pull request añade o cambia, no las que ya estaban. Y si no puede detectar una licencia, lo indica pero no falla.
La lista de licencias está en .github/dependency-review-config.yml:
allow-licenses:
- MIT
- Apache-2.0
- BSD-2-Clause
- BSD-3-Clause
- ISC
- 0BSD
- Zlib
- Unlicense
- CC0-1.0
- BlueOak-1.0.0
- Python-2.0
- MPL-2.0
fail-on-severity: high
Es una lista de permitidas a propósito. La opción deny-licenses de la action está obsoleta, y una lista de denegadas deja pasar cualquier licencia en la que no hayas pensado. La lista de arriba es un ejemplo de política permisiva, no asesoramiento legal. La misma action también falla ante vulnerabilidades conocidas en las dependencias nuevas; fail-on-severity: high fija ese umbral.
Todos los flujos de trabajo empiezan igual: se ejecutan en pull_request y en los push a main, con permissions: contents: read y nada más.
Los diez stacks
Cada stack de abajo muestra solo los pasos de su job tests. Ponlos bajo jobs.tests.steps, da al job name: Tests and coverage floor, añade los tres jobs compartidos y tendrás el flujo de trabajo completo. Todos los jobs tests empiezan con el mismo paso de checkout, que se muestra una sola vez, en la primera receta.
Cada stack tiene además un ajuste en AI CodeOps. Una sesión de AI CodeOps ejecuta el Test command de tu proyecto (se fija en el proyecto, en Plan → Projects) sobre su cambio en un sandbox y registra el resultado, y después el control de publicación de tu CI puede exigir minCoveragePct: 80. La sesión solo registra la cobertura cuando el comando imprime un resumen que AI CodeOps sabe leer: una línea TOTAL de pytest-cov o coverage.py, una tabla All files de Vitest, Jest o el test runner de Node, o una línea Coverage: 85%. Se guarda como número entero, redondeado hacia abajo, así que un 79.6% no supera un mínimo de 80. Una ejecución sin resumen de cobertura no se puede comprobar contra un mínimo, así que el control de publicación la deniega cuando minCoveragePct está fijado. Comprueba que la página de la ejecución muestra una cifra de cobertura antes de añadir el mínimo.
Next.js
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
- run: npm ci
- run: npx vitest run --coverage.enabled --coverage.thresholds.lines=80
- run: npm run build
Vitest es el test runner unitario que configura la documentación de Next.js. Añade @vitest/coverage-v8 a las dependencias de desarrollo que enumera la guía. next build también comprueba los tipos. Vitest no ejecuta los Server Components async, así que esos necesitan pruebas de extremo a extremo y no cuentan para este mínimo.
Ajuste en AI CodeOps: Test command npx vitest run --coverage.enabled --coverage.thresholds.lines=80. El reporter de texto de Vitest imprime la tabla All files, y AI CodeOps toma su primera columna, que es la de sentencias, no la de líneas.
Node.js
- run: npm ci
- run: node --test --experimental-test-coverage --test-coverage-lines=80
El test runner integrado de Node tiene un flag de mínimo desde Node 22.8. Por debajo del mínimo, la ejecución sale con código 1 y una línea como Error: 53.85% line coverage does not meet threshold of 80%. La cobertura del runner sigue marcada como experimental. El checkout y setup-node son como en Next.js.
Ajuste en AI CodeOps: Test command node --test --experimental-test-coverage --test-coverage-lines=80. El informe del runner termina con una fila all files, que AI CodeOps lee.
Python / Django
- uses: actions/setup-python@v7
with:
python-version: "3.13"
cache: pip
- run: pip install -r requirements.txt coverage
- run: python manage.py makemigrations --check --dry-run
- run: coverage run --source=. manage.py test
- run: coverage report --fail-under=80
La comprobación de migraciones falla cuando un modelo cambió sin su migración, un paso que un agente olvida con facilidad. Pon las reglas omit para las migraciones y los settings en .coveragerc, pero mantén --fail-under en la línea de comandos.
Ajuste en AI CodeOps: Test command coverage run --source=. manage.py test && coverage report --fail-under=80. La línea TOTAL del informe lleva el porcentaje.
FastAPI
- run: pip install -r requirements.txt -r requirements-dev.txt
- run: pytest --cov=app --cov-report=term-missing --cov-fail-under=80
Configura Python como en Django. requirements-dev.txt contiene pytest, pytest-cov y httpx, que necesita el TestClient de FastAPI. Cambia --cov=app por tu paquete.
Ajuste en AI CodeOps: Test command pytest --cov=app --cov-fail-under=80. La línea TOTAL de pytest-cov lleva el porcentaje.
Go
- uses: actions/setup-go@v7
with:
go-version-file: go.mod
- run: go vet ./...
- run: go test -race -coverprofile=coverage.out ./...
- name: 80% statement coverage floor
run: |
total=$(go tool cover -func=coverage.out | awk '/^total:/ { sub("%", "", $3); print $3 }')
echo "Total coverage: ${total:-none}%"
awk -v t="$total" 'BEGIN { exit !(t != "" && t + 0 >= 80) }' || { echo "::error::Coverage ${total:-none}% is below the 80% floor"; exit 1; }
go test no tiene flag de mínimo, así que el paso lee la línea total: y la compara. En un módulo de prueba pequeño con un 33.3% de cobertura, falla con 80 y pasa con 30. Un total vacío también falla, así que no se cuela un paso de pruebas que no escribió ningún perfil.
Ajuste en AI CodeOps: Test command go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out. go tool cover -func termina con una línea total:, que AI CodeOps lee igual que una línea TOTAL.
Ruby on Rails
- uses: ruby/setup-ruby@v1
with:
bundler-cache: true
- run: bin/rails db:prepare
env:
RAILS_ENV: test
- run: bin/rails test
env:
RAILS_ENV: test
PARALLEL_WORKERS: "1"
COVERAGE_MIN: "80"
Al principio de todo de test/test_helper.rb:
require "simplecov"
SimpleCov.start "rails" do
minimum_coverage Integer(ENV.fetch("COVERAGE_MIN", "80"))
end
SimpleCov no admite el mínimo en la línea de comandos, así que el flujo de trabajo se lo pasa en una variable de entorno. Un único worker mantiene la suite en un solo proceso, para que SimpleCov la vea entera.
Ajuste en AI CodeOps: Test command bin/rails test, con COVERAGE_MIN fijado como arriba. Al final de la ejecución, SimpleCov imprime una línea del estilo Line Coverage: 85.0%.
Java / Spring Boot (Maven)
- uses: actions/setup-java@v6
with:
distribution: temurin
java-version: "21"
cache: maven
- run: ./mvnw -B verify -Dcoverage.minimum=0.80
Añade jacoco-maven-plugin 0.8.15 a pom.xml con los goals prepare-agent, report y check, y una regla BUNDLE sobre LINE COVEREDRATIO con <minimum>${coverage.minimum}</minimum>. check se vincula a verify, así que el build falla por debajo del mínimo. En Gradle, el gráfico de dependencias de GitHub solo ve el build mediante el envío de dependencias (dependency submission), así que configúralo antes de fiarte de la comprobación de licencias.
Ajuste en AI CodeOps: JaCoCo escribe su informe en archivos, no en la consola, así que la ejecución de una sesión registra si pasa o falla, pero no la cobertura. Mantén el mínimo en el build de Maven, que fallará por debajo de él en cualquier caso. Deja minCoveragePct fuera de la llamada al control de publicación en este stack: sin cobertura registrada, el control denegaría todos los cambios.
.NET
- uses: actions/setup-dotnet@v6
with:
dotnet-version: "10.0.x"
- run: dotnet restore --locked-mode
- run: dotnet test --no-restore /p:CollectCoverage=true /p:Threshold=80 /p:ThresholdType=line /p:ThresholdStat=total
Añade coverlet.msbuild a cada proyecto de pruebas y pon RestorePackagesWithLockFile a true, para que haya archivos packages.lock.json para --locked-mode y para Syft. ThresholdStat=total comprueba la solución entera en lugar de cada módulo. Un detalle: coverlet.msbuild funciona con VSTest, el predeterminado, y no recoge nada con Microsoft.Testing.Platform. Si tu global.json activa esa plataforma, usa su propia extensión de cobertura.
Ajuste en AI CodeOps: igual que con JaCoCo, confía en el Threshold del propio build para hacer fallar la ejecución; mira la página de la ejecución de la sesión antes de fijar también minCoveragePct.
Rust
- run: rustup update stable
- uses: taiki-e/install-action@cargo-llvm-cov
- run: cargo clippy --all-targets --all-features -- -D warnings
- run: cargo llvm-cov --all-features --workspace --fail-under-lines 80
Es la configuración que usa el propio ejemplo de CI de cargo-llvm-cov, más el flag del mínimo. Haz commit de Cargo.lock, también en las bibliotecas, para que el SBOM y la comprobación de licencias vean las versiones exactas.
Ajuste en AI CodeOps: Test command cargo llvm-cov --workspace --fail-under-lines 80. El flag hace fallar la ejecución por debajo del mínimo; mira en la página de la ejecución qué porcentaje registró la sesión antes de fijar también minCoveragePct.
Monorepo
Un monorepo necesita una idea más. No quieres ejecutar las pruebas de todos los paquetes en cada cambio, así que filtras por ruta. Pero GitHub da por correcto un job omitido por su if, aunque sea una comprobación obligatoria. Si web es obligatoria y falla el job que decide si se ejecuta, web se omite y el pull request pasa.
La solución es un último job que se ejecuta siempre y lee todos los resultados:
changes:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
outputs:
web: ${{ steps.filter.outputs.web }}
api: ${{ steps.filter.outputs.api }}
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: dorny/paths-filter@v4
id: filter
with:
filters: |
web:
- 'apps/web/**'
- 'package-lock.json'
api:
- 'services/api/**'
# web and api: the Next.js and FastAPI test steps above, each with
# needs: changes and if: needs.changes.outputs.<name> == 'true'
gate:
name: Quality gates
if: always()
needs: [changes, web, api, secrets, sbom, licenses]
runs-on: ubuntu-latest
steps:
- env:
RESULTS: ${{ toJSON(needs.*.result) }}
run: |
echo "$RESULTS"
if echo "$RESULTS" | grep -Eq '"(failure|cancelled)"'; then exit 1; fi
Exige solo Quality gates. Ahora una omisión solo pasa cuando el filtro dijo que ese paquete no cambió. Secretos, SBOM y licencias siguen ejecutándose en cada cambio, sobre todo el repositorio, y Syft encuentra el lockfile de cada paquete.
Ajuste en AI CodeOps: un monorepo suele necesitar un Test command propio, como un script que ejecute los paquetes que toca un cambio. Fíjalo en el proyecto; la detección automática solo busca un script de pruebas en package.json, pytest o Go en la raíz.
Convertirlos en comprobaciones obligatorias
Un flujo de trabajo que falla no impide por sí solo una fusión. GitHub solo bloquea el botón de fusión con las comprobaciones que marcas como obligatorias: en la protección de ramas, «todas las comprobaciones de estado obligatorias deben superarse antes de que los colaboradores puedan fusionar cambios en la rama protegida» (About protected branches, comprobado el 24 de octubre de 2026). La misma página incluye skipped entre los estados que satisfacen una comprobación obligatoria, y por eso la receta del monorepo termina en un job que se ejecuta siempre.
- Exige las comprobaciones. En la protección de ramas o en un ruleset de la rama predeterminada, exige Tests and coverage floor, Secrets scan, SBOM (CycloneDX) y License policy, o Quality gates en el monorepo. Una comprobación solo aparece en el selector después de ejecutarse una vez, así que abre antes un pull request de prueba. Rulesets de GitHub para agentes de IA explica paso a paso el ruleset en sí.
- Protege los controles. CODEOWNERS en
.github/, con la revisión de los code owners obligatoria. Un cambio en un control es un cambio en tu política. - Fija más si lo necesitas. Estas recetas fijan cada action a su versión mayor actual. Para una higiene más estricta de la cadena de suministro, fija cada una a un SHA de commit completo y deja que Dependabot las actualice.
- Rompe cada control una vez. Borra una prueba, añade una dependencia GPL, haz commit de una clave falsa. Comprueba que cada job se pone en rojo antes de fiarte de su verde.
La variante de AI CodeOps
AI CodeOps tiene su propio control de publicación. No lee ningún archivo de configuración de tu repositorio. Tu CI le hace una pregunta por la API, y responde a partir de todas las sesiones de AI CodeOps que tocaron el cambio: hallazgos abiertos, la ejecución de pruebas y la cobertura de la propia sesión, las licencias del SBOM del proyecto y cualquier flujo de trabajo o promoción obligatorios.
release-gate:
if: startsWith(github.head_ref, 'codeops/run-')
runs-on: ubuntu-latest
steps:
- env:
AICODEOPS_API_KEY: ${{ secrets.AICODEOPS_API_KEY }}
PR_URL: ${{ github.event.pull_request.html_url }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: |
body=$(jq -n --arg pr "$PR_URL" --arg sha "$HEAD_SHA" \
'{pullRequestURL: $pr, commitSHA: $sha, blockingSeverity: "high", minCoveragePct: 80}')
response=$(curl -sS --fail --retry 3 --max-time 30 -X POST \
"https://console.aicodeops.dev/api/release/check" \
-H "Authorization: Bearer $AICODEOPS_API_KEY" \
-H "Content-Type: application/json" -d "$body") \
|| { echo "Release check unavailable: failing closed"; exit 1; }
[ "$(echo "$response" | jq -r '.allowed')" = "true" ] \
|| { echo "$response" | jq -r '.summary, (.reasons // [])[]'; exit 1; }
El if importa. AI CodeOps abre sus pull requests desde ramas codeops/run-<id>, y el control deniega un cambio sin sesiones de AI CodeOps, así que ejecutarlo en el pull request de una persona fallaría siempre. El endpoint devuelve HTTP 200 tanto si permite como si deniega, así que el paso lee allowed. Los campos están en la página de la API.
Una advertencia sobre minCoveragePct: deniega un cambio cuya ejecución de pruebas no informó de cobertura, porque un mínimo que no se puede comprobar no se supera. Si tu stack es de los que no dejan registrada la cobertura en la sesión, como JaCoCo más arriba, quita ese campo del cuerpo.
Dos advertencias si añades disallowedLicenses. La coincidencia es exacta, así que GPL-3.0 no coincide con GPL-3.0-only: enumera todas las grafías que usen tus SBOM. Y la comprobación lee el SBOM registrado para el proyecto en AI CodeOps. Con una regla de licencias fijada y sin SBOM registrado, el control deniega, porque no puede comprobarlo.
La otra mitad es la política del espacio de trabajo. Estas reglas hacen que cualquier cambio de la IA en los archivos que definen tus controles espere a una revisión aprobada:
[
{ "id": "review-ci-definitions", "action": "diff.apply", "resource": ".github/**", "decision": "ask" },
{ "id": "review-secret-scan-config", "action": "diff.apply", "resource": ".gitleaks.toml", "decision": "ask" },
{ "id": "review-vitest-config", "action": "diff.apply", "resource": "**vitest.config.*", "decision": "ask" }
]
** atraviesa carpetas y * se queda dentro de una, así que **vitest.config.* coincide con la configuración de la raíz y con la de cada paquete. Usa las dos mitades además de los controles normales, no en su lugar. Si prefieres partir de un flujo de trabajo completo, las plantillas incluyen un mínimo de cobertura para Python y un control de licencias sobre el SBOM.
¿Falta tu stack?
PHP, Elixir, Kotlin con Gradle y Swift son los huecos evidentes. Publicaremos las diez recetas como un repositorio con licencia MIT, y nos gustaría tener más. Si usas uno de estos stacks, aporta una receta. Necesita como prueba una ejecución en verde y otra en rojo, y aparecerás citado con un enlace.
Las reglas que aplica cada control del lado de AI CodeOps, y cómo pasar por triaje un cambio bloqueado, están en la documentación de controles de calidad.
Puntos clave
- Un control solo bloquea una fusión cuando es una comprobación obligatoria; un flujo de trabajo en rojo, por sí solo, es un consejo.
- Fallar en cerrado: nada de
continue-on-error, nada de|| true, y un SBOM vacío o una cifra de cobertura ilegible hacen fallar el control. - Mantén el mínimo de cobertura en el flujo de trabajo y pon
.github/bajo CODEOWNERS, para que el cambio que baja la cobertura no pueda bajar también el mínimo. - En un monorepo, exige un último job que lea todos los resultados, porque un job omitido cuenta como superado.
- AI CodeOps registra la cobertura de una sesión como número entero redondeado hacia abajo, así que un 79.6% no supera un mínimo de 80.