GitHub AI Scan API: organização, repositório e limites

O GitHub abriu em 10 de setembro de 2026 um public preview de APIs REST para administrar o AI Scan de pull requests no nível da organização e do repositório. A novidade é útil para equipes que querem ativar ou desativar a varredura por código, em vez de repetir a configuração manualmente na interface. O ponto mais importante, porém, é a hierarquia: o repositório pode ajustar sua própria participação, mas não consegue habilitar o recurso quando uma camada superior o bloqueia.

Segundo o anúncio oficial do GitHub, os endpoints são /orgs/{org}/code-scanning/ai-scan e /repos/{owner}/{repo}/code-scanning/ai-scan. A documentação deixa claro que esses endpoints continuam em public preview e podem mudar.

O que precisa estar pronto antes de chamar a API

Habilitar o parâmetro pr_scan pela API não elimina os pré-requisitos do produto. No preview atual, o AI Scan depende de uma combinação de política, licenças e configuração de code scanning.

Ambiente: o preview foi anunciado para github.com. O GitHub Enterprise Server não é suportado nesta versão.
Licenças: as detecções de segurança com IA exigem GitHub Advanced Security e, durante o public preview, também uma licença do GitHub Copilot.
Créditos de IA: o uso consome AI credits, de acordo com a documentação do recurso.
Política enterprise: o administrador enterprise precisa permitir AI Findings. Se a empresa proibir o recurso, a organização não consegue habilitá-lo.
Opt-in da organização: a organização precisa habilitar as detecções com IA antes de os repositórios poderem usá-las.
CodeQL default setup: o repositório precisa ter o CodeQL default setup habilitado. Isso é um pré-requisito de elegibilidade, embora a execução do AI Scan seja independente do estado de uma execução específica do CodeQL.

A referência conceitual do GitHub sobre AI-powered security detections é a melhor fonte para checar esses requisitos, porque ela também documenta os limites operacionais do preview.

Organização vs. repositório: endpoints, permissões e efeito

Escopo	Endpoint	Leitura	Atualização	Efeito prático
Organização	/orgs/{org}/code-scanning/ai-scan	Fine-grained: Administration da organização (read). Usuário autenticado deve ser owner ou security manager.	Fine-grained: Administration da organização (write).	Define se os repositórios da organização podem usar AI Scan. Se estiver desabilitado, o repositório não pode contornar o bloqueio.
Repositório	/repos/{owner}/{repo}/code-scanning/ai-scan	Fine-grained: Code scanning alerts do repositório (read).	Fine-grained: Administration do repositório (write).	Permite optar por habilitar ou desabilitar AI Scan naquele repositório, desde que a organização e a política enterprise permitam.

Para tokens clássicos, as exigências variam por endpoint. No nível da organização, a documentação aceita escopos como admin:org, repo ou write:org, conforme o papel do usuário. No repositório, a leitura exige security_events em repositórios privados ou públicos, enquanto a atualização exige repo; para operações restritas a repositórios públicos, public_repo pode ser suficiente. Antes de automatizar, confira os detalhes nas páginas da API da organização e da API de code scanning do repositório.

Como a precedência de configuração funciona

A forma mais segura de pensar na configuração é de cima para baixo:

Enterprise: a política de AI Findings precisa permitir o recurso.
Organização: pr_scan precisa estar habilitado para autorizar o uso nos repositórios.
Repositório: pode permanecer habilitado ou optar por desabilitar a detecção naquele projeto.

Isso evita uma interpretação perigosa da API do repositório: um PATCH bem-formado não garante que a configuração será efetiva se uma camada superior bloquear o recurso. A própria documentação da organização informa que uma tentativa de habilitar pode ser rejeitada quando a política enterprise não permite AI Scan. E o anúncio do preview reforça que a configuração do repositório não substitui um estado desabilitado na organização.

Como ler e atualizar o AI Scan por API

1. Consultar a organização

Faça um GET em https://api.github.com/orgs/ORG/code-scanning/ai-scan, enviando os cabeçalhos recomendados Accept: application/vnd.github+json e X-GitHub-Api-Version: 2026-03-10. Uma resposta 200 usa o campo pr_scan, com valor como enabled ou disabled.

2. Habilitar ou desabilitar na organização

