Gerenciar e depurar fluxos de trabalho no GitHub Actions

10 minutos

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

Para implementar esse processo, você aprenderá a:

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

Identificar o evento que disparou um fluxo de trabalho

Entender o que disparou um fluxo de trabalho do GitHub Actions é crucial para depurar, auditar e melhorar pipelines de CI/CD. Os tipos de gatilhos incluem um push para um branch, um pull request criado ou atualizado, um trabalho agendado ou uma expedição manual. Você pode identificar o evento de gatilho examinando a execução do fluxo de trabalho, as alterações do repositório e a solicitação de pull ou problema do GitHub relacionado.

Diagrama que mostra vários gatilhos de fluxo de trabalho no GitHub Actions, como push, solicitação de pull, agendamento e expedição manual.

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 dá suporte a vários tipos de gatilhos, incluindo:

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

Identificar o evento de gatilho

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

Utilize a interface de usuário do GitHub Actions:
1. No repositório, selecione a guia Ações .
2. Selecione uma rodada de fluxo de trabalho.
Um tipo de evento, como push, pull_requestou workflow_dispatch, aparece na parte superior do resumo da 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 uma execução de fluxo de trabalho. A github.event_name variável informa qual evento disparou 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 você inspecionar as execuções de fluxo de trabalho programaticamente, como usando a API, o objeto de execução incluirá uma event propriedade que especifica o gatilho.
- Você pode encontrar o SHA (Algoritmo de Hash Seguro de Confirmação), o ator e o carimbo de data/hora para rastrear o que causou o gatilho.

Inferir o gatilho a partir dos 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:

Comportamento observado	Evento desencadeador
Um novo commit foi enviado por push para `main` e o fluxo de trabalho foi executado.	evento `push`
Uma solicitação de pull foi aberta ou atualizada.	evento `pull_request`
Um colaborador executou manualmente um fluxo de trabalho.	`workflow_dispatch`
O fluxo de trabalho é executado diariamente em um momento específico.	`schedule` (cron)
O fluxo de trabalho foi executado após uma chamada de serviço externo.	`repository_dispatch`
O fluxo de trabalho foi executado quando um rótulo ou comentário foi adicionado a um problema.	evento `issues.*`

Examinando carimbos de data/hora, atividade de pull request e histórico de confirmação, muitas vezes você pode identificar qual ação causou a execução do fluxo de trabalho.

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

Verifique o resumo da execução do fluxo de trabalho na guia Ações .
Imprima ou registre um log github.event_name no fluxo de trabalho para maior clareza.
Compare os carimbos de data/hora e a atividade do repositório (confirmações, pull requests, problemas) para inferir o gatilho.
Use o contexto completo event para uma investigação mais profunda.

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

Entender 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 do arquivo de configuração, analise a estrutura e o conteúdo do arquivo .yml armazenado em .github/workflows/.

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

Quando ele é executado (na seção on).
O que isso faz dentro de jobs e steps.
Onde ele é executado (a seção runs-on).
Por que ele é executado (sua finalidade, como testar, implantar ou lint).
Como ele se comporta em condições específicas (ambiente, filtros, lógica).

Interpretar o efeito de um fluxo de trabalho

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 por push para o branch principal (push).
- É executado quando uma solicitação de pull é criada ou atualizada (pull_request).
- Pode ser disparado manualmente por um usuário (workflow_dispatch).
Identifique os trabalhos e as 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 do Linux (runs-on).
- Verifica o código do repositório (steps>name).
- Instala dependências de projeto (steps>name).
- Executa testes automatizados (steps>name).
Avalie a finalidade e o resultado do fluxo de trabalho.

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

"Esse fluxo de trabalho é um pipeline de CI (integração contínua). Ele garante que qualquer novo código que seja enviado por push para o repositório ou enviado por meio da solicitação de 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."
Identifique ou defina recursos opcionais que afetam a execução do fluxo de trabalho:
- 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

