GitHub Actions cache-mode: verificando permissões de cache por trás de uma CI verde
Se a CI termina verde, mas a próxima execução baixa as dependências novamente, a primeira reação costuma ser ajustar a chave do cache. Agora, você também precisa verificar se o salvamento foi ignorado devido a permissões. O simples fato de um fluxo de trabalho ser bem-sucedido não significa que o cache foi criado.
O GitHub anunciou a disponibilidade geral do cache-mode em 10 de setembro de 2026. Em todos os planos do github.com, agora é possível definir o acesso ao cache no nível do fluxo de trabalho ou do job. Indo além do artigo anterior sobre o padrão somente leitura existente, desta vez nos concentramos na configuração explícita e nos métodos de verificação.
Recursos confirmados: quatro combinações de restauração e salvamento
read permite apenas a restauração, enquanto write permite tanto a restauração quanto o salvamento. write-only permite apenas o salvamento, e none bloqueia ambos. A primeira verificação é não confundir o nome write como se fosse exclusivo para salvar.
O valor declarado em um job tem precedência sobre a configuração de todo o fluxo de trabalho. Por outro lado, em chamadas de fluxos de trabalho reutilizáveis, não é possível obter permissões de acesso maiores do que as permitidas pelo chamador. Não julgue as permissões reais de toda a execução lendo apenas a declaração em um único arquivo.
Uma execução verde não é evidência de salvamento
A documentação oficial explica que operações de cache não permitidas deixam logs informativos e continuam a execução. Uma restauração bloqueada é tratada como cache miss, e um salvamento bloqueado simplesmente não é executado. O ponto central de observação é que o fluxo de trabalho em si não falha.
Portanto, é útil separar os registros operacionais entre o sucesso da execução e o resultado do cache. Em uma única execução, verifique qual evento disparou, qual modo foi aplicado, se houve restauração e se o salvamento foi ignorado. Trata-se de uma abordagem operacional sugerida com base na documentação oficial dos recursos, e não em um novo recurso de painel fornecido automaticamente.
Crie uma pequena tabela de permissões antes de aplicar
Abra os fluxos de trabalho reais do seu repositório e identifique os jobs que produzem e os que consomem cache. Não é necessário agrupar com as mesmas permissões jobs que preparam dependências em branches confiáveis, jobs que testam alterações externas e jobs que validam artefatos de implantação.
Escreva duas frases para cada job: Este job precisa ler o cache existente? O resultado deste job pode ser deixado para a próxima execução ler? Se nenhum dos dois for necessário, você pode repensar o hábito de anexar cache por inércia. No entanto, a configuração real deve ser decidida de acordo com os limites de confiança e a estrutura de build do repositório.
Experimento mínimo: job consumidor somente leitura
Por exemplo, em um fluxo de trabalho de teste, especifique cache-mode: read no nível superior e verifique se não há sobreposições por job. Compare se os resultados dos testes com cache são idênticos aos resultados sem cache. Como o cache deve ser um meio auxiliar para reduzir o tempo de execução, se a precisão mudar sem o cache, as premissas de build devem ser revisadas primeiro.
O critério de aprovação deste experimento não é apenas uma linha de sucesso na CI. Deve ser possível explicar a tentativa de restauração e a omissão do salvamento, além de verificar novamente na próxima execução com as mesmas entradas. Registrar os commits anteriores e posteriores ao experimento, o gatilho, as configurações efetivas e o local dos logs facilita para os colegas reproduzirem a avaliação.
Em fluxos de trabalho reutilizáveis, leia até o caminho de chamada
Mesmo que você defina padrões seguros em um fluxo de trabalho compartilhado, deve revisar tanto o lado chamador quanto as configurações individuais dos jobs. O fato de diferentes repositórios chamarem o mesmo arquivo não significa que eles sejam executados com as mesmas permissões.
Durante a revisão, comece pelo chamador e siga pela declaração de cache do job até o fluxo de trabalho chamado. Se as permissões esperadas forem diferentes dos logs reais, identifique a origem da configuração antes de complicar ainda mais as chaves. Esta é uma sugestão para reduzir o tempo de diagnóstico em organizações com alto reuso e não implica um valor medido de melhoria de desempenho.
Exceções a serem observadas e ordem de aplicação
Especificar write ou write-only em eventos de baixa confiança, como pull_request_target, pode sobrescrever a restrição padrão somente leitura e aumentar o risco de envenenamento de cache. O GitHub adiciona anotações de aviso nesses casos. Respostas que aumentam as permissões de gravação para eliminar o aviso devem ser evitadas.
Por outro lado, a escolha de bloquear todo o cache também tem um custo. Os tempos de download e compilação podem aumentar; portanto, compare diretamente os tempos de execução em um job representativo antes de expandir o escopo. Em vez de prometer efeitos de desempenho com estimativas numéricas, é melhor que a equipe decida em conjunto as restrições necessárias de segurança e o atraso tolerável.
Perguntas para a equipe verificar agora
A tarefa para hoje não é adicionar a nova configuração em massa a todos os repositórios. Trata-se de encontrar os produtores e consumidores de cache em um fluxo de trabalho crítico, registrar as permissões e verificar as evidências de restauração e salvamento em uma única execução. Se for um job de implantação, mantenha as alterações pequenas para que os responsáveis possam ler os logs e verificar se atendem às expectativas.
A pergunta que pode surgir na prática é por que a CI teve sucesso se a etapa de salvamento foi ignorada. Este artigo explica essa confusão com base no comportamento oficial e não faz alegações sobre pesquisas na comunidade ou taxas universais de falha. Ao adotar o novo recurso, verificar separadamente os resultados de desempenho e de permissão permitirá classificar os próximos problemas de cache com mais precisão.