Personalize seu fluxo de trabalho com variáveis de ambiente e dados de artefatos

  • 12 minutos

Aqui, você aprenderá a usar 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á como acessar os logs de fluxo de trabalho do site do GitHub e dos pontos de extremidade da API REST.

Variáveis e contextos de ambiente padrão

Dentro do fluxo de trabalho de Ações do GitHub, há várias variáveis de ambiente padrão que estão disponíveis para uso, mas apenas no corredor que está executando um trabalho. Essas variáveis padrão diferenciam maiúsculas de minúsculas e se referem a valores de configuração para o sistema e para o 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 codificados. 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 na medida em que ambos fornecem acesso a informações de ambiente, mas têm algumas diferenças importantes. Enquanto as variáveis de ambiente padrão só podem ser usadas dentro do corredor, as variáveis de contexto podem ser usadas em qualquer ponto dentro do fluxo de trabalho. Por exemplo, as variáveis de contexto permitem executar uma if instrução para avaliar uma expressão antes que o corredor seja executado.

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 github.ref contexto para verificar a ramificação que disparou o fluxo de trabalho. Se a ramificação for main, o runner será executado e imprimirá "Implantando no servidor de produção na ramificação $GITHUB_REF". A variável $GITHUB_REF de ambiente padrão é usada no corredor para se referir à ramificação. Observe que as variáveis de ambiente padrão são todas maiúsculas, onde 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 em seu arquivo de fluxo de trabalho usando o env contexto. Se você quiser usar o valor de uma variável de ambiente dentro de um corredor, você pode usar o método normal do sistema operacional do corredor para ler 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 no seu fluxo de trabalho

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

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

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

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 tornar seu fluxo de trabalho executado com mais rapidez e eficiência. Isso pode reduzir drasticamente o tempo necessário para executar determinadas etapas em um fluxo de trabalho, porque os trabalhos em corredores hospedados no 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 dependências de um trabalho, use a ação do cache GitHub. Esta ação recupera um cache identificado por uma chave exclusiva que você fornece. Quando a ação localiza o cache, ela recupera os arquivos armazenados em cache para o caminho que você configura. Para usar a cache ação, 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 procurar um cache. Sim
Caminho Refere-se ao caminho do arquivo no corredor para armazenar em cache ou pesquisar. Sim
Chaves de restauração consiste em chaves existentes alternativas para caches se a chave de cache desejada não for encontrada. Não 
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 inclui key o sistema operacional do corredor e o hash SHA-256 do package-lock.json arquivo. O prefixo da chave com um ID (npm-cache neste exemplo) é útil quando você está usando o restore-keys fallback e tem vários caches.

Passar dados de artefato entre trabalhos

Semelhante à ideia de armazenar dependências em cache em seu fluxo de trabalho, você pode passar dados entre trabalhos dentro do mesmo fluxo de trabalho. Você pode fazer isso usando as upload-artifact ações e download-artifact . Os trabalhos que dependem dos artefatos de um trabalho anterior devem aguardar a conclusão bem-sucedida do trabalho anterior antes de poderem ser executados. Isso é ú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 job_1 usando a needs: job_1 sintaxe.

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. job_1 Grava algum texto no arquivo file.txt e, em seguida, usa a actions/upload-artifact@v2 ação para carregar esse artefato e armazenar os dados para uso futuro no fluxo de trabalho. job_2 requer job_1 concluir usando a needs: job_1 sintaxe, em seguida, usa a actions/download-artifact@v2 ação para baixar esse artefato e, em seguida, imprimir o conteúdo de file.txt.

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

Em alguns casos, os logs de fluxo de trabalho padrão não fornecerão detalhes suficientes para diagnosticar por que uma execução, tarefa ou etapa específica do fluxo de trabalho falhou. 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óstico definindo dois segredos do repositório que exigem admin acesso ao repositório para true:

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

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

Quando você pensa em automação bem-sucedida, você pretende passar a menor quantidade de tempo olhando para o que é automatizado para que você possa focar sua atenção no que é relevante. Mas, às vezes, as coisas não saem como planejado e você precisa rever 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 um fluxo de trabalho executado no GitHub, você pode seguir estas etapas:

  1. Navegue até a guia Ações no 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 Status depois de escolher seu 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 a partir da API REST

Além de visualizar logs usando o GitHub, você também pode usar a API REST do GitHub para exibir logs para execuções de fluxo de trabalho, reexecutar fluxos de trabalho ou até mesmo cancelar execuções de fluxo de trabalho. Para exibir o log de execução de um fluxo de trabalho usando a API, você precisa enviar uma GET solicitação para o ponto de extremidade de logs. Lembre-se de 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 repo escopo.

Por exemplo, uma GET solicitação 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