Um gancho reage a algo que acontece no Coroid. Você escolhe um evento, escreve instruções em linguagem simples e o gancho é executado quando o evento ocorre.
Encontre-os na plataforma, em Automações.
Crie um no Novo trabalho: selecione Automação e depois a opção 'Quando algo acontece'. O Novo trabalho disponibiliza os eventos GitHub e os eventos do Coroid. Veja Automações.
Eventos aos quais você pode reagir
Um gancho é acionado apenas para um evento enviado por algo. O Coroid envia a maioria dos eventos abaixo. Alguns são disparados pelos seus próprios sistemas. Qualquer outro evento é reservado: o editor não o lista e um novo gancho para ele é recusado. Se um gancho foi salvo em um evento reservado, o editor e a lista marcam-no como nunca sendo acionado; ele não é excluído.
Eventos enviados pelo Coroid
| Categoria | Eventos |
|---|---|
| Tarefa | Criado, status alterado, concluído, falhou |
| Agente | Iniciado, concluído, erro |
| Repositório | Commit enviado, ramificação criada, pull request aberto, atualizado ou mesclado, issue aberta, comentário que menciona Coroid |
| Sprint | Criado, planejamento iniciado, iniciado, tarefa adicionada, tarefa removida, revisão iniciada, concluído, cancelado |
| Plano | Fase iniciada, concluída, falhou |
| Agendamento | Execução iniciada, execução concluída, execução falhou |
| Relatório | Iniciado, concluído, falhou |
| Qualidade | Verificação iniciada, aprovada ou reprovada; resolvida automaticamente |
| Promoção | Solicitado, aprovado, rejeitado |
| Lançamento | Criado, candidato alterado, notas alteradas, notas aprovadas, escopo alterado, lista de verificação concluída, portão avaliado, portão substituído, aprovado, publicado, revertido |
| Implantação | Em fila, em execução, bem-sucedida, falhou, cancelada, atestada manualmente, rollback atestado manualmente, verificação de integridade aprovada, verificação de integridade falhou |
| Sincronização | Fonte externa atualizada |
| Slack e Telegram | Uma mensagem que corresponde ao filtro da automação |
Eventos disparados pelos seus próprios sistemas
| Categoria | Eventos |
|---|---|
| Análise | Dependência encontrada, problema de segurança encontrado, análise concluída |
| Implantação externa | Iniciada, concluída, falhou |
O Coroid não envia esses eventos. Um pipeline de CI, um scanner ou outro sistema seu dispara o gancho pelo seu ID: ele chama POST /api/v1/organizations/hooks/:id/dispatch
com a chave de um conta de serviço
que possui o hooks:dispatch escopo. O gancho é executado para o evento em que foi salvo. O editor lista esses eventos em "Disparados pelos seus próprios sistemas".
Eventos reservados
Estes ainda não foram enviados ou disparados, portanto o editor não os oferece:
| Categoria | Eventos |
|---|---|
| Tarefa | Fase alterada |
| Agente | Iteração, ferramenta chamada |
| Plano | Criado, fase concluída, revisão final iniciada, revisão final concluída, antes do pull request do plano |
| Agendamento | Criado, ativado, pausado |
| Sprint | Planejamento concluído, tarefa concluída, escopo alterado |
| Lançamento | Preparado, validado |
| Promoção | Antes do pull request da promoção |
| Qualidade | Verificação indisponível; reparo iniciado ou tentado; nova validação iniciada; consenso alcançado |
Quando o trabalho começa e termina
Planos, agendamentos, relatórios, verificações de qualidade, promoções e lançamentos enviam um evento quando começam e um evento quando terminam. Um gancho pode reagir a como o trabalho terminou, e um sistema seu pode medir quanto tempo levou.
| Trabalho | Inicia | Termina |
|---|---|---|
| Plano | Fase iniciada: o primeiro é enviado quando a execução do plano começa | Concluído, falhou |
| Agendamento | Execução iniciada | Execução concluída, execução falhou |
| Relatório | Iniciado | Concluído, falhou |
| Verificação de qualidade | Verificação iniciada | Aprovada, reprovada, resolvida automaticamente |
| Promoção | Solicitado | Aprovado, rejeitado |
| Lançamento | Criado | Publicado, revertido |
Cada um desses eventos registra o horário em que ocorreu em occurredAt. Um evento que informa como o trabalho terminou também registra quando o trabalho começou em
startedAt, e quanto tempo levou em durationMs. Isso startedAt é o
occurredAt do evento de início, portanto os dois sempre coincidem. O tempo de trabalho em pausa conta para a duração.
Cada evento é enviado uma vez, quando a alteração é salva. Uma alteração desfeita não gera nenhum evento, e uma nova tentativa também não gera eventos duplicados. Um evento de término é enviado apenas para trabalhos que foram iniciados: uma execução de planejamento simulada não gera eventos, assim como um relatório cancelado antes de começar.
O que cada evento contém, além dos horários:
| Evento | Enviado quando | Campos |
|---|---|---|
| Fase de planejamento iniciada | A execução do plano começa (sua primeira fase) e, posteriormente, sempre que a primeira tarefa de outra fase inicia. | planId, plan (id, título), phase (id, sequência, título), firstPhase, executionStartedAt |
| Planejamento concluído ou com falha | A execução do plano termina. Um plano que falha durante o planejamento não gera eventos. | planId, plan, status, executionStartedAt |
| Execução de agendamento iniciada | Uma execução de agendamento começa. | scheduleId, runId, schedule (id, nome), run (motivo do disparo, execução pai) |
| Execução de agendamento concluída ou com falha | A execução termina. | Os mesmos campos, status, e tasksCreated ou error |
| Relatório iniciado | Um relatório começa a ser gerado. Pausar e retomar mantêm o mesmo horário de início. | reportId, report (id, tipo, título) |
| Relatório concluído ou com falha | O relatório é salvo, ou falha ou é cancelado. | Os mesmos campos, e tokensUsed, costUsd e hasActionableFindings, ou error |
| Verificação de qualidade iniciada | Uma verificação de qualidade começa. | qualityRunId, check (assunto, disparador, versão da política, commit) |
| Verificação de qualidade aprovada ou com falha | A verificação chega à sua decisão. | Os mesmos campos, decision, redoCause, failedExpectationIds |
| Qualidade não resolvida automaticamente | Coroid para de tentar corrigir o que a verificação encontrou. | qualityRunId, workItemType, workItemId, reason |
| Promoção solicitada | Uma promoção é criada. | promotionId, laneId, promotion (título, status, ramificações, pull request) |
| Promoção aprovada | A promoção é mesclada: aprovada no Coroid, mesclada forçadamente, mesclada no provedor ou lançada em uma versão. | Os mesmos campos, approval, approvedBy, forceReason |
| Promoção rejeitada | Um revisor solicita alterações. | Os mesmos campos, reason, requestedBy, comment |
| Versão publicada | A primeira implantação em produção da versão tem sucesso. | releaseId, version, commitSha |
| Versão revertida | Uma reversão substitui a versão em um ambiente. | releaseId, version, rolledBackToReleaseId |
Os eventos sobre o trabalho em um projeto também contêm projectId, portanto um hook limitado a um
projeto dispara apenas para esse projeto. Se um hook criou o trabalho, esses eventos
contam para a profundidade da cadeia desse hook.
Disparadores e destinos
Toda automação tem uma fonte de disparo, de onde seus eventos provêm, e um destino, que decide o que acontece quando um evento é disparado. Dois dos destinos transformam um evento em trabalho.
| Fonte de disparo | Eventos |
|---|---|
| Evento de fluxo de trabalho | Eventos no Coroid, conforme na tabela acima |
| GitHub | Pull request aberta, atualizada ou mesclada; issue aberta; um comentário que menciona Coroid |
| Slack | Uma mensagem que corresponde ao filtro da automação |
| Telegram | Uma mensagem que corresponde ao filtro da automação, como uma que começa com /coroid |
| Jira | Uma nova issue |
| Destino | O que acontece |
|---|---|
| Hook | Executa suas instruções, somente leitura, conforme descrito nesta página. |
| Qualificar trabalho | Arquiva o evento como uma solicitação. Depois que a Qualificação for aprovada, Coroid cria o trabalho. |
| Coroid Check | Descontinuado. A Revisão Coroid de cada pull request é definida em Controle de Qualidade; as automações existentes foram pausadas |
Os eventos GitHub precisam do App GitHub. Um comentário que menciona Coroid conta apenas quando seu autor tem acesso de gravação ao repositório. Veja GitHub.
Uma tarefa de Qualificar trabalho começa por conta própria apenas quando o autor do evento é confiável: o autor de um GitHub pull request, issue ou comentário que tenha acesso de gravação ao repositório. Autores do Slack, Telegram e Jira nunca são confiáveis, portanto suas tarefas aguardam alguém iniciá-las. Veja Quando o trabalho começa.
Novos problemas do Jira chegam ao Coroid apenas por meio do webhook do Jira. Ele aceita apenas entregas assinadas com o segredo do webhook configurado para Coroid, somente para novos problemas e apenas quando a chave do projeto do Jira corresponder a um projeto do Coroid. No coroid.ai, o webhook do Jira ainda não foi configurado, portanto o gatilho do Jira não recebe eventos; importe os problemas do Jira em vez disso. Onde o webhook está configurado, um novo problema é encaminhado às automações do gatilho do Jira, como a origem da solicitação do Jira no Controle de Qualidade, que registra problemas dos tipos e prioridades que você escolher para Qualificação. Sem automação no gatilho, um novo problema não gera nenhum registro. O trabalho a partir do Jira nunca começa sozinho. Veja Rastreadores de problemas.
Somente leitura por padrão
Os hooks analisam e relatam. Eles podem criar tarefas de acompanhamento; não modificam seu código diretamente.
Esse padrão é o que os torna seguros para adoção. Uma automação que edita código em resposta a um evento age no momento menos provável de ser supervisionada. Um hook que abre uma tarefa produz o mesmo resultado pelo caminho normal — especificação, planejamento, verificação, revisão, pull request.
- AgendarHorário
- Automação de eventosAlgo acontece.
Uma tarefa comum
Especificação, plano, construção, verificação, revisão. Usa um slot de agente; atribua-lhe prioridade menor.
P2P3Um pull request
Ele não pode fazer merge nem commit na sua branch base.
Você aprova
Escrevendo boas instruções
As instruções de hook são processadas por um modelo, então parecem instruções para um colega em vez de código. O padrão de qualidade é o mesmo de uma especificação: indique o que observar, o que importa e o que fazer.
Seja específico sobre o caso de "não fazer nada". Sem isso, um hook encontrará algo para dizer toda vez que for executado, e hooks que sempre disparam são ignorados pelas pessoas.
Proteções
Existem três proteções porque a automação baseada em eventos falha de maneiras previsíveis:
Limites de taxa. Por minuto, por hora e por dia, configuráveis por hook. Um hook em um evento de alta frequência pode disparar centenas de vezes durante uma fusão movimentada.
Profundidade da cadeia. Os hooks podem disparar eventos que acionam outros hooks. Uma profundidade máxima da cadeia evita que isso se torne um loop.
Permissões de ferramenta. O que um hook pode acessar é controlado — o acesso somente de leitura, chamadas MCP e criação de tarefas são gerenciados separadamente.
Permissões
Apenas proprietários e administradores podem criar, alterar, testar ou excluir um hook; todos os membros podem ver os hooks e seu histórico de execução. Como um hook opera com alcance no nível da organização, essa assimetria é intencional.
Monitorando-os
A página de cada hook na fábrica lista suas execuções e o que fez nos últimos 30 dias: execuções, falhas e custo. Cada execução de automação também está em Configurações → Atividade, filtrada por Automação. Verifique suas execuções após habilitar um novo hook — o modo de falha não é um erro, mas sim o disparo constante sem gerar resultados úteis.
Hooks e agendamentos
| Mecanismo | Disparado por |
|---|---|
| Hook | Um evento da plataforma |
| Agendamento | Horário |
Ambos são automações, listadas juntas na fábrica. Veja Automações.