Memorizar dependências para acelerar os fluxos de trabalho

Sobre a memorização das dependências do fluxo de trabalho

As execuções do fluxo de trabalho geralmente reutilizam as mesmas saídas ou dependências baixadas de uma execução para outra. Por exemplo, as ferramentas de gerenciamento de pacotes e de dependência, como, por exemplo, Maven, Gradle, npm e Yarn mantêm uma cache local de dependências baixadas.

Os trabalhos em executores hospedados em GitHub iniciam em uma imagem limpa do executor e devem fazer o download das dependências a cada vez gerando maior utilização de rede, maior tempo de execução e maior custo. Para ajudar a acelerar o tempo que leva para recriar arquivos como dependências, GitHub pode armazenar arquivos em cache que você usa frequentemente em fluxos de trabalho.

Para armazenar dependências em cache para um trabalho, você pode usar a ação GitHub de cache. A ação cria e restaura um cache identificado por uma chave única. Como alternativa, se você estiver armazenando em cache os gerentes de pacotes listados abaixo, usar suas respectivas ações de setup-* exige uma configuração mínima e irá criar e restaurar caches de dependências para você.

Comparando artefatos e memorização de dependência

Os artefatos são similares, pois fornecem a habilidade de armazenar arquivos em GitHub, mas cada recurso oferece usos diferentes e não podem ser usados de forma intercambiável.

• Use o cache quando você deseja reutilizar arquivos que não mudam frequentemente entre trabalhos ou execuções de fluxo de trabalho como, por exemplo, dependências de compilação de um sistema de gerenciamento de pacotes.
• Use artefatos quando quiser salvar arquivos produzidos por um trabalho para ser visualizado após a conclusão da execução de um fluxo de trabalho como, por exemplo, binários compilados ou logs de compilação.

Para obter mais informações sobre artefatos da execução do fluxo de trabalho, consulte "Persistir dados de fluxo de trabalho usando artefatos".

Restrições para acessar uma cache

Um fluxo de trabalho pode acessar e restaurar um cache criado no branch atual, no branch de base (incluindo branches base de repositórios bifurcados) ou no branch-padrão (geralmente principal). Por exemplo, um cache criado no branch-padrão pode ser acessado a partir de qualquer pull request. Além disso, se o branch feature-b tiver o branch de base feature-a, um fluxo de trabalho acionado em feature-b teria acesso a caches criados no branch-padrão (principal), feature-a e feature-b.

As restrições de acesso fornecem o isolamento da cache e a segurança ao criar um limite lógico entre os diferentes branches. Por exemplo, um cache criado para o branch feature-a (com a base no principal) não seria acessível para um pull request para o branch feature-b (com a base no principal).

Vários fluxos de trabalho dentro de um repositório compartilham entradas de cache. Uma cache criada para um branch de um fluxo de trabalho pode ser acessada e restaurada a partir de outro fluxo de trabalho para o mesmo repositório e branch.

Usar a ação cache

A ação

cache</a> tentará restaurar um cache com base na chave que você fornecer. Quando a ação encontrar uma cache, ela irá restaurar os arquivos memorizados no caminho que você configurar.

Se não houver correspondência exata, a ação criará automaticamente um novo cache se o trabalho for concluído com sucesso. O novo cache usará a chave que você forneceu e que contém os arquivos que você especificar no caminho.

Como alternativa, você pode fornecer uma lista de chaves de restauração a serem usadas quando a chave não corresponder à cache existente. Uma lista de chaves de restauração é importante quando você está tentando restaurar uma cache de outro branch, pois as chaves de restauração<code podem corresponder parcialmente às chaves da cache. Para obter mais informações sobre a correspondência das chaves de restauração, consulte "Correspondendo uma chave da cache".

Parâmetros de entrada para a ação da cache

• key: Obrigatório A chave criada ao salvar uma cache e a chave usada para pesquisar uma cache. Pode ser qualquer combinação de variáveis, valores de contexto, strings estáticas e funções. As chaves têm um tamanho máximo de 512 caracteres e as chaves maiores que o tamanho máximo gerarão uma falha na ação.

• caminho: Obrigatório O(s) caminho(s) do executor para armazenar em cache ou restaurar.

  • É possível especificar um caminho único ou adicionar vários caminhos em linhas separadas. Por exemplo:

```
- name: Cache Gradle packages
  uses: actions/cache@v3
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
```

• Você pode especificar diretórios ou arquivos únicos e padrões glob são compatíveis.

• Você pode especificar caminhos absolutos ou caminhos relativos ao diretório do espaço de trabalho.

• restore-keys: Opcional Uma string que contêm chaves de restauração alternativas, com cada uma colocada em uma nova linha. Se nenhuma correspondência de cache for encontrada para a chave, estas chaves de restauração serão usadas sequencialmente na ordem fornecida para encontrar e restaurar um cache. Por exemplo:

  restore-keys: |
    npm-feature-${{ hashFiles('package-lock.json') }}
    npm-feature-
    npm-
  

Parâmetros de saída para a ação da cache

• cache-hit: Um valor booleano para indicar que uma correspondência exata foi encontrada para a chave.

Exemplo do uso da ação da cache

Este exemplo cria uma nova cache quando são alterados os pacotes no arquivo package-lock.json ou quando é alterado o sistema operacional do executor. A chave da cache usa contextos e expressões para gerar uma chave que inclui o sistema operacional do executor e um hash SHA-256 do arquivo package-lock.json file.

