Resposta rápida
O lockfile do GitHub Actions permite manter referências fáceis de ler, como actions/checkout@v4, mas faz o workflow executar exatamente os commits registrados em .github/workflows/actions.lock. O recurso ficou disponível de forma geral em 28 de outubro de 2026 para GitHub Free, Team e Enterprise Cloud.
Instale a extensão oficial com gh extension install github/gh-actions-lock, execute gh actions-lock na raiz do repositório, revise o arquivo gerado e as mudanças nos workflows e envie tudo no mesmo pull request. Na CI, use gh actions-lock --verify para detectar lockfile ausente, desatualizado ou incompatível com as referências usadas.
O que o lockfile protege
Sem um lockfile, uma referência por tag ou branch é resolvida novamente no momento da execução. Se v4 ou main passar a apontar para outro commit, o workflow pode executar código diferente sem uma alteração visível no YAML. Fixar o SHA diretamente reduz esse risco, mas dificulta a leitura e a atualização em muitos arquivos.
O actions.lock separa essas duas necessidades. O YAML continua mostrando a versão humana, enquanto o runner usa o commit travado. A ferramenta oficial inclui actions diretas, dependências transitivas e referências de workflows reutilizáveis que consegue resolver. Isso reduz mudanças inesperadas, mas não prova que o commit escolhido é seguro.
Como preparar a primeira adoção
Comece em uma branch limpa e escolha um workflow de baixo risco. Antes de gerar o arquivo, inventarie todas as linhas uses:, incluindo actions de terceiros, actions compostas, workflows reutilizáveis, caminhos locais e imagens de contêiner. Essa lista ajuda a reconhecer o que foi coberto e o que continua fora do lockfile.
- Atualize o GitHub CLI e autentique-se no host correto com gh auth status.
- Instale a extensão oficial: gh extension install github/gh-actions-lock.
- Execute gh actions-lock na raiz do repositório.
- Abra .github/workflows/actions.lock e compare cada dependência resolvida com o YAML.
- Revise commits, origem, mantenedor e permissões antes de aceitar o primeiro lock.
- Envie o lockfile e os ajustes de workflow no mesmo pull request.
Como revisar o diff sem aceitar uma troca silenciosa
O lockfile é gerado pela ferramenta e não deve ser editado manualmente. No primeiro pull request, confirme o repositório de origem, a referência legível e o SHA resolvido para cada action. Em atualizações futuras, trate a mudança de commit como uma atualização de dependência: leia o release, o diff relevante, as permissões e o histórico do mantenedor.
Se uma tag ou branch se moveu de forma inesperada, não automatize --accept-moved. A própria extensão orienta investigar o motivo antes de aceitar. Use --relock apenas quando a intenção for avançar as referências para os commits atuais e houver revisão do código que passará a executar.
Como verificar o lockfile na CI
Adicione gh actions-lock --verify a um job que rode quando workflows ou o lockfile mudarem. A verificação consulta a origem e valida cobertura e proveniência. Um erro após editar uses: normalmente indica que o lockfile precisa ser regenerado e enviado junto da mudança.
O modo --verify-local funciona sem rede e confere a cobertura local, o que pode ser útil em pre-commit. Ele não confirma a proveniência dos commits e não substitui --verify na proteção principal. O modo --no-fix apenas relata diferenças, sem reescrever arquivos.
- Faça o job disparar para mudanças em .github/workflows/** e no actions.lock.
- Conceda somente as permissões de leitura necessárias ao job de verificação.
- Execute gh actions-lock --verify e falhe o check quando houver divergência.
- Mantenha a revisão humana para qualquer SHA novo ou alterado.
- Use o modo local apenas como retorno rápido antes do push.
Dependabot e política obrigatória
Quando o Dependabot atualiza uma dependência coberta, o GitHub informa que o pull request correspondente também regenera a entrada do lockfile sem configuração adicional. Ainda assim, revise o novo commit antes do merge; a atualização automática não é uma aprovação de segurança.
Administradores podem exigir lockfile por política. Ative a regra Require lockfile somente depois de cobrir os workflows escolhidos e testar a verificação. A adoção pode ser gradual por workflow, mas todas as dependências de um workflow já incluído precisam constar no arquivo. Habilitar a exigência cedo demais pode bloquear execuções legítimas.
O que o actions.lock não cobre
A documentação atual da extensão registra limitações. Actions locais referenciadas por caminho relativo não são seguidas automaticamente, imagens de contêiner não são travadas pelo arquivo e alguns formatos de chamada de workflow reutilizável podem exigir verificação adicional. Para contêineres, use digest @sha256 quando o fornecedor publicar uma imagem verificável.
Expressões dinâmicas, código baixado por scripts e dependências instaladas dentro de uma action continuam fora do alcance do lockfile. O arquivo também não substitui secret scanning, CodeQL, permissions explícitas, revisão de pull request, proteção de ambiente ou isolamento de runner. Ele fixa o código resolvido; não atesta confiança, ausência de vulnerabilidade ou comportamento seguro.
Como diagnosticar uma falha depois de ativar
Se o workflow parar com mensagem de lockfile ausente ou desatualizado, compare a primeira referência uses: citada no log, regenere o arquivo e revise o diff. Se a resolução falhar, confirme autenticação do gh, host, permissões e acesso de rede antes de ampliar o token. Em runners próprios, valide também a versão do runner e a disponibilidade do GitHub.
Uma indisponibilidade geral aparece no GitHub Status; um erro restrito a um repositório costuma apontar para referência, política, permissão ou lockfile. Não remova a proteção para fazer o job passar sem entender qual dependência deixou de ser resolvida.
Limites e próxima ação útil
Este guia foi verificado em 29 de outubro de 2026 no anúncio de disponibilidade geral, na documentação e no repositório oficial da extensão. O recurso está disponível nos planos informados pelo GitHub, mas políticas administrativas e alguns controles podem variar por plano e organização. Consulte a documentação do seu ambiente antes de exigir a regra em todos os repositórios.
Escolha hoje um workflow de teste, gere o actions.lock e abra um pull request sem ativar a exigência global. Confirme que o arquivo cobre dependências diretas e transitivas, rode --verify e execute o workflow. Depois de revisar o resultado, repita por grupo de repositórios e só então torne o lockfile obrigatório.
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.
- GitHub Actions workflow lockfiles are generally availableGitHub Changelog
- Locking action dependencies in a repository's workflowsGitHub Docs
- Workflow dependency lockfilesGitHub Docs
- github/gh-actions-lockGitHub
- GitHub StatusGitHub