Configurar um fluxo de trabalho do GitHub Actions

  • 10 minutos

Aqui, você aprenderá mais sobre algumas configurações comuns em um arquivo de fluxo de trabalho. Você também explorará as categorias de tipos de evento, desabilitando e excluindo fluxos de trabalho e usando versões específicas de uma ação para as práticas recomendadas de segurança.

Configurar fluxos de trabalho a serem executados para eventos agendados

Conforme mencionado anteriormente, você pode configurar seus fluxos de trabalho para serem executados quando uma atividade específica ocorrer no GitHub, quando um evento fora do GitHub acontecer ou em um horário agendado. O evento schedule permite que você dispare um fluxo de trabalho para ser executado em horários UTC específicos usando a sintaxe cron do POSIX. Essa sintaxe cron possui cinco campos *, e cada campo representa uma unidade de tempo.

Diagram of the five unit-of-time fields for scheduling an event in a workflow file.

Por exemplo, se você quisesse executar um fluxo de trabalho a cada 15 minutos, o evento schedule seria semelhante ao seguinte:

on:
  schedule:
    - cron:  '*/15 * * * *'

E se você quisesse executar um fluxo de trabalho todos os domingos às 3h, o evento schedule seria parecido com o seguinte:

on:
  schedule:
    - cron:  '0 3 * * SUN'

Você também pode usar operadores para especificar um intervalo de valores ou para acesso telefônico a seu fluxo de trabalho agendado. O intervalo mais curto em que você pode executar fluxos de trabalho agendados é uma vez a cada cinco minutos, e eles são executados no commit mais recente no branch padrão ou base.

Configurar fluxos de trabalho a serem executados para eventos manuais

Além dos eventos agendados, você pode disparar manualmente um fluxo de trabalho usando o evento workflow_dispatch. Esse evento permite que você execute o fluxo de trabalho usando a API REST do GitHub ou selecionando o botão Executar fluxo de trabalho na guia Ações em seu repositório no GitHub. Usando workflow_dispatch, você pode escolher em qual branch deseja que o fluxo de trabalho seja executado, bem como definir inputs opcionais que o GitHub apresentará como elementos de formulário na IU.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

Além de workflow_dispatch, você pode usar a API do GitHub para disparar um evento de webhook chamado repository_dispatch. Esse evento permite que você dispare um fluxo de trabalho para atividades que ocorrem fora do GitHub e, essencialmente, serve como uma solicitação HTTP para seu repositório, solicitando que o GitHub dispare um fluxo de trabalho de uma ação ou um webhook. O uso desse evento manual exige que você realize duas tarefas: envie uma solicitação POST para o ponto de extremidade /repos/{owner}/{repo}/dispatches do GitHub com os nomes de evento do webhook no corpo da solicitação e configure seu fluxo de trabalho para usar o evento repository_dispatch.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Configurar fluxos de trabalho a serem executados para eventos de webhook

Por fim, você pode configurar um fluxo de trabalho para ser executado quando eventos de webhook específicos ocorrerem no GitHub. Você pode disparar a maioria dos eventos de webhook de mais de uma atividade para um webhook, portanto, se houver várias atividades para um webhook, você poderá especificar um tipo de atividade para disparar o fluxo de trabalho. Por exemplo, você pode executar um fluxo de trabalho para o evento check_run, mas apenas para os tipos de atividade rerequested ou requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

Usar palavras-chave condicionais

Em seu arquivo de fluxo de trabalho, você pode acessar informações de contexto e avaliar expressões. Embora as expressões sejam comumente usadas com a palavra-chave if condicional em um arquivo de fluxo de trabalho para determinar se uma etapa deve ser executada ou não, você pode usar qualquer contexto e expressão com suporte para criar uma condicional. É importante saber que, ao usar condicionais em seu fluxo de trabalho, você precisa usar a sintaxe específica ${{ <expression> }}, que diz ao GitHub para avaliar uma expressão em vez de tratá-la como uma cadeia de caracteres.

