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 nos executores hospedados em GitHub começam em uma imagem do executor limpa e devem baixar as dependências todas as vezes, o que gera maior utilização da rede, maior tempo de execução e aumento dos custos. Para ajudar a acelerar o tempo que leva para recriar arquivos como dependências, o GitHub pode armazenar em cache os arquivos que você usa frequentemente nos fluxos de trabalho.

Para armazenar em cache as dependências de um trabalho, você pode usar a ação cache do GitHub. A ação cria e restaura um cache identificado por uma chave exclusiva. Como alternativa, se você estiver armazenando em cache os gerenciadores de pacotes listados abaixo, o uso das respectivas ações setup-* exigirá configuração mínima e criará e restaurará caches de dependência 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 quiser reutilizar arquivos que não são alterados com frequência entre trabalhos ou execuções de fluxo de trabalho, como dependências de build de um sistema de gerenciamento de pacotes.
• Use artefatos quando quiser salvar arquivos produzidos por um trabalho a serem exibidos após o fim de uma execução de fluxo de trabalho, como binários internos ou logs de build.

Para obter mais informações sobre artefatos de execução de fluxo de trabalho, confira "Armazenar dados do fluxo de trabalho como artefatos".

Restrições para acessar uma cache

As restrições de acesso fornecem o isolamento da cache e a segurança ao criar um limite lógico entre os diferentes branches ou marcas. As execuções de fluxo de trabalho podem restaurar caches criados no branch atual ou no branch padrão (geralmente main). Se uma execução de fluxo de trabalho for disparada para uma solicitação de pull, ela também poderá restaurar caches criados no branch base, incluindo branches base de repositórios com fork. Por exemplo, se o branch feature-b tiver o branch base feature-a, uma execução de fluxo de trabalho disparada em uma solicitação de pull terá acesso aos caches criados no branch main padrão, no branch feature-a base e no branch feature-b atual.

As execuções de fluxo de trabalho não podem restaurar caches criados para branchs filhos ou irmãos. Por exemplo, um cache criado para o branch feature-b filho não estaria acessível a uma execução de fluxo de trabalho disparada no branch main pai. Da mesma forma, um cache criado para o branch feature-a com o main base não seria acessível ao branch feature-c irmão com o main base. As execuções de fluxo de trabalho também não podem restaurar caches criados para nomes de marcas diferentes. Por exemplo, um cache criado para a marca release-a com o main base não seria acessível a uma execução de fluxo de trabalho disparada para a marca release-b com o main base.

Quando um cache é criado por uma execução de fluxo de trabalho disparada em uma solicitação de pull, ele é criado para a referência de mesclagem (refs/pull/.../merge). Por isso, ele terá um escopo limitado e só poderá ser restaurado por novas execuções da solicitação de pull. Ele não poderá ser restaurado pelo branch base ou por outras solicitações de pull direcionadas a esse branch.

Diversas execuções de fluxo de trabalho em um repositório podem compartilhar caches. Um cache criado para um branch em uma execução de fluxo de trabalho pode ser acessado e restaurado por meio de outra execução de fluxo de trabalho para o mesmo repositório e branch.

Como usar a ação cache

A ação cache tentará restaurar um cache com base na key que você fornecer. Quando a ação encontra um cache que corresponde exatamente à chave, a ação restaura os arquivos armazenados em cache no path configurado. Opcionalmente, é possível fornecer uma lista de restore-keys para uso caso key não corresponda a um cache existente. Uma lista de restore-keys é útil ao restaurar um cache de outro branch porque restore-keys pode corresponder parcialmente às chaves de cache. Para obter mais informações sobre as restore-keys correspondentes, confira "Como fazer a correspondência de uma chave de cache".

Se houver uma correspondência exata com o key fornecido, isso será considerado uma ocorrência no cache. Se nenhum cache corresponder exatamente ao key fornecido, isso é considerado uma perda no cache. Em uma perda no cache, a ação cria automaticamente um cache quando o trabalho é concluído com sucesso. O novo cache usará a key fornecida e conterá os arquivos especificados no path. Para saber como isso é feito, confira "Ocorrências e perdas no cache".

Não é possível alterar o conteúdo de um cache existente. Em vez disso, crie um cache com uma nova chave.

Os parâmetros de entrada da ação cache

• key: Obrigatório A chave criada ao salvar um cache, e a chave usada para pesquisar um cache. Pode ser qualquer combinação de variáveis, valores de contexto, cadeias de caracteres 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.

