Gerenciar e depurar fluxos de trabalho nas Ações do GitHub

Lembre-se de que seu objetivo é automatizar o processo de compilação e publicação de código para que os recursos sejam atualizados sempre que um desenvolvedor adicionar uma alteração à base de código.

Para implementar esse processo, você aprende a:

• Identifique o evento que disparou um fluxo de trabalho.
• Use os logs de fluxo de trabalho do GitHub Actions.
• Salve e acesse artefatos de compilação.
• Automatize a adição de um rótulo a uma solicitação pull após uma revisão.

Identificar o evento que disparou um fluxo de trabalho

Entender o que desencadeou um fluxo de trabalho de Ações do GitHub é crucial para depurar, auditar e melhorar os pipelines de CI/CD. Os tipos de gatilhos incluem um push para uma ramificação, uma solicitação pull criada ou atualizada, um trabalho agendado ou um despacho manual. Você pode identificar o evento de acionamento examinando a execução do fluxo de trabalho, as alterações do repositório e o problema relacionado ao GitHub ou solicitação pull.

O que é um gatilho de fluxo de trabalho?

Um gatilho de fluxo de trabalho é um evento que faz com que um fluxo de trabalho seja executado. O GitHub suporta vários tipos de gatilhos, incluindo:

• push ou pull_request (com base em alterações de código)
• workflow_dispatch (um gatilho manual)
• schedule (tarefas cron)
• repository_dispatch (sistemas externos)
• Eventos de problema, discussão e solicitação de pull (por exemplo, issues.opened, pull_request.closed)

Identificar o evento desencadeador

Você pode identificar um evento de gatilho de fluxo de trabalho de várias maneiras:

• Utilize a interface de ações do GitHub.

  1. No repositório, selecione a guia Ações .
  2. Selecione uma execução de fluxo de tarefas.

  Um tipo de evento, como push, pull_requestou workflow_dispatch, aparece na parte superior do resumo de execução do fluxo de trabalho.

• Use github.event_name nos logs ou em um fluxo de trabalho.

  • O GitHub expõe dados de contexto durante a execução de um fluxo de trabalho. A github.event_name variável informa qual evento acionou o fluxo de trabalho.

  • Você pode imprimir as informações em uma etapa para depuração:

    -name: Show event trigger
      run: echo "Triggered by ${{ github.event_name }}"
    

• Use os detalhes da execução do fluxo de trabalho:

  • Se inspecionares a execução de fluxos de trabalho através de programação, como por exemplo utilizando uma API, o objeto de execução incluirá uma propriedade event que especifica o gatilho.
  • Você pode encontrar o SHA, o autor e o carimbo de data/hora para rastrear o que causou o acionamento.

Inferir o gatilho a partir de efeitos do repositório

Talvez você não tenha acesso direto à execução do fluxo de trabalho, mas ainda deseja inferir o que disparou a execução do fluxo de trabalho com base na atividade do repositório:

Ao rever carimbos de data/hora, atividade de pull request e histórico de commits, muitas vezes é possível identificar qual ação desencadeou a execução do workflow.

Para resumir como identificar o que desencadeou um fluxo de trabalho:

• Verifique o resumo da execução do fluxo de trabalho na guia Ações .
• Imprima ou faça login github.event_name dentro do fluxo de trabalho para obter visibilidade.
• Compare marcas temporais e a atividade do repositório (commits, pull requests, issues) para determinar o acionador.
• Use todo o event contexto para uma investigação mais profunda.

Essas práticas ajudam a depurar, auditar e melhorar a confiabilidade do fluxo de trabalho em seus pipelines de desenvolvimento e implantação.

Compreender um efeito de fluxo de trabalho lendo seu arquivo de configuração

Para entender os efeitos de um fluxo de trabalho a partir da leitura de seu arquivo de configuração, analise a estrutura e o .yml conteúdo do arquivo armazenado no .github/workflows/.

O arquivo de configuração do fluxo de trabalho especifica as seguintes informações sobre o fluxo de trabalho:

