Um arquivo de workflow parece simples: baixar o repositório, instalar dependências, executar testes e publicar. Cada linha uses, porém, pode chamar uma ação mantida fora da empresa, que por sua vez depende de outras ações. Se uma referência por tag ou branch mudar, o pipeline pode executar código diferente daquele que foi revisado — com acesso a tokens, segredos, artefatos e ambientes de implantação.
Em 28 de outubro de 2026, os lockfiles de dependências do GitHub Actions chegaram à disponibilidade geral. O mecanismo permite manter referências legíveis no workflow e registrar, num arquivo separado, o commit exato e a identidade do repositório que devem ser executados. A novidade torna mais prática uma recomendação antiga de segurança: saber exatamente qual código participa da construção do seu software.
O pipeline também faz parte do produto
Empresas costumam aplicar revisão rigorosa ao código da aplicação e tratar o CI/CD como configuração auxiliar. Essa divisão não corresponde ao risco real. O pipeline lê o código, injeta credenciais, gera pacotes, assina artefatos e publica em produção. Uma dependência comprometida nessa etapa pode alterar o resultado sem tocar no repositório principal.
Tags como v3 facilitam atualizações, mas podem apontar para outro commit no futuro. Branches como main são ainda mais móveis. Mesmo quando o mantenedor é confiável, uma conta comprometida ou uma transferência de repositório pode mudar o que será executado.
O que um lockfile de workflow registra?
O arquivo .github/workflows/actions.lock relaciona os workflows às dependências utilizadas. Para cada ação, guarda a referência amigável, o commit resolvido e identificadores numéricos do proprietário e do repositório. Na execução, a plataforma verifica se o código corresponde ao registro.
- commit exato: evita que uma tag móvel altere silenciosamente o código executado;
- dependências transitivas: inclui ações chamadas por outras ações;
- identidade do repositório: ajuda a detectar substituições por outro projeto com o mesmo nome;
- inventário auditável: mostra quais componentes participam de cada workflow;
- mudanças revisáveis: uma atualização aparece como diff no pull request.
O lockfile é gerado pela extensão gh actions-lock e não deve ser editado à mão. Quando o Dependabot atualiza uma ação num workflow já adotado, também pode regenerar a entrada correspondente.
Lockfile é melhor que fixar SHA no YAML?
Fixar cada ação a um SHA completo continua sendo uma defesa útil, mas perde legibilidade e não oferece uma visão central das relações transitivas. O lockfile permite que o workflow mostre uma versão reconhecível enquanto a execução usa o commit aprovado. Ele também registra a identidade do repositório e facilita atualizações automáticas com revisão.
Isso não significa abandonar toda referência fixa. Workflows reutilizáveis chamados no nível de job têm regras próprias e podem precisar de SHA completo ou de lockfile no repositório onde são definidos. A arquitetura deve considerar os limites reais da ferramenta.
Exemplo: publicação de um aplicativo de vendas
Uma equipe mantém backend, painel web e aplicativo móvel. O workflow usa ações para checkout, configuração de runtime, cache, análise de segurança, upload de artefatos e implantação na nuvem. Antes do lockfile, seis referências por tag escondiam outras dependências transitivas.
No piloto, a empresa gera o inventário, confirma os repositórios de origem e revisa os commits atuais. O lockfile entra no mesmo pull request que habilita o primeiro workflow. Uma regra exige aprovação da equipe de plataforma para mudanças no arquivo. O Dependabot abre atualizações separadas, com a versão legível e o novo commit.
Na semana seguinte, uma tag de ação é movida pelo mantenedor. O pipeline continua executando o commit aprovado. A equipe recebe a atualização como mudança explícita, avalia o diff e decide quando avançar. A entrega permanece estável sem congelar o ecossistema.
O que o lockfile não resolve
Fixar uma dependência não prova que ela é segura. Se o commit já contém código malicioso, o lockfile apenas garante execução consistente. Ele também não controla parâmetros, scripts de shell, imagens de runner, pacotes instalados durante o job, segredos expostos ou permissões excessivas.
- revise a ação antes de fixá-la;
- trate mudanças de commit como mudanças de código;
- verifique workflows reutilizáveis e ações locais;
- mantenha o arquivo atualizado e bloqueie versões obsoletas;
- não aceite automaticamente uma referência movida sem investigar;
- teste a adoção antes de ativar uma política que bloqueie toda execução.
Controles que completam a proteção
Permissões mínimas e credenciais temporárias
Defina permissões do token por job e use OIDC para obter credenciais temporárias do provedor de nuvem. Um pipeline fixado, mas com chave administrativa permanente, continua perigoso. A nossa análise sobre segredos e chaves de API detalha esse risco.
CODEOWNERS e regras de aprovação
Inclua workflows e lockfiles no escopo de proprietários de código. Mudanças na cadeia de construção devem exigir revisão de quem entende segurança de entrega, não apenas da equipe responsável pela funcionalidade.
Proveniência e atestação
Lockfiles controlam parte das entradas; atestações ligam o artefato à origem e ao processo de construção. Estruturas como SLSA ajudam a organizar controles para impedir adulteração e verificar o que foi produzido.
Ambientes e implantação protegidos
Separe construção de implantação, limite ambientes, exija aprovação para produção e valide o artefato que será promovido. Recompilar em cada ambiente quebra a cadeia de evidências.
Como adotar em vários repositórios
- Inventarie: liste workflows, ações externas, reutilizáveis, permissões e segredos.
- Priorize: comece por pipelines que publicam artefatos ou acessam a produção.
- Gere e revise: crie lockfiles, confirme origem e avalie cada commit atual.
- Automatize a atualização: configure Dependabot e verificação de arquivo desatualizado.
- Proteja o diff: use CODEOWNERS e regras de branch.
- Avalie a política: execute em modo de observação antes de tornar o lockfile obrigatório.
- Meça e expanda: acompanhe cobertura, falhas e tempo de atualização.
Um programa empresarial precisa de exceções com prazo. Repositórios legados ou ações internas podem exigir migração gradual. Registrar o motivo, o responsável e a data de revisão é melhor que criar uma política impossível de cumprir.
Métricas para segurança sem atrito
Acompanhe o percentual de workflows cobertos, dependências transitivas inventariadas, referências móveis restantes, lockfiles desatualizados e tempo médio para aplicar atualizações de segurança. Observe também falsos bloqueios, tempo de pipeline e volume de exceções.
O objetivo não é maximizar arquivos gerados. É reduzir mudanças invisíveis e permitir que equipes atualizem componentes com evidência. Uma política que paralisa entregas tende a ser contornada; uma política integrada ao fluxo de pull request vira parte natural da engenharia.
Da automação conveniente à entrega verificável
Lockfiles de CI/CD transformam dependências implícitas em um contrato revisável. Eles não substituem análise de código, gestão de segredos, proveniência ou testes, mas fecham uma lacuna importante entre “o que lemos” e “o que realmente roda”.
A ProativaIA desenvolve software sob medida, aplicativos e automações com pipelines seguros e observáveis. Podemos mapear sua cadeia de entrega, modernizar CI/CD, aplicar controles graduais e integrar segurança ao desenvolvimento sem transformar cada publicação num processo manual.