Faça um PATCH no mesmo endpoint com corpo JSON equivalente a {"pr_scan":"enabled"} ou {"pr_scan":"disabled"}. Para um token fine-grained, a atualização exige permissão Administration da organização em modo write.

3. Consultar o repositório

Faça um GET em https://api.github.com/repos/OWNER/REPO/code-scanning/ai-scan. Uma resposta 200 também retorna o estado de pr_scan. Um 403 pode indicar, entre outras condições documentadas, que GitHub Advanced Security não está habilitado para o repositório.

4. Atualizar um repositório específico

Faça um PATCH no endpoint do repositório com {"pr_scan":"enabled"} ou {"pr_scan":"disabled"}. A documentação do endpoint aponta 403 quando o repositório está arquivado ou quando GitHub Advanced Security não está habilitado, além de 404 para recurso não encontrado e 422 para falha de validação.

Um fluxo de rollout que reduz surpresa

Para uma organização com muitos repositórios, vale separar a ativação da verificação. Um fluxo conservador é:

confirmar política enterprise, licenças e AI credits;
inventariar repositórios com GitHub Advanced Security e CodeQL default setup;
ler o estado atual da organização pela API;
habilitar a organização apenas quando os pré-requisitos estiverem prontos;
selecionar um grupo pequeno de repositórios e consultar o estado de cada um;
aplicar PATCH somente nos repositórios escolhidos;
reler os endpoints após a mudança e registrar respostas HTTP para auditoria da automação;
expandir o rollout depois de observar custo, sinal e falsos positivos.

Esse desenho também facilita rollback: como o valor é explícito, a automação pode guardar o estado anterior e restaurá-lo se o preview apresentar comportamento inesperado.

O que o public preview ainda não faz

Não é varredura completa do repositório: as detecções com IA analisam pull requests; não há full repository scan.
Não cria backlog de alertas na área de segurança: os achados de IA aparecem no pull request, ao lado dos resultados de code scanning, e não como alertas históricos do repositório.
Não bloqueia merge por si só: os achados são advisory e, no preview atual, não podem ser usados em rulesets para impor requisito de merge.
Pode produzir falsos positivos: como em outras ferramentas baseadas em IA, os resultados precisam de revisão humana e o GitHub oferece feedback de positivo/negativo.
Escopo pode mudar: categorias de detecção, idiomas suportados e comportamento dos endpoints podem evoluir durante o preview.
Não está no GHES deste lançamento: o anúncio limita esta versão a github.com para clientes elegíveis de GitHub Advanced Security.

O AI Scan substitui CodeQL?

Não. O GitHub apresenta o AI Scan como complemento ao CodeQL, especialmente para linguagens e frameworks fora da cobertura atual do CodeQL. A documentação cita exemplos como PHP, Shell/Bash, Terraform em HCL, Dockerfiles e lacunas de frameworks como JSP e Blazor. O AI Scan é disparado na criação do pull request e após novos commits, e pode continuar mesmo quando uma execução específica do CodeQL falha ou fica aguardando.

Na prática, o desenho de segurança é complementar: CodeQL mantém a análise estática de alta precisão em seu conjunto suportado, enquanto as detecções com IA ampliam a cobertura em PRs. Por isso, habilitar AI Scan não é uma justificativa para remover o CodeQL default setup — além de conceitualmente diferentes, o próprio default setup é requisito para usar o recurso no preview.

Checklist antes de automatizar

O ambiente é github.com, não GitHub Enterprise Server?
GitHub Advanced Security está habilitado no repositório?
Há licença do GitHub Copilot para o preview e orçamento de AI credits?
A política enterprise de AI Findings permite a ativação?
A organização está habilitada para AI Scan?
O CodeQL default setup está habilitado no repositório?
O token tem a permissão exata para leitura ou escrita no escopo escolhido?
A automação trata 403, 404 e 422 sem assumir que todo erro significa a mesma coisa?
O rollout reconhece que o recurso é public preview e pode mudar?

Para equipes de plataforma e AppSec, a principal vantagem das novas APIs é governança programável: a mesma configuração que antes dependia de cliques pode entrar em scripts, pipelines e controles de rollout. A principal cautela é não confundir essa automação com disponibilidade irrestrita. Licenças, política enterprise, opt-in da organização, elegibilidade do repositório e os limites do public preview continuam determinando se o AI Scan realmente roda.