Resposta rápida
Se a interface ou a API do GitHub Actions passou a mostrar 2.500+ para uma consulta de execuções, isso não significa que existem exatamente 2.500 runs nem que os demais foram apagados. Desde 25 de setembro de 2026, consultas amplas que encontram mais de 2.500 registros exibem essa contagem aproximada para evitar um total incompleto causado por timeout.
Não use essa contagem como total de auditoria. A API continua limitando a até 1.000 resultados cada busca que usa filtros como workflow, evento, status, branch ou ator. Para coletar um histórico completo, divida a consulta em intervalos de criação que não se sobreponham, percorra todas as páginas de cada intervalo e elimine duplicatas pelo id da execução.
O que mudou na API e na interface
O GitHub alterou as consultas de workflow runs feitas pela API do Actions e pela interface. Quando uma busca com filtros encontra mais de 2.500 registros, o total passa a ser apresentado como 2.500+ em vez de uma quantidade exata. A mudança está em implantação no GitHub.com e no GitHub Enterprise Cloud.
Segundo o comunicado oficial, buscas acima desse volume frequentemente atingiam timeout. O número anterior podia refletir apenas os registros encontrados antes da interrupção, mesmo quando parecia exato. A nova indicação é menos precisa, mas evita que um total parcial seja interpretado como o tamanho real do conjunto.
Por que per_page=100 não resolve o histórico completo
No endpoint GET /repos/{owner}/{repo}/actions/runs, per_page aceita até 100 itens. Isso reduz o número de chamadas por página, mas não remove o limite da busca. Quando você usa actor, branch, check_suite_id, created, event, head_sha ou status, a documentação informa que a pesquisa retorna no máximo 1.000 resultados.
Assim, seguir o cabeçalho Link até a última página é necessário, mas não suficiente para uma consulta que corresponde a milhares de runs. A coleta precisa combinar paginação com particionamento do filtro created. Dez páginas de 100 itens encerram a janela atual; não garantem que o restante do histórico esteja acessível na décima primeira página.
Como dividir as consultas por data
Use created para separar o período em janelas menores. O filtro aceita data, data e hora e intervalos. A granularidade adequada depende do volume: um repositório pequeno pode usar meses; um monorepo com muitas execuções pode precisar de dias ou horas. O objetivo é manter cada janela abaixo do limite de 1.000 resultados.
Com o GitHub CLI, um ponto de partida é gh api --paginate -H "X-GitHub-Api-Version: 2026-03-10" "/repos/OWNER/REPO/actions/runs?created=2026-09-01..2026-09-07&per_page=100". Substitua OWNER e REPO, autentique o CLI e ajuste o intervalo. Para um repositório privado, use um token com permissão de leitura de Actions; não coloque o token na URL, no log ou no arquivo do script.
- Escolha uma data inicial e uma data final para o relatório.
- Consulte uma janela pequena com created e per_page=100.
- Percorra o cabeçalho Link até não existir rel=next.
- Se a janela alcançar 1.000 itens, divida-a em períodos menores e repita.
- Una os resultados e remova duplicatas pelo campo id da workflow run.
- Registre a última data e o último id processados para retomar a coleta com segurança.
Como evitar lacunas e duplicatas nas bordas
Janelas com os mesmos horários de início e fim podem incluir a execução da borda duas vezes; janelas abertas podem deixar um intervalo sem cobertura. Defina uma convenção única, use UTC e registre os limites usados em cada chamada. Mesmo com intervalos planejados, deduplicar por id é uma proteção barata contra sobreposição e reprocessamento.
Em uma coleta contínua, salve um ponto de controle somente depois de persistir todas as páginas da janela. Se o processo falhar no meio, repita a janela e deduplique. Para relatórios históricos, valide que as janelas cobrem o período inteiro e compare o primeiro e o último created_at de cada bloco, sem tratar a soma das contagens aproximadas como prova de completude.
Filtros que reduzem custo e tornam a resposta útil
Se a pergunta é específica, filtre antes de paginar. Workflow, actor, branch, event, status e head_sha podem reduzir o conjunto. Para auditoria de falhas, por exemplo, combine status com created; para uma branch de release, acrescente branch. Não aplique um filtro só para ficar abaixo do limite se isso retirar registros necessários ao relatório.
Evite fazer chamadas concorrentes em excesso. As boas práticas da API recomendam solicitações seriais quando possível, respeito aos limites e recuo quando houver erro. Guarde ETag e use requisições condicionais quando o recurso e o cliente permitirem; isso reduz tráfego sem transformar cache em fonte única de auditoria.
403, 429 ou páginas que param antes do esperado
Uma resposta 403 pode indicar permissão insuficiente ou limite de taxa, enquanto 429 sinaliza excesso de requisições. Verifique os cabeçalhos x-ratelimit-remaining, x-ratelimit-reset e retry-after antes de trocar credenciais ou repetir imediatamente. Em repositórios privados, confirme a permissão Actions: read do token de acesso refinado.
Se a paginação falhar sem mudança no script, consulte o GitHub Status para separar indisponibilidade do serviço de erro de filtro, autenticação ou limite. Um status operacional não garante que a sua consulta esteja correta; ele apenas reduz a chance de uma falha geral da plataforma.
- Registre status HTTP, request id e cabeçalhos de rate limit sem gravar o token.
- Respeite retry-after ou aguarde até x-ratelimit-reset quando o limite acabar.
- Reduza a frequência e o tamanho das janelas antes de ampliar permissões.
- Confirme Actions: read e o acesso do token ao repositório privado.
- Consulte o GitHub Status e repita apenas a janela que falhou.
Limitações deste método
O particionamento recupera o que a API disponibiliza dentro dos filtros e permissões informados; ele não recria runs excluídas, não vence políticas de retenção e não concede acesso a repositórios privados. O anúncio cobre GitHub.com e GitHub Enterprise Cloud. No GitHub Enterprise Server, confirme o comportamento na documentação da versão instalada.
A indicação 2.500+ está em implantação e clientes rígidos devem lidar com uma contagem não exata sem interromper a coleta. Use os itens retornados e os links de paginação como mecanismo operacional. Para uma comprovação formal, mantenha logs de coleta, janelas, ids e respostas de erro, e não apenas um número exibido na interface.
Próxima ação útil
Este guia foi verificado em 26 de setembro de 2026. Procure nos seus scripts onde a contagem de workflow runs decide o fim da paginação, o tamanho do relatório ou um alerta. Troque essa dependência por páginas, intervalos created e deduplicação por id. Teste primeiro com uma janela que produza menos de 1.000 resultados e depois amplie o período.
Se a rotina roda em GitHub Actions, atualize também os limites de tempo e a persistência do ponto de controle. Um job que consulta anos de histórico em toda execução é mais frágil e caro do que uma importação inicial seguida de coleta incremental.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Changes to query results in the GitHub Actions API and UIGitHub Changelog
- REST API endpoints for workflow runsGitHub Docs
- Using pagination in the REST APIGitHub Docs
- Best practices for using the REST APIGitHub Docs
- Rate limits for the REST APIGitHub Docs
- GitHub StatusGitHub