No seu repositório, vá até a aba Ações.
Localize a execução com falha (normalmente indicada por um X vermelho).
Selecione o fluxo de trabalho com falha para abrir o resumo da execução.
Nos logs do fluxo de trabalho, revise o erro.
1. No resumo da execução, expanda cada trabalho e etapa até encontrar o que indica falha.
2. Selecione o trabalho ou a etapa para exibir seus logs.
3. Procurar por:
  - 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.
Verifique o arquivo de configuração do fluxo de trabalho.

Use o .yml arquivo para determinar:
- O que cada etapa estava tentando fazer?
- Se houver variáveis de ambiente (env) ou condicionais (if) que afetam a execução.
- Se a falha for devido a uma dependência ausente, erro de sintaxe ou etapa configurada incorretamente.
Se uma etapa falhar, verifique as seguintes causas:
- As dependências foram instaladas com êxito na etapa anterior?
- Os arquivos de teste existem e são aprovados localmente?

Cenários comuns de falha

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

Sintoma	Causa provável
Uma etapa falha e retorna `command not found`l	Dependência ausente ou configuração incorreta
`npm install` falha.	Arquivo corrompido `package-lock.json` ou um problema de rede
Falha em uma etapa de teste	Problemas de teste de unidade, arquivo de configuração ausente ou sintaxe de teste inválida
`Permission denied` aparece.	Permissões de arquivo incorretas ou segredos ausentes

Identificar como acessar logs de fluxo de trabalho no GitHub

No seu repositório, vá até a aba Ações.
Na lista de fluxos de trabalho, selecione o fluxo de trabalho relevante.

Por exemplo, se o .yml arquivo tiver o seguinte código, um link intitulado Fluxo de Trabalho ci aparecerá na lista:
```
name: CI Workflow
```
Selecione uma execução específica.

Na lista de execuções que exibem o status, selecione a data e hora ou a mensagem de confirmação da execução específica que você deseja inspecionar.
Expanda cada tarefa e etapa.

A página de resumo de execução exibe trabalhos conforme eles são definidos no arquivo de fluxo de trabalho, como build ou teste:
1. Selecione um trabalho para expandi-lo.
2. Dentro do trabalho, expanda etapas individuais, como "Instalar dependências" ou "Executar testes".
Exibir a saída do log.

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

A tabela a seguir resume as etapas que você toma para acessar logs de fluxo de trabalho:

Ação	Propósito
Guia ações	Exibir todas as execuções de fluxo de trabalho.
Selecione o nome do fluxo de trabalho	Filtrar execuções por fluxo de trabalho.
Selecionar uma execução	Veja os resultados específicos da tarefa e do processo.
Expandir etapas	Exibir logs detalhados.
Baixar logs	Baixe logs para solução de problemas offline ou de equipe.

Logs de ações da 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 será exibido nos logs. Você pode examinar os detalhes do erro ou falha ao investigar o que aconteceu.

Captura de tela do log do GitHub Actions com detalhes sobre um teste com falha.

Trabalhar com artefatos

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

Armazenar um artefato o preserva entre trabalhos. Cada trabalho usa uma nova instância de uma VM, para que você não possa reutilizar o artefato salvando-o na VM. Se você precisar do artefato em um trabalho diferente, poderá carregar o artefato no armazenamento em um trabalho e baixá-lo para o outro trabalho.

Armazenamento de artefatos

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 snippet 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 fazer upload de tudo em um diretório. Se você quiser carregar apenas 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, o build deve ser concluído com êxito e fazer upload do artefato. No código a seguir, você especifica que o trabalho de teste depende do trabalho de build.

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

No trecho do 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 Armazenar dados de fluxo de trabalho como artefatos.

Automatizar 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 um agendamento 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 de pull. Para esse cenário, você pode disparar em pull-request-review.

Outra ação que você pode executar é adicionar um rótulo à solicitação de 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 secrets.GITHUB_TOKEN variável de autenticação é necessária porque a ação deve fazer alterações no repositório adicionando um rótulo. Por fim, insira o nome do rótulo a ser adicionado.

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 no GitHub Actions.

Comentários

Esta página foi útil?