O GitHub mudou a forma como consultas de execuções do GitHub Actions informam a quantidade de resultados na API e na interface. Desde o anúncio de 25 de setembro de 2026, buscas filtradas por workflow, evento, status, branch ou ator deixam de tentar fornecer uma contagem exata quando há mais de 2.500 registros correspondentes. Nesses casos, o GitHub passa a reportar a quantidade como “2.500+”. A paginação de resultados continua existindo e as consultas filtradas continuam limitadas a até 1.000 execuções retornáveis por busca.
Para quem mantém scripts, integrações, dashboards ou rotinas de auditoria, a revisão principal é simples: uma contagem acima desse limite não deve mais ser tratada como o total exato do universo consultado. Se a automação precisa localizar, exportar ou processar um conjunto muito grande de execuções, a recomendação do próprio GitHub é restringir melhor os filtros, inclusive com intervalos de data, e fazer consultas menores.
O que mudou nas consultas do GitHub Actions
A alteração atinge consultas de workflow runs feitas tanto pela interface quanto pela API do GitHub Actions. Segundo o GitHub, o comportamento anterior podia produzir um número aparentemente preciso, mas incorreto, em pesquisas muito grandes. Consultas com mais de 2.500 registros frequentemente atingiam timeout durante o cálculo e podiam terminar mostrando a quantidade encontrada até o momento da interrupção, não o total verdadeiro.
Para reduzir esse problema, o GitHub optou por trocar precisão numérica por uma indicação explícita de limite. Acima de 2.500 correspondências, a informação passa a significar apenas que existem mais de 2.500 registros. Isso evita que consumidores interpretem como exato um número que, em pesquisas extensas, poderia ter sido parcial.
É importante separar duas coisas. A primeira é a contagem apresentada para a pesquisa. A segunda é a quantidade de itens que uma consulta filtrada pode devolver por paginação. A documentação da API informa que buscas de workflow runs com parâmetros como actor, branch, created, event, head_sha ou status retornam no máximo 1.000 resultados por pesquisa. Cada página pode conter até 100 itens, conforme o parâmetro per_page.
Quais automações merecem revisão
Nem toda integração precisa ser alterada. O risco está principalmente em rotinas que usam a contagem como condição de controle ou que esperam varrer mais de 1.000 resultados de uma só vez. Vale revisar automações que executem um ou mais dos seguintes comportamentos:
- comparar a contagem retornada com um número esperado para decidir se a coleta terminou;
- usar a contagem como denominador de métricas, percentuais ou indicadores de cobertura;
- presumir que uma pesquisa ampla representa todas as execuções históricas do repositório;
- encerrar a paginação porque a quantidade total informada parece ter sido alcançada;
- gerar relatórios de conformidade ou auditoria que dependam de um total exato de workflow runs;
- consultar longos períodos usando apenas filtros amplos como branch, ator, evento ou status.
Se a automação só busca execuções recentes, procura um run específico, trabalha com um intervalo curto ou processa poucas páginas, a mudança pode não produzir efeito prático. Ainda assim, testes de regressão são úteis para confirmar que nenhum código converte ou compara a contagem de forma rígida.
O que não deve ser presumido sobre a API
O anúncio informa que o GitHub passa a reportar “2.500+” quando a quantidade encontrada excede 2.500, mas não detalha no changelog uma mudança de tipo para um campo específico da resposta REST. Por isso, uma integração não deve assumir, sem teste do endpoint utilizado, que um campo numérico como total_count simplesmente se tornou uma string.
O ponto seguro para implementação é tratar a contagem de grandes consultas como não exata e não construir lógica crítica que dependa de conhecer o total real a partir de uma única pesquisa ampla. Quando o código depende do formato exato da resposta, valide o endpoint e a versão de API usados pela integração antes de alterar parsing, tipagem ou esquema.
Como dividir consultas grandes
O caminho indicado pelo GitHub é estreitar os filtros. Para históricos extensos, uma estratégia prática é dividir a busca em janelas de tempo com o parâmetro created. Em vez de perguntar por todas as execuções de uma branch ou de um ator durante um período indefinido, a automação pode consultar mês a mês, semana a semana ou em outra janela adequada ao volume.
O tamanho ideal da janela depende da frequência dos workflows. Um repositório com centenas de execuções diárias provavelmente precisa de cortes menores que um projeto com poucos runs por semana. A regra operacional é escolher filtros que mantenham cada pesquisa abaixo dos limites relevantes e, quando necessário, reduzir novamente a janela.
Além da data, a API permite combinar filtros como actor, branch, event e status. Isso ajuda a transformar uma consulta muito abrangente em conjuntos menores e verificáveis. Depois, a aplicação pode agregar os resultados localmente, deduplicando por identificador da execução caso exista sobreposição entre janelas ou critérios.
Paginação continua exigindo atenção
A mudança na contagem não elimina as regras de paginação. A documentação do GitHub informa que per_page aceita no máximo 100 itens. Em buscas filtradas, o endpoint de listagem de workflow runs limita cada pesquisa a até 1.000 resultados. Portanto, aumentar o tamanho da página não resolve a necessidade de particionar uma consulta que corresponde a milhares de execuções.
Uma rotina robusta deve paginar enquanto houver páginas válidas dentro da pesquisa atual e controlar separadamente a passagem para a próxima janela de filtros. Esse desenho reduz a dependência de uma contagem global e torna mais explícito quais intervalos já foram processados.
Checklist para revisar scripts e integrações
- Localize consultas amplas. Procure chamadas de listagem de workflow runs filtradas por workflow, evento, status, branch, ator ou grandes períodos.
- Identifique dependência da contagem. Verifique condições, loops, dashboards e métricas que suponham que a contagem retornada é um total exato.
- Separe contagem de coleta. Não use um número global como única prova de que todos os registros foram processados.
- Particione o histórico. Adicione faixas de data ou outros filtros para manter as consultas menores.
- Paginar até o limite da busca. Respeite per_page e a paginação, lembrando que uma pesquisa filtrada pode devolver no máximo 1.000 resultados.
- Teste respostas reais. Confirme o comportamento do endpoint e da versão de API usados pela sua integração, especialmente se houver validação de tipo ou esquema.
- Proteja relatórios históricos. Se um indicador precisa de total exato, calcule-o a partir de conjuntos particionados e completos, não da contagem de uma única consulta ampla.
Quem é afetado e onde a mudança está chegando
O GitHub informou que a alteração está em implantação no github.com e no GitHub Enterprise Cloud. O anúncio não afirma que o mesmo comportamento já está disponível em todas as versões do GitHub Enterprise Server. Equipes que operam ambientes diferentes devem validar o comportamento na plataforma efetivamente usada antes de padronizar uma única estratégia de parsing para todos os ambientes.
O impacto prático para workflows e observabilidade
A mudança não altera a execução de um workflow, os gatilhos de um arquivo YAML ou o resultado de jobs já executados. Ela afeta a forma de consultar grandes conjuntos de workflow runs e interpretar o tamanho da resposta. O efeito aparece principalmente em ferramentas ao redor do Actions: coletores de histórico, inventários, painéis, auditorias, jobs agendados e integrações que cruzam execuções por branch, usuário, evento ou status.
Para essas ferramentas, a adaptação mais segura é abandonar a expectativa de uma contagem global exata em consultas muito grandes. Trabalhar com filtros menores, paginação controlada e agregação local reduz a chance de perder runs ou produzir métricas enganosas quando o volume ultrapassa os limites anunciados.
