O lockfile do GitHub Actions fixa o código executado, mas não todo o CI

É possível confiar no GitHub Actions quando um workflow referencia uma action por uma tag como @v3? O lockfile especifica qual commit da action será executado, mesmo que a tag seja movida posteriormente. A equipe pode revisar as atualizações de dependências no diff e manter uma lista auditável de actions usadas pelo CI. O limite prático: o lockfile cobre actions chamadas por etapas, mas um reusable workflow chamado no nível do job precisa ser fixado separadamente. O mecanismo descrito está disponível no GitHub Enterprise Cloud.

O que exatamente o lockfile fixa?

Referências a branches e tags são convenientes, mas a versão indicada por elas pode mudar. Uma entrada como uses: octo-org/deploy-action@v3 aponta para o nome de uma tag; o GitHub resolve essa referência para um commit quando o workflow é executado. Se o responsável pelo projeto mover a tag, uma execução futura sem dependência fixada poderá obter outro código.

De acordo com a documentação do GitHub sobre lockfiles, o arquivo .github/workflows/actions.lock armazena referências de dependências e os respectivos commits SHA, incluindo dependências transitivas — actions usadas por outras actions. O arquivo é criado pela extensão da CLI do GitHub gh actions-lock; ele não deve ser editado manualmente.

O gerador também pode tornar mais específicas as referências uses nos arquivos de workflow: por exemplo, pode converter uma referência a uma tag mutável em uma mais específica, preservando o commit para o qual ela apontava quando o lockfile foi criado. Por isso, ao adotar o mecanismo, é preciso revisar todo o diff — as alterações no workflow e no lockfile — e verificar se a versão fixada é a que a equipe pretende executar.

Depois disso, a atualização de uma dependência torna-se uma mudança visível no repositório: a equipe pode revisar a alteração do commit, discuti-la e aprová-la pelo processo habitual de revisão. O lockfile ajuda a auditar o código das actions e a manter as dependências consistentes; por si só, não atesta que o código escolhido seja seguro.

Onde termina o escopo da fixação?

A chamada de um reusable workflow em jobs.<job_id>.uses não é fixada pelo lockfile do repositório que faz a chamada. As dependências do reusable workflow pertencem ao repositório em que ele está definido. Para fixar a própria chamada, indique o SHA completo do commit; para fixar as actions desse workflow, o repositório de origem precisa de seu próprio lockfile.

O lockfile controla o código das actions, mas não outras entradas do processo de build, como parâmetros passados à action, secrets ou a imagem do runner. Ele responde a uma pergunta específica: qual commit do código da action será executado? Esses outros elementos exigem suas próprias regras de gestão.

Há também um caso especial: uma action local chamada por um caminho como uses: ./. De acordo com as instruções do GitHub, a extensão gh actions-lock não fixa nem analisa o caminho da action local. Se essa action usar outras actions, as dependências precisam ser geridas separadamente; a documentação descreve uma opção para migrar as referências a actions locais para o formato $/.

Assim, uma entrada no lockfile pode fazer parte de uma cadeia, mas não substitui o controle de todos os seus elos. Para um reusable workflow externo, verifique a fixação da chamada e o estado do repositório de origem; para actions locais, confira como suas dependências foram contabilizadas.

Como implementar o controle sem interromper o CI de surpresa?

O GitHub recomenda começar com um piloto em repositórios e workflows selecionados. A política Require lockfile bloqueia a execução dos workflows abrangidos sem um lockfile válido, inclusive workflows sem dependências uses:. O modo Evaluate das políticas só está disponível no GitHub Enterprise Cloud. Portanto, primeiro prepare o escopo e as atualizações automáticas; depois, ative a regra obrigatória.

1. Verifique as referências atuais. Antes de criar o lockfile, confirme que as actions apontam para versões que a equipe realmente pretende fixar. O gerador fixa o commit resolvido a partir da referência atual.
2. Crie e revise o lockfile. Instale a extensão gh-actions-lock, execute gh actions-lock na raiz do repositório e revise o diff completo, incluindo as referências uses reescritas.
3. Configure atualizações e validações. O Dependabot pode atualizar as entradas correspondentes dos workflows já configurados. No CI do pull request, é possível configurar uma tarefa de verificação com gh actions-lock --verify para detectar um lockfile desatualizado antes do build principal.
4. Defina revisores. Adicione .github/workflows/actions.lock ao CODEOWNERS e exija que responsáveis pela segurança do build revisem as alterações.
5. Faça um piloto da política. Comece com os repositórios e workflows configurados. No modo Evaluate, analise os resultados; antes de ativar o modo Active, confirme que todos os workflows abrangidos estão preparados e que os lockfiles continuam atualizados.

Require lockfile e a política separada Require actions to be pinned to a full-length commit SHA são regras diferentes; o GitHub informa que elas podem ser mantidas ao mesmo tempo. A verificação no CI e a política obrigatória também têm funções distintas: a primeira detecta um arquivo desatualizado durante o trabalho no pull request; a segunda bloqueia a execução de workflows que não atendem ao requisito.

Exemplo: atualização de uma action de implantação

Suponha que um workflow publique um aplicativo por meio de octo-org/deploy-action@v3. Primeiro, a equipe verifica para qual versão essa referência é resolvida; em seguida, executa gh actions-lock e analisa o diff do workflow junto com a entrada do commit no lockfile. Ao atualizar a action, o revisor vê as alterações nas referências e no commit fixado; assim, pode avaliar uma atualização específica, em vez de confiar que uma tag mutável sempre apontará para o mesmo código.

Se a implantação for feita por um reusable workflow de outro repositório, o lockfile local não cobre suas dependências. Fixe a referência ao reusable workflow com o SHA completo e verifique se o repositório de origem gerencia as dependências de suas próprias actions. Em organizações grandes, isso transforma regras dispersas em um processo auditável, sem deixar de controlar separadamente parâmetros, secrets e o runner.

O lockfile é útil como camada de controle do código das actions: torna visíveis as versões e atualizações, inclusive as dependências transitivas. Para garantir uma cobertura confiável, verifique também os reusable workflows e as actions locais, automatize as atualizações e só torne a política obrigatória depois de um piloto.