• path: Obrigatório Os caminhos no executor para armazenamento em cache ou restauração.

  • Você pode especificar um só caminho 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 os 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 cadeia de caracteres que contém chaves de restauração alternativas, com cada chave de restauração colocada em uma nova linha. Se não houver nenhuma ocorrência da keyno cache, essas chaves de restauração serão usadas sequencialmente na ordem fornecida para localizar e restaurar um cache. Por exemplo:

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

• enableCrossOsArchive: opcional um valor booliano que, quando habilitado, permite que os executores do Windows salvem ou restaurem caches independentemente do sistema operacional em que o cache foi criado. Se esse parâmetro não estiver definido, ele usará como padrão false. Para obter mais informações, confira Cache entre sistemas operacionais na documentação do Actions Cache.

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

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

Ocorrências e perdas no cache

Quando key corresponde exatamente a um cache existente, isso é chamado de ocorrência no cache e a ação restaura os arquivos em cache no diretório path.

Quando key não corresponde a um cache existente, isso é chamado de perda no cache e um cache é criado automaticamente se o trabalho for concluído com sucesso.

Quando ocorre uma perda no cache, a ação também pesquisa o restore-keys especificado para encontrar correspondências:

1. Se você fornecer restore-keys, a ação cache vai procurar sequencialmente os caches que correspondem à lista de restore-keys.
   • Se houver uma correspondência exata, a ação vai restaurar os arquivos no cache no diretório path.
   • 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, o último cache é restaurado no diretório path.
2. A ação cache é concluída e a próxima etapa é executada no trabalho.
3. Se o trabalho for concluído com sucesso, a ação criará automaticamente um cache com o conteúdo do diretório path.

Para obter uma explicação mais detalhada do processo de correspondência de cache, confira "Correspondência de uma chave de cache".

Exemplo que usa a ação cache

Este exemplo cria um cache quando os pacotes do arquivo package-lock.json são alterados ou quando o sistema operacional do executor é alterado. A chave de 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.

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

      - 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 != 'true' }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Test
        run: npm test

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

      - 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 != 'true' }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Test
        run: npm test

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, confira "Contextos" e "Expressões."

O uso de expressões para criar uma key permite que você crie automaticamente um cache quando as dependências são alteradas.

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

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

O GitHub avalia a expressão hash "package-lock.json" para obter a key final.

npm-d5ea0750

Usando a saída da ação cache

Você pode usar a saída da ação cache para fazer algo com base na ocorrência ou na perda no cache. Quando uma correspondência exata é encontrada para um cache do key especificado, a saída cache-hit é definida como true.

No exemplo de fluxo de trabalho acima, há uma etapa que lista o estado dos módulos de nó na ocorrência de uma perda no cache:

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

Corresponder uma chave da cache

A ação cache primeiro pesquisa ocorrências de key no cache e a versão do cache no branch que contém a execução de fluxo de trabalho. Quando não há ocorrências, ela pesquisa restore-keys e a versão. Se ainda não houver ocorrências no branch atual, a ação cache repetirá as mesmas etapas no branch padrão. Observe que as restrições de escopo se aplicam durante a pesquisa. Para saber mais, confira "Restrições de acesso a um cache".

A versão do cache é uma maneira de marcar um cache com metadados de path e a ferramenta de compactação usada durante a criação dele. Isso garante que a execução de fluxo de trabalho de consumo corresponda exclusivamente a um cache que possa realmente descompactar e usar. Para saber mais, confira Versão de cache na documentação do cache de ações.

O restore-keys permite que você especifique uma lista de chaves de restauração alternativas a serem usadas quando houver uma perda no cache na key. Você pode criar múltiplas chaves de restauração ordenadas da mais específica para a menos específica. A ação cache procura o 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 são resolvidas para estas restore-keys:

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

A chave de restauração npm-feature- corresponde a qualquer chave que comece com a cadeia de caracteres npm-feature-. Por exemplo, 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 precedidas com npm-feature-.
3. npm- corresponde a qualquer chave precedida com npm-.

Exemplo de prioridade de pesquisa

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

Por exemplo, se uma solicitação de pull contiver um branch feature e for direcionada ao branch padrão (main), a ação vai procurar key e restore-keys na seguinte ordem:

1. Chave npm-feature-d5ea0750 no branch feature
2. Chave npm-feature- no branch feature
3. Chave npm- no branch feature
4. Chave npm-feature-d5ea0750 no branch main
5. Chave npm-feature- no branch main
6. Chave npm- no branch main

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 para 10 GB. Depois que um repositório atingir seu volume máximo de armazenamento em cache, a política de remoção de cache criará espaço excluindo os caches mais antigos do repositório.