Por exemplo, um fluxo de trabalho que usa a condicional if para verificar se github.ref (o branch ou a marca ref que disparou a execução do fluxo de trabalho) corresponde a refs/heads/main para prosseguir com as etapas seguintes do fluxo de trabalho, seria semelhante a isto:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Observe que, nesse exemplo, os símbolos ${{ }} estão faltando na sintaxe. No caso de algumas expressões, como na condicional if, você pode omitir a sintaxe da expressão. O GitHub avalia automaticamente algumas dessas expressões comuns, mas você sempre pode incluí-las caso esqueça quais expressões o GitHub avalia de forma automática.

Para saber mais sobre sintaxe e expressões de fluxo de trabalho, confira Sintaxe de fluxo de trabalho do GitHub Actions.

Desabilitar e excluir fluxos de trabalho

Depois de adicionar um fluxo de trabalho ao seu repositório, você pode se deparar com uma situação em que deseja desabilitar temporariamente o fluxo. Você pode impedir que um fluxo de trabalho seja disparado sem ter que excluir o arquivo do repositório, seja no GitHub ou por meio da API REST do GitHub. Quando quiser habilitar o fluxo de trabalho novamente, você poderá fazer isso com facilidade usando os mesmos métodos.

Screenshot of disabling a workflow on GitHub.

Desabilitar um fluxo de trabalho pode ser útil em algumas situações, por exemplo:

  • Um erro em um fluxo de trabalho está produzindo solicitações em excesso ou incorretas, impactando negativamente os serviços externos.
  • Você deseja pausar temporariamente um fluxo de trabalho que não é crítico e está consumindo muitos minutos em sua conta.
  • Você deseja pausar um fluxo de trabalho que está enviando solicitações a um serviço inativo.
  • Você está trabalhando em um fork e não precisa de todas as funcionalidades disponíveis dos fluxos de trabalho (como fluxos de trabalho programados).

Você também pode cancelar uma execução de fluxo de trabalho que está em andamento na IU do GitHub na guia Ações ou usando o ponto de extremidade DELETE /repos/{owner}/{repo}/actions/runs/{run_id} da API do GitHub. Lembre-se de que, quando você cancelar uma execução de fluxo de trabalho, o GitHub cancelará todos os seus trabalhos e as etapas nessa execução.

Usar o modelo de fluxo de trabalho de uma organização

Se você tiver um fluxo de trabalho que várias equipes usam em uma organização, em vez de recriar o mesmo fluxo para cada repositório, você poderá promover a consistência em toda a sua organização usando um modelo de fluxo de trabalho definido no repositório .github da organização. Qualquer membro da organização pode usar um modelo de fluxo de trabalho dela, e qualquer repositório da organização tem acesso a esses modelos de fluxo.

Para encontrar esses fluxos de trabalho, navegue até a guia Ações de um repositório dentro da organização, selecione Novo fluxo de trabalho e encontre a seção de modelo de fluxo de trabalho da organização intitulada "Fluxos de trabalho criados por nome da organização". Por exemplo, a organização chamada Mona tem um modelo de fluxo de trabalho, conforme mostrado abaixo.

Screenshot of a template organization workflow called greet and triage by Mona.

Usar versões específicas de uma ação

Ao fazer referência a ações em seu fluxo de trabalho, recomendamos que você se refira a uma versão específica dessa ação, em vez de apenas à própria ação. Ao fazer referência a uma versão específica, você está criando uma proteção contra alterações inesperadas enviadas para a ação que poderiam interromper o fluxo de trabalho. Confira várias maneiras de fazer referência a uma versão específica de uma ação:

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Algumas referências são mais seguras do que outras. Por exemplo, fazer referência a um branch específico executará essa ação nas alterações mais recentes desse branch, o que você pode ou não desejar. Ao fazer referência a um número de versão específico ou confirmar hash de SHA, você está sendo mais específico sobre a versão da ação que está executando. Para obter mais estabilidade e segurança, recomendamos que você use o SHA de commit de uma ação lançada em seus fluxos de trabalho.