Personalizar seu fluxo de trabalho com variáveis de ambiente e dados de artefato

  • 12 minutos

Neste módulo, você aprenderá a usar as variáveis de ambiente padrão e personalizadas, scripts personalizados, dependências de cache e passar dados de artefato entre trabalhos. Você também aprenderá a acessar os logs de fluxo de trabalho do site do GitHub e dos pontos de extremidade da API REST.

Variáveis de ambiente e contextos padrão

No fluxo de trabalho do GitHub Actions, há muitas variáveis de ambiente padrão disponíveis para uso, mas somente dentro do executor de um trabalho. Essas variáveis padrão diferenciam maiúsculas e minúsculas e se referem aos valores de configuração do sistema e do usuário atual. Recomendamos que você use essas variáveis de ambiente padrão para fazer referência ao sistema de arquivos em vez de usar caminhos de arquivo embutidos em código. Para usar uma variável de ambiente padrão, especifique $ seguido pelo nome da variável de ambiente.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Além das variáveis de ambiente padrão, você pode usar variáveis definidas como contextos. Contextos e variáveis padrão são semelhantes, pois ambos fornecem acesso a informações de ambiente, mas têm algumas diferenças importantes. Embora as variáveis de ambiente padrão possam ser usadas apenas dentro do executor, as variáveis de contexto podem ser usadas em qualquer ponto do fluxo de trabalho. Por exemplo, as variáveis de contexto permitem que você execute uma instrução if para avaliar uma expressão antes de executar o executor.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Este exemplo está usando o contexto github.ref para verificar o branch que disparou o fluxo de trabalho. Se o branch for main, o executor será executado e imprimirá "Implantando no servidor de produção no branch $GITHUB _REF". A variável de ambiente padrão $GITHUB_REF é usada no executor para se referir ao branch. Observe que as variáveis de ambiente padrão são todas maiúsculas, já as variáveis de contexto são todas minúsculas.

Variáveis de ambiente personalizadas

Semelhante ao uso de variáveis de ambiente padrão, você pode usar variáveis de ambiente personalizadas em seu arquivo de fluxo de trabalho. Para criar uma variável personalizada, você precisa defini-la no arquivo de fluxo de trabalho usando o contexto env. Se você quiser usar o valor de uma variável de ambiente dentro de um executor, poderá usar o método normal do sistema operacional do executor para ler as variáveis de ambiente.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

Scripts em seu fluxo de trabalho

Nos exemplos de snippet de fluxo de trabalho anteriores, a palavra-chave run é usada para simplesmente imprimir uma cadeia de texto. Como a palavra-chave run avisa ao trabalho para executar um comando no executor, você usa a palavra-chave run para executar ações ou scripts.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

Neste exemplo, você estará usando o npm para instalar o pacote de teste de software bats usando a palavra-chave run. Você também pode executar um script como uma ação. Você pode armazenar o script em seu repositório, geralmente feito em um diretório .github/scripts/ e, em seguida, fornecer o caminho e o tipo de shell usando a palavra-chave run.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash

Dependências de cache com a ação de cache

Ao criar um fluxo de trabalho, muitas vezes você encontrará a necessidade de reutilizar as mesmas saídas ou baixar dependências de uma execução para outra. Em vez de baixar essas dependências repetidamente, você pode armazená-las em cache para fazer com que seu fluxo de trabalho seja executado de forma mais rápida e eficiente. Isso pode reduzir drasticamente o tempo necessário para executar determinadas etapas em um fluxo de trabalho, pois os trabalhos em executores hospedados pelo GitHub começam em um ambiente virtual limpo a cada vez. As dependências de cache ajudarão a acelerar o tempo necessário para recriar esses arquivos de dependência.

Para armazenar em cache as dependências de um trabalho, use a ação cache do GitHub Actions. Essa ação recupera um cache identificado por uma chave exclusiva que você fornece. Quando a ação encontra o cache, ele recupera os arquivos armazenados em cache para o caminho que você configurar. Para usar a ação cache, você precisará definir alguns parâmetros específicos:

Parâmetro Descrição Obrigatório
Chave Refere-se ao identificador de chave criado ao salvar e pesquisar um cache. Sim
Caminho Refere-se ao caminho do arquivo no executor para armazenar em cache ou pesquisar. Sim
Chaves de restauração consiste em chaves existentes alternativas para armazenar em cache se a chave de cache desejada não for encontrada. No 
steps:
  - uses: actions/checkout@v2

  - name: Cache NPM dependencies
    uses: actions/cache@v2
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-cache-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-cache-