• Quando é executado (na on seção).
• O que faz (em jobs e steps).
• Onde corre (a runs-on secção).
• Por que ele é executado (sua finalidade, como testar, implementar ou analisar o código).
• Como se comporta em condições específicas (ambiente, filtros, lógica).

Interpretar um efeito de fluxo de trabalho

1. Identifique o gatilho.

   Para identificar qual ação iniciou o fluxo de trabalho, consulte a on seção do fluxo de trabalho.

   Por exemplo:

   on:
     push:
       branches: [main]
     pull_request:
       types: [opened, synchronize]
     workflow_dispatch:
   

   Este exemplo de fluxo de trabalho:

   • É executado automaticamente quando o código é enviado para a ramificação principal (push).
   • É executado quando uma solicitação pull é criada ou atualizada (pull_request).
   • Pode ser acionado manualmente por um usuário (workflow_dispatch).

2. Identifique os trabalhos e etapas do fluxo de trabalho.

   Para determinar o que o fluxo de trabalho faz, consulte as seções jobs e steps do fluxo de trabalho.

   Por exemplo:

   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout code
           uses: actions/checkout@v3
         - name: Install dependencies
           run: npm install
         - name: Run tests
           run: npm test
   

   Este exemplo de fluxo de trabalho:

   • Usa um ambiente virtual Linux (runs-on).
   • Verifica o código do repositório (steps>name).
   • Instala dependências do projeto (steps>name).
   • Executa testes automatizados (steps>name).

3. Avalie o objetivo e o resultado do fluxo de trabalho.

   Ao ler o arquivo de configuração, você pode descrever o resultado pretendido do fluxo de trabalho:

   "Este fluxo de trabalho é um pipeline de integração contínua (CI). Ele garante que qualquer novo código enviado por push para o repositório ou enviado por meio de solicitação pull seja testado automaticamente. Se os testes falharem, a interface do usuário do fluxo de trabalho do GitHub exibirá esse resultado para ajudá-lo a manter a qualidade do código."

4. Identifique ou defina recursos opcionais que afetam a forma como o fluxo de trabalho é executado:

   • env define variáveis de ambiente.
   • if Adiciona lógica condicional para executar etapas específicas somente quando os critérios são atendidos.
   • timeout-minutes ou continue-on-error defina a execução do fluxo de trabalho e o tratamento de erros.

Diagnosticar uma execução de fluxo de trabalho com falha

1. No seu repositório, vá para a guia Ações.

2. Encontre a execução com falha (normalmente indicada por um X vermelho).

3. Selecione o fluxo de trabalho com falha para abrir o resumo da execução.

4. Nos logs de fluxo de trabalho, revise o erro.

   1. No resumo da execução, expanda cada trabalho e etapa até encontrar aquele que indica uma falha.

   2. Selecione o trabalho ou etapa para exibir seus logs.

   3. Procure:

      • Mensagens de erro
      • Rastreamentos de pilha
      • Códigos de saída

   Por exemplo, um teste com falha pode mostrar npm ERR! Test failed ou exit code 1.

5. Verifique o arquivo de configuração do fluxo de trabalho.

   Use o .yml arquivo para determinar:

   • O que cada passo estava tentando fazer?
   • Se houver variáveis de ambiente (env) ou condicionais (if) que afetem a execução.
   • Se a falha for devido a uma dependência ausente, erro de sintaxe ou etapa mal configurada.

   Se uma etapa falhar, verifique as seguintes causas:

   • As dependências foram instaladas com êxito na etapa anterior?
   • Os arquivos de teste existem e passam localmente?

Cenários de falha comuns

A tabela a seguir descreve cenários comuns de falha de fluxo de trabalho:

Identificar como acessar logs de fluxo de trabalho no GitHub

1. No seu repositório, vá para a guia Ações.

2. Na lista de fluxos de trabalho, selecione o fluxo de trabalho relevante.

   Por exemplo, se o .yml arquivo tiver o código a seguir, um link intitulado CI Workflow aparecerá na lista:

   name: CI Workflow
   

3. Selecione uma execução específica.

   Na lista de execuções que mostram o status, selecione o carimbo de data/hora ou a mensagem de confirmação da execução específica que você deseja inspecionar.

