Configurar disparadores de pipeline

Um disparador é o que inicia um pipeline. Cada um é um nó no canvas, largado a partir da secção Gatilhos da biblioteca de nós. Selecionar esse nó abre o respetivo inspetor à direita — não existe uma lista de disparadores sempre visível, nem um separador de disparadores, nem um ecrã de disparadores.

Abrir um inspetor de disparador

Aceda a Definições → Espaço de trabalho → Modelos de pipeline.
Clique no lápis na linha do modelo para abrir o editor.
Selecione um nó de disparador no canvas. O painel direito aparece com as definições desse disparador. Sem nada selecionado, o painel fica oculto.

Adicionar um disparador

A secção Gatilhos da biblioteca de nós lista cada tipo de início como um nó próprio: manual, programação, webhook e um cartão por cada evento de domínio. Pesquise por merged, ticket ou pelo nome do tipo (PrMerged) e arraste o cartão para o canvas. Um modelo novo também mostra um mosaico fantasma Adicionar um gatilho na âncora de entrada — escolha a partir da mesma lista pesquisável.

O disparador é inserido de imediato. Os novos disparadores automáticos ficam desativados para que um largar não dispare uma execução antes de o ter configurado. Use o interruptor Ativado do inspetor para o ativar, ou o ícone do caixote para o eliminar.

Permitir execuções manuais

Largue Execução manual (ou escolha-o a partir do mosaico fantasma) e ative Ativado no respetivo inspetor. É isso que faz o modelo aparecer no seletor de execuções. Não é um caso especial — o interruptor escreve uma linha de disparador comum cujo tipo de evento é manual. Persiste de imediato; não há nada para guardar.

O mesmo interruptor está por trás de Execução manual no cabeçalho do editor, onde fica ao lado das entradas declaradas do modelo.

Num evento

Estes eventos iniciam uma execução:

Etiqueta no seletor	Evento
PR externa aberta	`ExternalPrDetected`
PR publicada	`PullRequestPublished`
Status da PR alterado	`PullRequestStatusChanged`
PR fundida	`PrMerged`
Mensagem recebida	`MessageReceived`
Ticket criado	`TicketCreated`
Status do ticket alterado	`TicketStatusChanged`
Ticket atribuído	`TicketAssigned`
Tarefa concluída	`TicketCompleted`
Tarefa falhou	`TicketFailed`
Tarefa cancelada	`TicketCancelled`
Limite de orçamento ultrapassado	`BudgetThresholdCrossed`
Repositório adicionado	`RepoAdded`
Gravação da reunião interrompida	`MeetingRecordingStopped`
Habilidade atualizada	`SkillUpdated`
Espaço excluído	`SpaceDeleted`

SpaceDeleted é o evento que o pipeline incorporado de limpeza de worktrees escuta: transporta o id do espaço eliminado, pelo que a execução recupera exatamente os worktrees desse espaço em vez de varrer todo o espaço de trabalho.

Para conhecer as chaves de payload que cada evento transporta, consulte a referência de eventos de domínio.

Filtrar um disparador de evento

Selecione o nó Status da PR alterado. As etiquetas de estado do inspetor são o único filtro que a interface consegue criar. Clique em qualquer uma de merged, closed, approved, opened, reopened; o disparador só dispara quando o status do evento corresponde a uma delas. Deixar todas as etiquetas por selecionar significa que não há filtro.

Não existe um campo de filtro JSON de forma livre. Uma chave de filtro que o payload do evento não transporta nunca corresponde, pelo que não crie um à mão com base numa chave que não confirmou na referência de eventos de domínio.

Numa programação

Selecione o nó Programação para editar quando é que ele dispara. Os campos do inspetor persistem tal como os deixa:

Campo	Descrição
Agendamento (cron ou every:segundos)	Uma expressão cron de cinco campos, como `0 9 * * 1`, ou um intervalo, como `every:86400`. Um número simples é convertido para `every:<n>`.
Fuso horário (opcional)	Uma zona IANA, como `Europe/Paris`. Predefinição: UTC.
Em execuções perdidas	O que fazer com os disparos perdidos enquanto o servidor esteve em baixo: Executar uma vez agrega todas as ocorrências perdidas num único disparo ao reiniciar (a predefinição); Ignorar retoma na próxima ocorrência futura.

A linha de resumo do mosaico do canvas só explicita o intervalo para o formato every:<seconds>; uma expressão cron aparece apenas como «Programação».

Através de um webhook

Largar Webhook gera um token aleatório. Selecione o nó para copiar o caminho POST /webhooks/<token> a partir do inspetor.

O token é também o segredo HMAC: o pedido tem de transportar X-Hub-Signature-256: sha256=<hex>, em que o hex é HMAC-SHA256(body, token). Uma entrega que falhe a verificação é rejeitada e registada e não pode ser reproduzida. Os duplicados são ignorados pela respetiva chave de deduplicação.

Cada início é o seu próprio nó do grafo. Puxar uma ligação a partir de Programação liga apenas a Programação; Execução manual pode seguir um caminho diferente (por exemplo, um nó de condição) antes de se juntar ao mesmo trabalho. Uma execução entra no início que corresponde ao seu tipo de evento e ignora os subgrafos que pertencem aos outros inícios.

Como um disparador chega a uma execução

Um disparador ativado cujo tipo de evento e filtro correspondam ambos inicia uma execução com o payload do evento como payload de disparo da execução — é contra isso que {{key}} num prompt ou script de um passo é resolvido. Os eventos que transportam uma chave natural são deduplicados, pelo que o mesmo evento disparar duas vezes não inicia duas execuções.

Um modelo desativado é recusado mesmo que o respetivo disparador corresponda. Oito dos treze modelos incorporados vêm desativados, pelo que os respetivos disparadores iniciais disparam para o vazio até ativar o modelo.

Padrões úteis

Condicionar apenas o caminho manual — encaminhe Execução manual através de um nó de condição e ligue Programação diretamente ao trabalho. Cada início é dono das suas próprias ligações.
Rever cada nova PR — evento PR publicada no modelo pr_review.
Limpar após um merge — evento Status da PR alterado, filtrado por merged / closed / approved. O modelo incorporado pr_merged_cleanup já escuta desta forma, além de ticket concluído/cancelado, SpaceDeleted e uma programação diária que é ativada à força em cada recriação dos dados iniciais, por se tratar de recolha de lixo.
Varredura noturna — programação 0 2 * * * com um fuso horário, num modelo cujo primeiro nó é um script bash.
Reagir a um sistema externo — um disparador de webhook, em que o sistema que chama assina o corpo do pedido conforme acima.