Arquivos de bloqueio de dependências do fluxo de trabalho

Um arquivo de bloqueio fixa todas as ações das quais seus fluxos de trabalho dependem em um commit verificado, portanto, o código que você analisou é o código que é executado.

Neste artigo

Por que bloquear dependências de fluxo de trabalho?

Os fluxos de trabalho geralmente fazem referência a uma ação por uma tag ou branch, como uses: octo-org/deploy-action@v3 ou uses: octo-org/deploy-action@main. GitHub Actions resolve essa referência para qualquer commit para o qual a tag ou branch aponta em tempo de execução.

Tags e branches podem se mover. Como resultado, o código executado não tem a garantia de ser o código que o autor do fluxo de trabalho revisou originalmente. Se a conta de um mantenedor upstream for comprometida e uma tag for redirecionada, seus repositórios poderão executar código mal-intencionado.

Um arquivo de bloqueio de dependência de fluxo de trabalho associa um SHA do commit a cada ação da qual seus fluxos de trabalho dependem, incluindo dependências transitivas. Ele não vincula chamadas a fluxos de trabalho reutilizáveis (jobs.<job_id>.uses). Para fixar um fluxo de trabalho reutilizável, referencie-o por sua SHA do commit completa. Um lockfile controla qual código de ação é executado no runner. Ele não controla outras entradas de build, como parâmetros de entrada, segredos ou a imagem do executor. Um arquivo de bloqueio fornece o seguinte para o código da action que ele aborda:

  • Resolução reproduzível de dependências entre ações
  • Alterações de dependência revisíveis e Dependabot atualizações de versão
  • Um inventário auditável das dependências de ação dos seus sistemas de CI/CD

Como funciona o arquivo de bloqueio?

O arquivo de bloqueio é definido em um repositório em .github/workflows/actions.lock. Ela é gerada por gh actions-lockuma GitHub CLI extensão e nunca deve ser editada manualmente.

Você pode integrar os fluxos de trabalho de um repositório ao arquivo de bloqueio um de cada vez ou tudo de uma vez. Depois que um fluxo de trabalho é configurado:

  • Cada dependência de ação que o fluxo de trabalho usa deve estar presente no arquivo de bloqueio.
  • O commit bloqueado é o que é executado quando o fluxo de trabalho é executado e o que as políticas de ações permitidas verificam.
  • Esse commit deve ser acessível a partir do branch ou da tag registrados para ele no arquivo de bloqueio, no repositório da própria ação. Um commit que existe apenas em um fork, ou que não é mais acessível a partir desse branch ou tag, é rejeitado quando o fluxo de trabalho é executado.

Um arquivo de bloqueio abrange os fluxos de trabalho em seu próprio repositório, incluindo dependências transitivas (ações que suas dependências de ação usam), exceto para dependências de chamadas de fluxo de trabalho reutilizáveis. Fluxos de trabalho reutilizáveis também podem ter seus próprios arquivos de bloqueio. As dependências de um fluxo de trabalho reutilizável são cobertas pelo arquivo de bloqueio do repositório em que ele é definido, não pelo arquivo de bloqueio do repositório que o chama.

O que o arquivo de bloqueio registra?

O arquivo de bloqueio tem duas seções. workflows registra quais dependências cada fluxo de trabalho integrado usa, e dependencies registra a qual commit cada uma dessas referências corresponde.

# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
    '.github/workflows/ci.yml':
        - 'octo-org/deploy-action@v3.1.0'
dependencies:
    'octo-org/deploy-action@v3.1.0':
        ref: 'v3.1.0'
        commit: 'sha1-...'
        owner_id: 44036562
        repo_id: 197814629

Cada dependência registra:

  • ref: A tag ou branch da qual o commit foi resolvido.
  • commit: o commit exato ao qual a referência foi resolvida. Esse é o código que será executado.
  • owner_id e repo_id: a identidade numérica do repositório de origem. GitHub Actions usa-os para confirmar em tempo de execução que o repositório por trás do nome ainda é aquele que você travou.

Esse formato estruturado fornece a ferramentas como Dependabot um registro legível por computador que elas podem usar para gerenciar atualizações de dependência, sem depender de comentários YAML como anotações de versão.

Como os arquivos de bloqueio se comparam com a fixação por SHA?

GitHub historicamente recomendou fixar ações de terceiros em um SHA de commit completo em seus arquivos de fluxo de trabalho. Para repositórios que adotam um arquivo de bloqueio, a fixação SHA em arquivos de fluxo de trabalho não é mais necessária. O lockfile é a melhor opção porque:

  • Dá suporte a dependências transitivas
  • Torna os arquivos de fluxo de trabalho mais fáceis de ler
  • Registra a identidade do repositório de origem

Um arquivo lockfile também satisfaz a política separada Exigir que as ações sejam fixadas em um SHA de commit completo para fluxos de trabalho que aderiram a ela. Consulte Controle da execução de GitHub Actions fluxos de trabalho.

Próximas Etapas 

Para criar um arquivo de bloqueio para um repositório, consulte Bloqueio de dependências de ação nos fluxos de trabalho de um repositório.