El 3 de septiembre de 2026, GitHub Actions incorporó un permiso específico para un caso que antes solía empujar a los workflows hacia credenciales más amplias: vulnerability-alerts. Con vulnerability-alerts: read, el GITHUB_TOKEN puede listar y consultar alertas de Dependabot del propio repositorio sin recibir permisos de escritura y sin depender de un token personal solo para esa lectura. El cambio fue anunciado en el changelog oficial de GitHub.
El punto más importante es que el nuevo permiso es deliberadamente limitado: solo acepta read o none. Por eso encaja bien en jobs de inventario, triaje, generación de informes y gates que solo necesitan observar alertas. No convierte el GITHUB_TOKEN en una credencial capaz de descartar, reabrir o modificar alertas.
Qué cambió con vulnerability-alerts
La referencia de sintaxis de GitHub Actions ahora incluye vulnerability-alerts entre los permisos configurables del GITHUB_TOKEN. Según la documentación de workflow syntax, vulnerability-alerts: read permite que una acción liste alertas de Dependabot del repositorio; write no es un valor válido. La misma documentación indica que read-all y write-all incluyen este permiso como lectura, pero eso es más amplio de lo necesario para un job cuya única función es consultar alertas.
Otra regla ayuda a aplicar el principio de mínimo privilegio: cuando declaras acceso para cualquier permiso dentro de permissions, los permisos que no declares pasan a none. Por lo tanto, un job con solo vulnerability-alerts: read no recibe automáticamente contents: read, issues: write ni otros accesos. Si ese mismo job también hace checkout del repositorio, agrega únicamente el acceso que esa etapa realmente necesita.
Configuración mínima para solo leer alertas
Si el job no necesita descargar el código, la configuración puede ser mínima. El ejemplo siguiente usa GitHub CLI para llamar al endpoint de alertas del repositorio actual y expone el token únicamente al comando que realiza la consulta.
name: Read Dependabot alerts on: workflow_dispatch: jobs: alerts: runs-on: ubuntu-latest permissions: vulnerability-alerts: read steps: - name: List open alerts env: GH_TOKEN: ${{ github.token }} run: | gh api \ -H "X-GitHub-Api-Version: 2026-03-10" \ "repos/${{ github.repository }}/dependabot/alerts?state=open&per_page=100" \ --jq '.[] | { number, state, package: .dependency.package.name, severity: .security_advisory.severity, ghsa: .security_advisory.ghsa_id }'En este caso no hay motivo para conceder contents: read: el job no hace checkout ni lee archivos del repositorio mediante la API. Si necesitas combinar los alertas con datos del código, agrega solo el scope adicional imprescindible:
permissions: contents: read vulnerability-alerts: readPara documentar explícitamente que otro job no debe acceder a los alertas, vulnerability-alerts: none también es válido. En la práctica, resulta especialmente útil cuando quieres que el límite de seguridad sea evidente en el YAML; si ya declaraste otros permisos y omitiste vulnerability-alerts, este ya quedará en none.
Qué llamadas cubre el nuevo permiso
La API REST de alertas de Dependabot ofrece operaciones de lectura y actualización. Para automatizaciones con el nuevo permiso del GITHUB_TOKEN, la división práctica es:
| Operación | Endpoint | Con vulnerability-alerts: read |
|---|---|---|
| Listar alertas del repositorio | GET /repos/{owner}/{repo}/dependabot/alerts | Sí |
| Leer un alerta específico | GET /repos/{owner}/{repo}/dependabot/alerts/{alert_number} | Sí |
| Cambiar estado, descartar o reabrir | PATCH /repos/{owner}/{repo}/dependabot/alerts/{alert_number} | No |
El endpoint de actualización exige permiso de escritura para “Dependabot alerts” en credenciales que ofrecen ese nivel. Como vulnerability-alerts en el GITHUB_TOKEN solo admite read y none, un workflow configurado con el nuevo permiso debe tratarse como consumidor de datos, no como herramienta de administración de alertas. Si el proceso realmente necesita modificar alertas, usa una credencial adecuada, como una GitHub App con permiso granular de escritura, y mantén ese flujo separado del job de lectura.
Qué puedes extraer sin conceder acceso de escritura
La respuesta de la API incluye información suficiente para muchos flujos de triaje: número y estado del alerta, paquete y ecosistema, ruta del manifiesto, relación de la dependencia cuando está disponible, identificadores GHSA y CVE, severidad, versiones vulnerables, primera versión corregida cuando se conoce, CVSS y EPSS cuando se proporcionan. Con esto se pueden generar informes, crear gates internos o alimentar observabilidad sin dar al job autoridad para modificar el repositorio ni el propio alerta.
Conviene separar dos conceptos: “leer alertas” no es lo mismo que “leer código”. El acceso a alertas tiene su propio permiso. Si un script necesita inspeccionar package-lock.json, requirements.txt u otro archivo después de consultar la API, también necesitará contents: read u otra forma segura de recibir ese contenido.
El mínimo privilegio por job es mejor que por workflow completo
La clave permissions puede definirse en el nivel superior del workflow o dentro de un job. Para este caso, los permisos por job suelen ser más seguros. Solo el job de seguridad recibe vulnerability-alerts: read, mientras que build, pruebas y publicación siguen sin acceso a los alertas.
permissions: {} jobs: build: runs-on: ubuntu-latest permissions: contents: read vulnerability-alerts: none steps: - uses: actions/checkout@v6 - run: npm test security-report: runs-on: ubuntu-latest permissions: vulnerability-alerts: read steps: - name: Read alerts env: GH_TOKEN: ${{ github.token }} run: gh api "repos/${{ github.repository }}/dependabot/alerts?state=open"Esta separación también reduce el impacto de una acción de terceros comprometida. La guía de autenticación con GITHUB_TOKEN de GitHub recomienda limitar el token a los permisos mínimos necesarios porque las acciones pueden acceder a github.token incluso cuando el workflow no pasa el secreto explícitamente como input.
Reusable workflows: el llamador fija el techo
En los workflows reutilizables, el workflow llamado no puede recibir más permisos que los proporcionados por el llamador. La documentación de reusable workflows indica que los permisos del GITHUB_TOKEN solo pueden mantenerse iguales o reducirse a lo largo de la cadena de llamadas. Por lo tanto, si un workflow reutilizable necesita consultar alertas, el job llamador debe conceder vulnerability-alerts: read; el workflow llamado no puede elevar por sí solo un token que llegó con none.
jobs: audit: uses: org/security-workflows/.github/workflows/dependabot-audit.yml@v3 permissions: vulnerability-alerts: readEn una cadena A → B → C, trata el permiso como un techo descendente: si A no concede lectura, B y C no pueden recuperarla. Esto evita que un reusable workflow introduzca silenciosamente más acceso del que autorizó el repositorio llamador.
Forks y pull requests: la lectura también es privilegio
Los pull requests procedentes de forks reciben un GITHUB_TOKEN restringido y, en general, no reciben secretos. GitHub también trata los workflows activados por pull requests de Dependabot como si procedieran de un fork. Estas reglas están documentadas en eventos que activan workflows y en la documentación de Dependabot en GitHub Actions.
Que vulnerability-alerts sea de solo lectura no significa que sea seguro entregar esa lectura a código no confiable. Los alertas pueden revelar paquetes, versiones y vulnerabilidades presentes en el repositorio. Evita conceder este permiso a un job que hace checkout y ejecuta código controlado por el autor de un pull request externo. Una arquitectura más segura separa la consulta en un job o workflow confiable activado por workflow_dispatch, schedule, push a una rama protegida u otro evento que no ejecute contenido no confiable.
Si existe un motivo para usar pull_request_target, sigue la guía de seguridad específica de GitHub: mantén los permisos al mínimo y no hagas checkout ni ejecutes el head no confiable del pull request en un contexto privilegiado. El límite no es solo “escritura o no escritura”; evitar la filtración de datos de seguridad también forma parte del mínimo privilegio.
Errores comunes al adoptar el permiso
- Usar read-all por comodidad. Funciona para leer alertas, pero concede varios otros permisos de lectura. Prefiere solo vulnerability-alerts: read y los scopes adicionales que sean realmente necesarios.
- Agregar contents: read sin necesitarlo. Si el job solo llama a la API, ese permiso puede eliminarse.
- Intentar vulnerability-alerts: write. Ese valor no está soportado.
- Esperar que el nuevo scope permita descartar alertas. Las actualizaciones requieren permiso de escritura de Dependabot alerts y una credencial adecuada.
- Depender del valor predeterminado del repositorio. Define permissions en el YAML para que el contrato del job sea explícito y revisable.
- Olvidar que los reusable workflows no pueden elevar privilegios. El llamador debe conceder la lectura.
- Ejecutar código de forks en el mismo job que lee alertas. Incluso sin escritura, eso puede exponer información de seguridad.
Cómo investigar 403, 404 o una lista vacía
El endpoint de listado documenta respuestas como 403 y 404, pero esos códigos pueden tener más de una causa. Primero confirma en el workflow que el job realmente recibe vulnerability-alerts: read y que consulta repos/${{ github.repository }}/dependabot/alerts. Después verifica que Dependabot alerts esté habilitado para el repositorio y que el dependency graph esté disponible.
Una respuesta 200 con [] no es un fallo de permisos: puede que simplemente no haya alertas que coincidan con los filtros utilizados. Para depurar, elimina temporalmente filtros como state o severity y revisa el JSON bruto. En cambio, un 422 apunta a la validación de la solicitud, como parámetros incompatibles o no válidos.
Checklist de migración a mínimo privilegio
- Localiza workflows que usan PAT, GitHub App o read-all solo para consultar alertas de Dependabot.
- Mueve la lectura de alertas a un job dedicado cuando sea posible.
- Define vulnerability-alerts: read en el nivel de ese job.
- Agrega contents: read solo cuando se necesite checkout o acceso al contenido.
- Mantén las operaciones de actualización de alertas en un flujo separado con una credencial de escritura adecuada.
- Revisa los reusable workflows para confirmar que el llamador concede el permiso sin ampliar accesos no relacionados.
- No expongas la lectura de alertas a código de forks ni a otros inputs no confiables.
- Prueba GET /repos/{owner}/{repo}/dependabot/alerts y trata 403, 404, 422 y una lista vacía como casos distintos.
Para workflows que solo necesitan observar vulnerabilidades, el nuevo permiso cierra una brecha importante: ahora puedes usar el token efímero y limitado al repositorio de GitHub Actions para leer alertas de Dependabot bajo un contrato explícito de solo lectura. La mejora de seguridad depende menos de la nueva palabra del YAML y más de usarla en el menor alcance posible: en el job correcto, con triggers confiables y sin mezclar la visibilidad de alertas con capacidades de escritura innecesarias.