4. Expanda cada trabalho e etapa.

   A página de resumo da execução exibe os trabalhos conforme definidos no arquivo de fluxo de trabalho, como compilação ou teste:

   1. Selecione um trabalho para expandi-lo.
   2. No âmbito do trabalho, detalhe etapas individuais, como "Instalar dependências" ou "Executar testes".

5. Visualize a saída do log.

   Para exibir a saída completa do log, incluindo registos do console, mensagens de erro e informações de depuração, selecione uma etapa no fluxo de trabalho. Você pode copiar, pesquisar e baixar os logs.

A tabela a seguir resume as etapas executadas para acessar os logs de fluxo de trabalho:

Registos de ação para a compilação

Quando um fluxo de trabalho é executado, ele produz um log que inclui os detalhes do que aconteceu e quaisquer erros ou falhas de teste.

Se ocorrer um erro ou se um teste falhar, um X vermelho em vez de uma marca de seleção verde aparecerá nos logs. Você pode examinar os detalhes do erro ou falha em investigar o que aconteceu.

Trabalhar com artefatos

Quando um fluxo de trabalho produz algo diferente de uma entrada de log, o produto é chamado de artefato . Por exemplo, a compilação Node.js produz um contêiner do Docker que pode ser implantado. O contêiner é um artefato que você pode carregar para o armazenamento usando a ação actions/upload-artifact . Mais tarde, você pode baixar o artefato do armazenamento usando actions/download-artifact.

O armazenamento de um artefato o preserva entre os trabalhos. Cada trabalho usa uma nova instância de uma VM, portanto, você não pode reutilizar o artefato salvando-o na VM. Se você precisar de seu artefato em um trabalho diferente, você pode carregar o artefato para armazenamento em um trabalho e baixá-lo para o outro trabalho.

Armazenamento de artefactos

Os artefatos são armazenados no espaço de armazenamento no GitHub. O espaço é gratuito para repositórios públicos, e algum armazenamento é gratuito para repositórios privados, dependendo da conta. O GitHub armazena seus artefatos por 90 dias.

No trecho de fluxo de trabalho a seguir, observe que na ação actions/upload-artifact@main há um atributo path. O valor desse atributo é o caminho para armazenar o artefato. Neste exemplo, você especifica public/ para carregar tudo em um diretório. Se você queria apenas fazer upload de um único arquivo, use algo como público /mytext.txt.

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

Para baixar o artefato para teste, a compilação deve ser concluída com êxito e carregar o artefato. No código a seguir, você especifica que o trabalho de teste depende do trabalho de compilação.

test:
    needs: build
    runs-on: ubuntu-latest

No trecho de fluxo de trabalho a seguir, você baixa o artefato. Agora, o trabalho de teste pode usar o artefato para teste.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

Para obter mais informações sobre como usar artefatos em fluxos de trabalho, consulte Armazenando dados do fluxo de trabalho como artefatos.

Automatize revisões no GitHub usando fluxos de trabalho

Além de iniciar um fluxo de trabalho por meio de eventos do GitHub como push e pull-request, você pode executar um fluxo de trabalho em uma agenda ou após algum evento fora do GitHub.

Talvez você queira que um fluxo de trabalho seja executado somente depois que um usuário concluir uma ação específica, como depois que um revisor aprovar uma solicitação pull. Para esse cenário, você pode acionar o pull-request-review.

Outra ação que você pode tomar é adicionar um rótulo à solicitação pull. Nesse caso, use a ação pullreminders/label-when-approved-action.

Por exemplo:

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

env No bloco , você define as variáveis de ambiente para a ação. Por exemplo, você pode definir o número de aprovadores necessários para executar o fluxo de trabalho. Neste exemplo, é um. A variável de autenticação secrets.GITHUB_TOKEN é necessária porque a ação deve fazer alterações no repositório adicionando um rótulo. Finalmente, introduza o nome da etiqueta a adicionar.

Adicionar um rótulo pode ser um evento que inicia outro fluxo de trabalho, como uma mesclagem. Abordaremos esse evento no próximo módulo, que descreve o uso da entrega contínua nas Ações do GitHub.