No exemplo anterior, o path é definido como ~/.npm e a key inclui o sistema operacional do executor e o hash SHA-256 do arquivo package-lock.json. A prefixação da chave com uma ID (npm-cache, neste exemplo) é útil quando você usa o restore-keys fallback e tem vários caches.

Passar dados de artefato entre trabalhos

Semelhante ao contexto de armazenar em cache dependências em seu fluxo de trabalho, você pode passar dados entre trabalhos dentro do mesmo fluxo de trabalho. É possível fazer isso usando as ações upload-artifact e download-artifact. Trabalhos que dependem dos artefatos de um trabalho anterior devem aguardar a conclusão bem-sucedida deste trabalho anterior antes de poderem ser executados. Isso será útil se você tiver uma série de trabalhos que precisam ser executados sequencialmente com base em artefatos carregados de um trabalho anterior. Por exemplo, job_2 requer o job_1 usando a sintaxe do needs: job_1.

name: Share data between jobs
on: push
jobs:
  job_1:
    name: Upload File
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello World" > file.txt
      - uses: actions/upload-artifact@v2
        with:
          name: file
          path: file.txt

  job_2:
    name: Download File
    runs-on: ubuntu-latest
    needs: job_1
    steps:
      - uses: actions/download-artifact@v2
        with:
          name: file
      - run: cat file.txt

O exemplo anterior tem dois trabalhos. O job_1 grava texto no arquivo file.txt e, em seguida, usa a ação actions/upload-artifact@v2 para carregar esse artefato e armazenar os dados para uso futuro no fluxo de trabalho. O job_2 requer a conclusão de job_1 usando a sintaxe needs: job_1 e usa a ação actions/download-artifact@v2 para baixar esse artefato e depois imprimir o conteúdo de file.txt.

Habilitar log de depuração de etapa em um fluxo de trabalho

Em alguns casos, o log de fluxo de trabalho padrão não fornecerá detalhes suficientes para diagnosticar o motivo de falha da execução de um fluxo de trabalhos específico, da tarefa ou da etapa. Para essas situações, você pode habilitar o log de depuração adicional para duas opções: execuções e etapas. Habilite esse log de diagnósticos definindo dois segredos de repositório que requerem acesso de admin ao repositório para true:

  • Para habilitar o log de diagnóstico do executor, defina o segredo ACTIONS_RUNNER_DEBUG no repositório que contém o fluxo de trabalho como true.
  • Para habilitar o log de diagnóstico de etapa, defina o segredo ACTIONS_STEP_DEBUG no repositório que contém o fluxo de trabalho como true.

Acessar os logs de fluxo de trabalho da interface do usuário

Quando se pensa em automação bem-sucedida, o objetivo é gastar o menor tempo examinando o que é automatizado para que se possa concentrar a atenção no que é relevante. Mas, às vezes, as coisas não funcionam como planejado, e você precisa examinar o que aconteceu. Esse processo de depuração pode ser frustrante, mas o GitHub fornece uma estrutura de layout clara que permite uma maneira rápida de navegar entre os trabalhos, mantendo o contexto da etapa de depuração atual. Para exibir os logs de uma execução de fluxo de trabalho no GitHub, você pode seguir estas etapas:

  1. Navegue até a guia Ações em seu repositório.
  2. Na barra lateral esquerda, clique no fluxo de trabalho desejado.
  3. Na lista de execuções de fluxo de trabalho, selecione a execução desejada.
  4. Em Trabalhos, selecione o trabalho desejado.
  5. Leia a saída do log.

Se você tiver várias execuções em um fluxo de trabalho, também poderá selecionar o filtro de Status depois de escolher o fluxo de trabalho e defini-lo como Falha para exibir apenas as execuções com falha dentro desse fluxo de trabalho.

Acessar os logs de fluxo de trabalho da API REST

Além de exibir logs usando o GitHub, você também pode usar a API REST do GitHub para exibir logs de execuções de fluxo de trabalho, executar fluxos de trabalho novamente ou até mesmo cancelar execuções de fluxo de trabalho. Para exibir o log de uma execução de fluxo de trabalho usando a API, você precisa enviar uma solicitação GET para o ponto de extremidade de logs. Tenha em mente que qualquer pessoa com acesso de leitura ao repositório pode usar esse ponto de extremidade. Se o repositório for privado, você deverá usar um token de acesso com o escopo repo.

Por exemplo, uma solicitação GET para exibir um log de execução de fluxo de trabalho específico seguiria este caminho:

GET /repos/{owner}/{repo}/actions/runs/{run_id}/logs