Configurar um fluxo de trabalho de Ações do GitHub

10 minutos

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

Configurar fluxos de trabalho para execução de eventos agendados

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

Diagrama dos cinco campos de unidade de tempo para agendar um evento em um arquivo de fluxo de trabalho.

Por exemplo, se você quisesse executar um fluxo de trabalho a cada 15 minutos, o schedule evento teria a seguinte aparência:

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

E se você quisesse executar um fluxo de trabalho todos os domingos às 3h00, o schedule evento ficaria assim:

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

Você também pode usar operadores para especificar um intervalo de valores ou para discar em seu fluxo de trabalho agendado. O intervalo mais curto que você pode executar fluxos de trabalho agendados é uma vez a cada cinco minutos, e eles são executados na confirmação mais recente na ramificação padrão ou base.

Configurar fluxos de trabalho para execução de eventos manuais

Além dos eventos agendados, você pode acionar manualmente um fluxo de trabalho usando o workflow_dispatch evento. 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 dentro do repositório no GitHub. Usando workflow_dispatcho , você pode escolher em qual ramificação deseja que o fluxo de trabalho seja executado, bem como definir opcionalmente inputs que o GitHub apresentará como elementos de formulário na interface do usuário.

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

Além do workflow_dispatch, você pode usar a API do GitHub para disparar um evento webhook chamado repository_dispatch. Esse evento permite que você acione 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 acione um fluxo de trabalho fora de uma ação ou webhook. Usar esse evento manual requer que você faça duas coisas: enviar uma POST solicitação para o ponto de extremidade /repos/{owner}/{repo}/dispatches do GitHub com os nomes de evento do webhook no corpo da solicitação e configurar seu fluxo de trabalho para usar o repository_dispatch evento.

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 para execução de eventos de webhook

Por fim, você pode configurar um fluxo de trabalho para ser executado quando eventos específicos de webhook ocorrerem no GitHub. Você pode acionar a maioria dos eventos de webhook de mais de uma atividade para um webhook, portanto, se existirem várias atividades para um webhook, você poderá especificar um tipo de atividade para acionar o fluxo de trabalho. Por exemplo, você pode executar um fluxo de trabalho para o check_run evento, mas apenas para os rerequested tipos de atividade 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 condicional if 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 suportados para criar uma condicional. É importante saber que, ao usar condicionais em seu fluxo de trabalho, você precisa usar a sintaxe ${{ <expression> }}específica , 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 o if condicional para verificar se o github.ref (a branch ou tag ref que disparou a execução do fluxo de trabalho) corresponde refs/heads/main para prosseguir com as seguintes etapas no fluxo de trabalho teria a seguinte aparência:

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

Observe que, neste exemplo, o ${{ }} estão faltando na sintaxe. Com algumas expressões, como no caso do if condicional, você pode omitir a sintaxe da expressão. O GitHub avalia automaticamente algumas dessas expressões comuns, mas você sempre pode incluí-las caso se esqueça de quais expressões o GitHub avalia automaticamente.

Para obter mais informações sobre sintaxe e expressões do fluxo de trabalho, confira Sintaxe do fluxo de trabalho para ações do GitHub.

Desabilitar e excluir fluxos de trabalho

Depois de adicionar um fluxo de trabalho ao repositório, você pode encontrar uma situação em que deseja desativar temporariamente o fluxo de trabalho. Você pode impedir que um fluxo de trabalho seja acionado sem ter que excluir o arquivo do repositório, seja no GitHub ou por meio da API REST do GitHub. Quando você deseja habilitar o fluxo de trabalho novamente, você pode facilmente fazê-lo usando os mesmos métodos.

Captura de tela mostrando a desativação de um fluxo de trabalho no GitHub.

A desativação de um fluxo de trabalho pode ser útil em algumas situações, por exemplo:

Um erro em um fluxo de trabalho está produzindo muitas solicitações ou solicitações erradas que afetam 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 para um serviço que está inativo.
Você está trabalhando em uma bifurcação e não precisa de todas as funcionalidades de alguns fluxos de trabalho que ela inclui (como fluxos de trabalho agendados).

Você também pode cancelar uma execução de fluxo de trabalho em andamento na interface do usuário 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ê cancela uma execução de fluxo de trabalho, o GitHub cancela todos os seus trabalhos e etapas dentro dessa execução.

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

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

Você pode encontrar esses fluxos de trabalho navegando até a guia Ações de um repositório dentro da organização, selecionando Novo fluxo de trabalho e, em seguida, localizando a seção de modelo de fluxo de trabalho da organização intitulada "Fluxos de trabalho criados pelo nome da organização". Por exemplo, a organização chamada Mona tem um fluxo de trabalho de modelo, conforme mostrado abaixo.

Captura de tela de um fluxo de trabalho de organização de modelo chamado greet and triage por 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 à ação em si. Ao fazer referência a uma versão específica, você está colocando uma proteção contra alterações inesperadas enviadas para a ação que podem potencialmente interromper seu fluxo de trabalho. Aqui estão 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 uma ramificação específica executará essa ação a partir das alterações mais recentes dessa ramificação, que você pode ou não querer. Ao fazer referência a um número de versão específico ou confirmar hash 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 confirmação de uma ação liberada em seus fluxos de trabalho.