Configurar gatilhos de pipeline

Um gatilho é o que inicia um pipeline. Cada um é um nó no canvas, arrastado da seção Gatilhos da biblioteca de nós. Selecionar esse nó abre o inspetor dele à direita — não existe uma lista de gatilhos sempre visível, nem uma aba de gatilhos, nem uma tela de gatilhos.

Abrir o inspetor de um gatilho

Acesse Configurações → Espaço de trabalho → Modelos de pipeline.
Clique no lápis na linha do modelo para abrir o editor.
Selecione um nó de gatilho no canvas. O painel direito aparece com as configurações desse gatilho. Com nada selecionado, o painel fica oculto.

Adicionar um gatilho

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

O gatilho é inserido imediatamente. Gatilhos automáticos novos começam desabilitados, para que soltar um não dispare uma execução antes de você configurá-lo. Use o interruptor Ativado do inspetor para ligá-lo, ou o ícone de lixeira para excluí-lo.

Permitir execuções manuais

Arraste Execução manual (ou escolha-o no bloco fantasma) e ligue Ativado no inspetor dele. É isso que faz o modelo aparecer no seletor de execuções. Não é um caso especial — o interruptor grava uma linha de gatilho comum cujo tipo de evento é manual. Ele persiste imediatamente; não há nada para salvar.

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.

Em um evento

Estes eventos iniciam uma execução:

Rótulo no seletor	Evento
PR externa aberta	`ExternalPrDetected`
PR publicada	`PullRequestPublished`
Status da PR alterado	`PullRequestStatusChanged`
PR mesclada	`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 integrado de limpeza de worktrees escuta: ele carrega o id do espaço excluído, então a execução recupera exatamente os worktrees daquele espaço em vez de varrer todo o espaço de trabalho.

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

Filtrar um gatilho de evento

Selecione o nó Status da PR alterado. Os chips de status do inspetor são o único filtro que a interface consegue criar. Toque em qualquer um de merged, closed, approved, opened, reopened; o gatilho então dispara apenas quando o status do evento corresponde a um deles. Deixar todos os chips sem seleção significa nenhum filtro.

Não existe um campo de filtro JSON de formato livre. Uma chave de filtro que o payload do evento não carrega nunca corresponde, então não crie uma à mão com base em uma chave que você não confirmou na referência de eventos de domínio.

Em um agendamento

Selecione o nó Programação para editar quando ele dispara. Os campos do inspetor são salvos conforme você 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 sem mais nada é convertido para `every:<n>`.
Fuso horário (opcional)	Uma zona IANA como `Europe/Paris`. O padrão é UTC.
Em execuções perdidas	O que fazer com os disparos perdidos enquanto o servidor estava fora do ar: Executar uma vez agrupa todos os horários perdidos em um único disparo na reinicialização (o padrão), Ignorar retoma no próximo horário futuro.

A linha de resumo do cartão no canvas só detalha o intervalo para a forma every:<seconds>; uma expressão cron aparece apenas como “Programação”.

Por meio de um webhook

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

O token também é o segredo HMAC: a requisição deve carregar X-Hub-Signature-256: sha256=<hex>, em que o hex é HMAC-SHA256(body, token). Uma entrega que falha na verificação é rejeitada e registrada, e não pode ser reenviada. As duplicatas são ignoradas pela chave de deduplicação delas.

Cada início é um nó próprio do grafo. Puxar uma conexão a partir de Programação conecta 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 pelo início que corresponde ao seu tipo de evento e ignora os subgrafos que pertencem aos outros inícios.

Como um gatilho chega a uma execução

Um gatilho habilitado cujo tipo de evento e filtro correspondem inicia uma execução com o payload do evento como o payload de gatilho da execução — é contra isso que {{key}} no prompt ou no script de uma etapa é resolvido. Eventos que carregam uma chave natural são deduplicados, então o mesmo evento disparado duas vezes não inicia duas execuções.

Um modelo desabilitado é recusado mesmo quando o gatilho dele corresponde. Oito dos treze modelos integrados vêm desabilitados, então os gatilhos semeados deles disparam no vazio até você ativar o modelo.

Padrões úteis

Restrinja apenas o caminho manual — conecte Execução manual a um nó de condição e Programação direto ao trabalho. Cada início tem as suas próprias conexões.
Revise toda PR nova — evento PR publicada no modelo pr_review.
Limpe depois de um merge — evento Status da PR alterado, filtrado para merged / closed / approved. O modelo integrado pr_merged_cleanup já escuta assim, além de tarefa concluída/cancelada, SpaceDeleted e um agendamento diário que é habilitado à força a cada nova semeadura porque se trata de coleta de lixo.
Varredura noturna — agendamento 0 2 * * * com um fuso horário, em um modelo cujo primeiro nó é um script bash.
Reaja a um sistema externo — um gatilho de webhook, com o sistema que chama assinando o corpo da requisição como acima.