Se você exceder o limite, GitHub salvará o novo cache, mas começará a despejar caches até que o tamanho total seja menor que o limite do repositório. O processo de remoção de cache pode causar sobrecarga nos caches, pois eles são criados e excluídos em alta frequência. Para reduzir isso, revise os caches de um repositório e execute etapas corretivas, como remover o cache de fluxos de trabalho específicos. Para saber mais, confira "Gerenciar caches".

Gerenciando caches

Para gerenciar caches criados por meio de seus fluxos de trabalho, faça o seguinte:

• Exiba uma lista de todas as entradas de cache de um repositório.
• Filtre e classifique a lista de caches usando metadados específicos, como tamanho do cache, hora de criação ou hora do último acesso.
• Exclua as entradas de cache de um repositório.
• Monitore o uso de cache agregado para repositórios e organizações.

Há diversas maneiras de gerenciar os caches de repositórios:

• Usar a interface da Web do GitHub, conforme mostrado abaixo.
• Usar a API REST: Para obter mais informações, confira a documentação da API REST "Cache do GitHub Actions".
• Instalar uma extensão da GitHub CLI para gerenciar os caches por meio da linha de comando. Para saber mais, confira a extensão gh-actions-cache.

Exibir entradas de cache

É possível usar a interface da Web para exibir uma lista das entradas de cache de um repositório. Na lista de cache, é possível ver quanto espaço em disco cada cache está usando, quando os caches foram criados e quando foram usados pela última vez.

1. No GitHub.com, navegue até a página principal do repositório.

2. No nome do repositório, clique em Ações.

   

3. Na barra lateral esquerda, na seção "Gerenciamento", clique em Caches.

4. Revise a lista de entradas de cache do repositório.

   • Para pesquisar as entradas de cache usadas para um branch específico, clique no menu suspenso Branch e selecione um branch. A lista de cache exibirá todos os caches usados para o branch selecionado.
   • Para pesquisar entradas de cache com uma chave de cache específica, use a sintaxe key: key-name no campo Filtrar caches. A lista de cache exibirá os caches de todos os branches em que a chave foi usada.

   

Excluir entradas de cache

Os usuários com acesso write a um repositório podem usar a interface da Web do GitHub para excluir entradas de cache.

1. No GitHub.com, navegue até a página principal do repositório.

2. No nome do repositório, clique em Ações.

   

3. Na barra lateral esquerda, na seção "Gerenciamento", clique em Caches.

4. À direita da entrada de cache que deseja excluir, clique em .

   

Forçar a exclusão de entradas de cache

Os caches têm restrições de escopo de branch em vigor, o que significa que alguns caches têm opções de uso limitadas. Para obter mais informações sobre as restrições do escopo de cache, confira "Memorizar dependências para acelerar os fluxos de trabalho". Se caches limitados a um branch específico estiverem usando um excesso de cota de armazenamento, isso poderá fazer com que os caches do branch default sejam criados e excluídos com alta frequência.

Por exemplo, um repositório pode ter muitas novas solicitações de pull abertas, cada qual com caches próprios restritos a um branch específico. Esses caches podem ocupar a maior parte do armazenamento em cache do repositório em questão. Depois que um repositório atingir seu volume máximo de armazenamento em cache, a política de remoção de cache criará espaço excluindo os caches mais antigos do repositório. Para evitar a eliminação de cache nessa situação, você pode configurar fluxos de trabalho que excluam caches em uma cadência mais rápida do que a política de remoção de cache. Você pode usar a extensão da CLI gh-actions-cache para excluir caches de branches específicos.

Este fluxo de trabalho de exemplo usa gh-actions-cache para excluir até 100 caches criados por uma ramificação depois que uma solicitação pull é fechada.

name: cleanup caches by a branch
on:
  pull_request:
    types:
      - closed

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        
      - name: Cleanup
        run: |
          gh extension install actions/gh-actions-cache
          
          REPO=${{ github.repository }}
          BRANCH="refs/pull/${{ github.event.pull_request.number }}/merge"

          echo "Fetching list of cache key"
          cacheKeysForPR=$(gh actions-cache list -R $REPO -B $BRANCH -L 100 | cut -f 1 )

          ## Setting this to not fail the workflow while deleting cache keys. 
          set +e
          echo "Deleting caches..."
          for cacheKey in $cacheKeysForPR
          do
              gh actions-cache delete $cacheKey -R $REPO -B $BRANCH --confirm
          done
          echo "Done"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Como alternativa, você pode usar a API para listar ou excluir automaticamente todos os caches em sua cadência. Para obter mais informações, confira "Cache do GitHub Actions".