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

Aqui, você aprende algumas configurações comuns em um arquivo de fluxo de trabalho. Você também explora 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.

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

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_dispatch, pode escolher em que ramificação deseja que o fluxo de trabalho seja executado e configurar opcionalmente inputs que o GitHub apresenta como elementos de formulário na interface do utilizador.

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. Ele serve essencialmente como uma solicitação HTTP para o seu repositório pedindo ao GitHub para acionar um fluxo de trabalho a partir 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. 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]

Despacho_de_repositório

repository_dispatch é um evento personalizado no GitHub Actions que permite que sistemas externos (ou até mesmo outros fluxos de trabalho do GitHub) acionem manualmente fluxos de trabalho enviando uma solicitação POST para a API do GitHub. Ele permite automação flexível e integração com ferramentas, scripts ou sistemas externos que precisam iniciar fluxos de trabalho em seu repositório.

Casos de uso

• Acione fluxos de trabalho a partir de ferramentas externas de CI/CD.

• Coordene implantações multi-repo (por exemplo, o Repo A conclui a compilação → aciona o Repo B).

• Inicie a automação com base em eventos externos (webhooks, alertas de monitoramento, trabalhos CRON fora do GitHub).

• Encadeie execuções de fluxo de trabalho entre repositórios ou dentro de monorepos.

Exemplo de fluxo de trabalho que escuta repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Elementos-chave:

• tipos: Opcional. Define tipos de eventos personalizados como run-tests, deploy-to-prod, etc.

• github.event.client_payload: Acesso a quaisquer outros dados personalizados passados no evento de despacho.

• github.event.action: Nome do tipo_de_evento enviado.

Acionando o evento via API

Você deve enviar uma solicitação POST para o ponto de extremidade da API REST v3 do GitHub:

POST https://api.github.com/repos/OWNER/REPO/dispatches

Autorização

• Requer um token de acesso pessoal (PAT) com escopo de repositório.
• Para organizações, garanta configurações de acesso adequadas para seu token.

Exemplo de estrutura de comando

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Estrutura da carga útil

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Parâmetros

Campo	Tipo	Descrição	Obrigatório
event_type	cadeia (de caracteres)	Um nome personalizado para o evento. Este nome corresponde ao valor de tipos no gatilho do fluxo de trabalho	Sim
client_payload	objecto	Carga JSON arbitrária para enviar dados personalizados para o fluxo de trabalho (github.event.client_payload)	Não

Especificação dos parâmetros do Repository_dispatch

Ao fazer uma solicitação POST para o ponto de extremidade da API do GitHub, você deve passar um corpo JSON com dois parâmetros principais:

• tipo_de_evento
• client_payload

tipo_de_evento

Uma cadeia de caracteres personalizada necessária que você define. O GitHub trata esse valor como a "ação" ou "tipo" do despacho. Ele é usado para identificar o que acionou o fluxo de trabalho e filtrar fluxos de trabalho que estão escutando tipos específicos.

• Formato:

  • Tipo: string
  • Exemplo: "deploy", "run-tests", "sync-db", "build-docker"

• Uso no fluxo de trabalho: usado na escuta de tipos de eventos específicos e no acesso ao valor dentro do fluxo de trabalho. Isso ajuda na reutilização de um único fluxo de trabalho para várias finalidades e torna a automação mais organizada e orientada a eventos.

• Exemplo:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

Um objeto JSON de forma livre que permite enviar dados personalizados junto com o despacho. Você define a estrutura e ela fica acessível dentro do fluxo de trabalho.

• Formato:

  • Tipo: objeto
  • Chaves e valores personalizados

• Uso no fluxo de trabalho: este objeto é usado para implantações em vários ambientes, lançamentos versionados ou passagem de contexto de outro sistema ou pipeline e permite fluxos de trabalho parametrizados, de maneira semelhante a argumentos de entrada.

• Exemplo:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

Exemplo de desagregação da carga útil

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

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. Essa sintaxe 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 if condicional para verificar se a github.ref (a ramificação ou tag ref que disparou a execução do fluxo de trabalho) corresponde refs/heads/mainao . Para continuar, o 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 a 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.

A desativação de um fluxo de trabalho pode ser útil em algumas das seguintes situações:

• 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 em uma organização, não precisará recriar o mesmo fluxo de trabalho para cada repositório. Em vez disso, você pode 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 aqui.

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 executa 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.