El 10 de septiembre de 2026, GitHub abrió un public preview de APIs REST para administrar AI Scan en pull requests a nivel de organización y repositorio. Las nuevas APIs son útiles para equipos que quieren activar o desactivar el análisis de forma programática, en lugar de repetir la misma configuración manualmente en la interfaz. El punto más importante es la jerarquía: un repositorio puede ajustar su propia participación, pero no puede habilitar la función cuando una capa superior la bloquea.
Según el anuncio oficial de GitHub, los endpoints son /orgs/{org}/code-scanning/ai-scan y /repos/{owner}/{repo}/code-scanning/ai-scan. La documentación deja claro que estos endpoints continúan en public preview y pueden cambiar.
Qué debe estar listo antes de llamar a la API
Habilitar el parámetro pr_scan mediante la API no elimina los requisitos previos del producto. En el preview actual, AI Scan depende de una combinación de política, licencias y configuración de code scanning.
- Entorno: el preview fue anunciado para github.com. GitHub Enterprise Server no es compatible con esta versión.
- Licencias: las detecciones de seguridad con IA requieren GitHub Advanced Security y, durante el public preview, también una licencia de GitHub Copilot.
- Créditos de IA: el uso consume AI credits, según la documentación de la función.
- Política enterprise: un administrador enterprise debe permitir AI Findings. Si la empresa bloquea la función, la organización no puede habilitarla.
- Opt-in de la organización: la organización debe habilitar las detecciones con IA antes de que los repositorios puedan usarlas.
- CodeQL default setup: el repositorio debe tener habilitado CodeQL default setup. Es un requisito de elegibilidad aunque la ejecución de AI Scan sea independiente del estado de una ejecución específica de CodeQL.
La referencia conceptual de GitHub sobre AI-powered security detections es la mejor fuente para verificar estos requisitos porque también documenta los límites operativos del preview.
Organización vs. repositorio: endpoints, permisos y efecto
| Ámbito | Endpoint | Lectura | Actualización | Efecto práctico |
|---|---|---|---|---|
| Organización | /orgs/{org}/code-scanning/ai-scan | Fine-grained: Administration de la organización (read). El usuario autenticado debe ser owner o security manager. | Fine-grained: Administration de la organización (write). | Define si los repositorios de la organización pueden usar AI Scan. Si está deshabilitado, un repositorio no puede eludir el bloqueo. |
| Repositorio | /repos/{owner}/{repo}/code-scanning/ai-scan | Fine-grained: Code scanning alerts del repositorio (read). | Fine-grained: Administration del repositorio (write). | Permite habilitar o deshabilitar AI Scan para ese repositorio cuando la organización y la política enterprise lo permiten. |
Los requisitos para tokens clásicos cambian según el endpoint. A nivel de organización, la documentación acepta scopes como admin:org, repo o write:org, según el rol del usuario. En el repositorio, la lectura requiere security_events para repositorios privados o públicos, mientras que la actualización requiere repo; para operaciones limitadas a repositorios públicos, public_repo puede ser suficiente. Antes de automatizar, consulta los detalles en la página de la API de organización y en la API de code scanning del repositorio.
Cómo funciona la precedencia de configuración
La forma más segura de pensar en la configuración es de arriba hacia abajo:
- Enterprise: la política de AI Findings debe permitir la función.
- Organización: pr_scan debe estar habilitado para autorizar su uso en repositorios.
- Repositorio: puede permanecer habilitado u optar por deshabilitar la detección para ese proyecto.
Esto evita una interpretación arriesgada de la API del repositorio: un PATCH correctamente formado no garantiza que el ajuste sea efectivo si una capa superior bloquea la función. La documentación de organización indica que un intento de habilitación puede ser rechazado cuando la política enterprise no permite AI Scan. El anuncio del preview también señala que la configuración del repositorio no sustituye un estado deshabilitado en la organización.
Cómo consultar y actualizar AI Scan por API
1. Consultar la configuración de la organización
Envía un GET a https://api.github.com/orgs/ORG/code-scanning/ai-scan con los headers recomendados Accept: application/vnd.github+json y X-GitHub-Api-Version: 2026-03-10. Una respuesta 200 utiliza el campo pr_scan con un valor como enabled o disabled.
2. Habilitar o deshabilitar a nivel de organización
Envía un PATCH al mismo endpoint con un cuerpo JSON equivalente a {"pr_scan":"enabled"} o {"pr_scan":"disabled"}. Con un token fine-grained, la actualización requiere el permiso Administration de la organización en modo write.
3. Consultar la configuración del repositorio
Envía un GET a https://api.github.com/repos/OWNER/REPO/code-scanning/ai-scan. Una respuesta 200 también devuelve el estado de pr_scan. Un 403 puede indicar, entre otras condiciones documentadas, que GitHub Advanced Security no está habilitado para el repositorio.
4. Actualizar un repositorio específico
Envía un PATCH al endpoint del repositorio con {"pr_scan":"enabled"} o {"pr_scan":"disabled"}. La documentación del endpoint indica 403 cuando el repositorio está archivado o GitHub Advanced Security no está habilitado, además de 404 para un recurso inexistente y 422 para fallos de validación.
Un flujo de rollout que reduce sorpresas
Para una organización con muchos repositorios, conviene separar la activación de la verificación. Un flujo conservador es:
- confirmar política enterprise, licencias y AI credits;
- inventariar repositorios con GitHub Advanced Security y CodeQL default setup;
- leer el estado actual de la organización mediante la API;
- habilitar la organización solo cuando los requisitos previos estén listos;
- seleccionar un grupo pequeño de repositorios y consultar el estado de cada uno;
- aplicar PATCH únicamente a los repositorios elegidos;
- volver a leer los endpoints después del cambio y registrar las respuestas HTTP para auditoría de la automatización;
- ampliar el rollout después de observar coste, calidad de señal y falsos positivos.
Este diseño también facilita el rollback: como el valor es explícito, la automatización puede guardar el estado anterior y restaurarlo si el preview presenta un comportamiento inesperado.
Lo que el public preview todavía no hace
- No es un análisis completo del repositorio: las detecciones con IA analizan solo pull requests; no se admiten full repository scans.
- No crea un backlog en la vista de seguridad: los hallazgos de IA aparecen en el pull request junto a los resultados de code scanning y no como alertas históricas de seguridad del repositorio.
- No bloquea merges por sí solo: los hallazgos son advisory y, en el preview actual, no pueden utilizarse en rulesets para imponer un requisito de merge.
- Puede producir falsos positivos: como otras herramientas basadas en IA, los resultados requieren revisión humana y GitHub ofrece feedback positivo/negativo.
- El alcance puede cambiar: las categorías de detección, los lenguajes admitidos y el comportamiento de los endpoints pueden evolucionar durante el preview.
- No está en GHES en esta versión: el anuncio limita este lanzamiento a github.com para clientes elegibles de GitHub Advanced Security.
¿AI Scan sustituye a CodeQL?
No. GitHub presenta AI Scan como complemento de CodeQL, especialmente para lenguajes y frameworks fuera de la cobertura actual de CodeQL. La documentación cita ejemplos como PHP, Shell/Bash, Terraform en HCL, Dockerfiles y carencias de frameworks como JSP y Blazor. AI Scan se ejecuta al crear el pull request y después de nuevos commits, y puede continuar incluso cuando una ejecución específica de CodeQL falla o queda en espera.
En la práctica, el diseño de seguridad es complementario: CodeQL mantiene el análisis estático de alta precisión para su conjunto admitido, mientras que las detecciones con IA amplían la cobertura en PRs. Por eso, habilitar AI Scan no es una razón para quitar CodeQL default setup: además de ser conceptualmente distintos, el propio default setup es un requisito para usar la función durante el preview.
Checklist antes de automatizar
- ¿El entorno es github.com y no GitHub Enterprise Server?
- ¿GitHub Advanced Security está habilitado en el repositorio?
- ¿Existe una licencia de GitHub Copilot para el preview y presupuesto para AI credits?
- ¿La política enterprise de AI Findings permite la habilitación?
- ¿La organización está habilitada para AI Scan?
- ¿CodeQL default setup está habilitado en el repositorio?
- ¿El token tiene el permiso exacto de lectura o escritura para el ámbito elegido?
- ¿La automatización gestiona 403, 404 y 422 sin asumir que todos los errores significan lo mismo?
- ¿El rollout reconoce que la función está en public preview y puede cambiar?
Para equipos de plataforma y AppSec, la principal ventaja de las nuevas APIs es la gobernanza programable: una configuración que antes dependía de clics en la interfaz puede formar parte de scripts, pipelines y rollouts controlados. La principal cautela es no confundir esa automatización con disponibilidad irrestricta. Las licencias, la política enterprise, el opt-in de la organización, la elegibilidad del repositorio y los límites del public preview siguen determinando si AI Scan realmente se ejecuta.