name: Caching with npm
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v3
        env:
          cache-name: cache-node-modules
        with:
          # npm cache files are stored in `~/.npm` on Linux/macOS
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-

      - if: ${{ steps.cache-npm.outputs.cache-hit == 'false' }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm build

      - name: Test
        run: npm test

Quando uma chave corresponde a um cache existente, isso é denominado correspondência de cache, e a ação restaura os arquivos em cache para o diretório do caminho.

Quando a chave não corresponde a um cache existente, isso se chama falha de cache,, e um novo cache é criado automaticamente se o trabalho for concluído com sucesso.

Quando a falha de um cache ocorrer, a ação também pesquisa restore-keys para quaisquer correspondências:

1. Se você fornecer chaves de restauração, a ação da cache pesquisará, em seguida, todas as caches que correspondem à lista de chaves de restauração.
   • Se houver uma correspondência exata, a ação irá restaurar os arquivos na cache para o diretório do caminho.
   • Se não houver correspondências exatas, a ação pesquisará correspondências parciais das chaves de restauração. Quando uma ação encontra uma correspondência parcial, a última cache é restaurada para o diretório do caminho.
2. A ação cache é concluída e a próxima etapa do trabalho é executada.
3. Se a tarefa completar com sucesso, a ação cria automaticamente um novo cache com o conteúdo do diretório do caminho.

Para uma explicação mais detalhada do processo de correspondência de cache, consulte "Correspondendo uma chave do cache". Após criar uma cache, você não poderá alterar o conteúdo de uma cache existente, mas você poderá criar uma nova cache com uma nova chave.

Usar contextos para criar chaves da cache

Uma chave da cache pode incluir quaisquer contextos, funções, literais e operadores suportados por GitHub Actions. Para obter mais informações, consulte "Contextos" e "Expressões".

Usar expressões para criar uma chave permite que você crie automaticamente uma nova cache quando as dependências forem alteradas.

Por exemplo, você pode criar uma chave usando uma expressão que calcula o hash de um arquivo package-lock.json de npm. Portanto, quando as dependências que compõem o arquivo package-lock.json mudarem, a tecla cache muda e um novo cache é criado automaticamente.

npm-${{ hashFiles('package-lock.json') }}

GitHub avalia a expressão hash "package-lock.json" para derivar a chave final.

npm-d5ea0750

Usando a saída da ação do cache

Você pode usar a ação cache para fazer algo baseado em se ocorreu uma correspondência de cache ou se a falha ocorreu. Se houver uma falha de cache (uma correspondência exata para um cache não foi encontrada para a chave especificada), o resultado do cache-hit será definido como falso.

No exemplo de fluxo de trabalho acima, há uma etapa que lista o estado dos módulos do Node se ocorrer uma falha de cache:

- if: ${{ steps.cache-npm.outputs.cache-hit == 'false' }}
  name: List the state of node modules
  continue-on-error: true
  run: npm list

Corresponder uma chave da cache

A ação da cache primeiro pesquisa correspondências da cache para a chave e para as chaves de restauração no branch que contém a execução do fluxo de trabalho. Se não houver correspondências no branch atual, a ação da cache pesquisa a chave e as chaves de restauração no branch-pai e nos branches upstream.

restore-keys permite que você especifique uma lista de chaves alternativas de restauração a serem usadas quando há ausência de cache na chave. Você pode criar múltiplas chaves de restauração ordenadas da mais específica para a menos específica. A ação da cache pesquisa restore-keys em ordem sequencial. Quando uma chave não corresponde diretamente, a ação pesquisa as chaves prefixadas com a chave de restauração. Se houver múltiplas correspondências parciais para uma chave de restauração, a ação retornará a cache criada por último.

Exemplo do uso de múltiplas chaves de restauração

restore-keys: |
  npm-feature-${{ hashFiles('package-lock.json') }}
  npm-feature-
  npm-

O executor avalia as expressões, que resolvem essas chaves de restauração:

restore-keys: |
  npm-feature-d5ea0750
  npm-feature-
  npm-

A chave de restauração npm-feature- corresponde a qualquer chave que começa com a string npm-feature-. Por exemplo, ambas as chaves npm-feature-fd3052de e npm-feature-a9b253ff correspondem à chave de restauração. Será usada a cache com a data de criação mais recente. As chaves neste exemplo são pesquisadas na ordem a seguir:

1. npm-feature-d5ea0750 corresponde a um hash específico.
2. npm-feature- corresponde às chaves de cache prefixadas com npm-feature-.
3. npm- corresponde a chaves prefixadas com npm-.

Exemplo de prioridade de pesquisa

key:
  npm-feature-d5ea0750
restore-keys: |
  npm-feature-
  npm-

Por exemplo, se um pull request contiver um branch de recurso e tiver como alvo o branch padrão (main), a ação pesquisa chave e restore-keys na seguinte ordem:

1. A chave npm-feature-d5ea0750 no branch de recurso
2. Chave npm-feature- no branch de recurso
3. Chave npm- no branch de recurso
4. Chave npm-feature-d5ea0750 no branch principal
5. Chave npm-feature- no branch principal
6. Chave npm- no branch principal

Limites de uso e política de eliminação

GitHub removerá todas as entradas da cache não acessadas há mais de 7 dias. Não há limite no número de caches que você pode armazenar, mas o tamanho total de todos os caches em um repositório é limitado a 10 GB.

Se você exceder o limite, o GitHub salvará o novo cache, mas começará a despejar os caches até que o tamanho total seja menor que o limite do repositório.

Gerenciando caches

Você pode usar a API REST de GitHub para gerenciar seus caches. Você pode usar a API para listar e excluir entradas de cache e ver o seu uso de cache. Para obter mais informações, consulte o "GitHub Actions Cache" na documentação da API REST.

Você também pode instalar uma extensão de GitHub CLI para gerenciar seus caches pela linha de comando. Para obter mais informações sobre a extensão, consulte a documentação de extensão. Para obter mais informações sobre extensões de GitHub CLI, consulte "Usando as extensões de CLI do GitHub."