Autopilots
Agende trabalho recorrente para agentes ou dispare execuções por webhook, com histórico de execuções, filtros de eventos e controle de acesso.
Um autopilot entrega trabalho a um agente sem ninguém criar a tarefa à mão: num horário definido, quando outro sistema chama um webhook ou quando você clica em Executar agora. No app, os autopilots ficam na página Automação da barra lateral; na CLI, no comando jiraya autopilot.
Criar um autopilot
Abra a página Automação
Clique em Automação na barra lateral e depois em Nova automação. Escolha um modelo ou Começar do zero.
Descreva o trabalho
- Nome: aparece na lista e é o título inicial das tarefas criadas no modo Criar tarefa.
- Runbook: as instruções que o agente lê a cada execução. Escreva o objetivo, o contexto e os passos, como faria numa tarefa.
- Responsável: o agente ou a equipe que executa o trabalho. Com uma equipe, quem recebe é o líder dela.
- Projeto (opcional): agrupa as tarefas criadas e define onde a execução roda, como o repositório do projeto.
- Inscritos (opcional): membros que recebem as notificações de cada tarefa criada pelo autopilot.
Escolha o modo de saída e o gatilho
Defina o Modo de saída (veja abaixo) e o Gatilho: Programação ou Webhook. Depois de salvo, o autopilot roda sozinho até ser pausado.
Modos de saída
| Modo | O que cada execução faz | Com o runtime do agente desconectado |
|---|---|---|
| Criar tarefa | Cria uma tarefa em todo com o runbook na descrição, atribuída ao agente. O agente trabalha nela como em qualquer tarefa e, ao começar, renomeia a tarefa para descrever o que está fazendo. | A tarefa é criada mesmo assim e espera o runtime voltar. |
| Somente execução | Roda o agente direto, sem criar tarefa. O resultado fica no histórico de execuções. | A execução é marcada como Ignorado e nada fica na fila. |
Use Criar tarefa quando quiser acompanhar, comentar e revisar cada entrega no quadro. Use Somente execução para rotinas que não precisam de registro no quadro.
Nota
No modo Criar tarefa, se o mesmo autopilot criou uma tarefa com o mesmo título há menos de um minuto, a nova execução é ignorada. Isso evita tarefas duplicadas quando o gatilho dispara duas vezes seguidas.
Rodar numa programação
A programação usa uma expressão cron de cinco campos (minuto, hora, dia do mês, mês e dia da semana) e um fuso horário IANA, como America/Sao_Paulo. Sem fuso, vale UTC.
No app, o editor monta a expressão para você: Em um horário ou Em um intervalo, os dias da semana e o fuso. Também dá para digitar a expressão no modo Cron. A prévia Próximas execuções mostra quando o autopilot vai rodar.
Exemplos:
| Expressão | Quando roda |
|---|---|
0 9 * * 1-5 | Dias úteis, às 9h |
30 18 * * 5 | Sextas-feiras, às 18h30 |
0 */4 * * * | A cada 4 horas, na hora cheia |
Um autopilot pode ter mais de uma programação. Gerencie cada uma em Gatilhos, na página do autopilot.
Rodar por webhook
Com o gatilho Webhook, o Jiraya gera uma URL depois que o autopilot é criado. Qualquer sistema que envie um POST com JSON para essa URL dispara uma execução:
curl -X POST https://api.jiraya.io/api/webhooks/autopilots/awt_... -H "Content-Type: application/json" -d '{"event": "deploy.failed", "service": "api"}'O corpo precisa ser um objeto ou uma lista JSON de até 256 KiB. No modo Criar tarefa, a descrição da tarefa traz o runbook, o evento identificado e o JSON recebido.
Proteja a URL
A URL é a credencial do webhook: quem tiver a URL consegue disparar o autopilot. Ela só aparece para quem pode editar o autopilot. Se ela vazar, use Renovar URL na página do autopilot. A URL antiga para de funcionar na hora, então atualize o sistema que a chama.
Para não processar a mesma entrega duas vezes, envie um identificador único no cabeçalho Idempotency-Key. O GitHub já faz isso com o cabeçalho X-GitHub-Delivery. Uma chave repetida é respondida como duplicate, sem nova execução.
Filtros de eventos
Os filtros fazem o autopilot processar só os eventos que interessam. Cada filtro tem um evento e, opcionalmente, uma lista de ações. Sem filtros, todo evento é aceito.
O Jiraya identifica o evento de cada entrega nesta ordem:
- O campo
eventdo corpo JSON. - O cabeçalho
X-GitHub-Event, combinado com o campoactiondo corpo. Umworkflow_runcomactionigual acompletedviragithub.workflow_run.completed. - O cabeçalho
X-Gitlab-Event. - O cabeçalho
X-Event-Type. - Os campos
typeouactiondo corpo. - Se nada disso existir, o evento é
webhook.received.
As ações do filtro são comparadas com o fim do nome do evento e com os campos action, state, conclusion e status do corpo. Por exemplo, o filtro com evento workflow_run e ações failure aceita só as execuções de workflow do GitHub que terminaram com falha.
Respostas do webhook
| HTTP | status no corpo | Quando |
|---|---|---|
| 200 | accepted | A execução foi criada. |
| 200 | skipped | A execução foi registrada como ignorada, por exemplo com o runtime desconectado no modo Somente execução. |
| 200 | ignored | O gatilho está desativado, o autopilot está pausado ou excluído, o evento não passou nos filtros ou o limite de execuções foi atingido. O motivo vem no campo reason. |
| 200 | duplicate | A chave de idempotência já foi usada. |
| 400 | — | Corpo vazio, JSON inválido ou um valor que não é objeto nem lista. |
| 404 | — | A URL não existe ou foi renovada. |
| 413 | — | O corpo passou de 256 KiB. |
| 429 | — | Muitas chamadas. Tente de novo depois do tempo indicado no cabeçalho Retry-After. |
Acompanhar execuções
A página do autopilot mostra:
- Gatilhos: as programações e o webhook. No webhook ficam Mostrar URL, Copiar URL e Renovar URL.
- Histórico de execuções: cada execução com o status Tarefa criada, Em execução, Ignorado, Concluído ou Falhou, e o motivo quando ela não rodou.
- Entregas de webhook: cada chamada recebida, com o evento identificado e o resultado. Quem pode editar o autopilot consegue repetir uma entrega.
Executar agora dispara uma execução na hora, fora da programação. Ela só funciona com o autopilot ativo.
Falhas, pausa e exclusão
- Pausar: use a chave de status na página do autopilot. Um autopilot pausado ignora as programações e os webhooks até ser reativado.
- Pausa automática: o Jiraya confere os autopilots uma vez por dia. Se um deles teve ao menos 50 execuções nos últimos 7 dias e 90% ou mais falharam, ele é pausado e quem o criou recebe um aviso na caixa de entrada. Corrija a causa e reative à mão.
- Sem runtime: se o agente responsável perder o runtime, o autopilot fica Pausada — o responsável precisa de um ambiente. Associe um runtime ao agente e reative.
- Excluir: em Zona de risco, Excluir automação para os gatilhos e tira o autopilot da lista. As tarefas que ele já criou continuam no quadro.
Os limites do workspace podem restringir a quantidade de autopilots e de execuções por mês. Quando o limite é atingido, a execução aparece como não acionada, com o motivo.
Permissões
- Qualquer membro do workspace pode criar um autopilot.
- Quem criou, os administradores do workspace e os colaboradores adicionados em Gerenciar acesso podem editar, executar, pausar e excluir o autopilot e mexer nos gatilhos.
- Só quem criou e os administradores mudam quem tem acesso.
Usar a CLI
Crie um autopilot que abre uma tarefa por dia útil, às 9h no horário de Brasília:
jiraya autopilot create --title "Resumo diário de erros" --agent "Backend" --mode create_issue --description "Leia os erros das últimas 24 horas e resuma os mais frequentes."jiraya autopilot trigger-add <autopilot-id> --kind schedule --cron "0 9 * * 1-5" --timezone America/Sao_PauloOutros comandos:
| Comando | O que faz |
|---|---|
jiraya autopilot list | Lista os autopilots do workspace. Filtre com --status active ou --status paused. |
jiraya autopilot get <id> | Mostra os detalhes. A URL do webhook aparece só com --show-secrets --output json. |
jiraya autopilot update <id> | Muda nome, runbook, agente, projeto, modo ou status (--status paused pausa). |
jiraya autopilot trigger <id> | Executa uma vez, na hora. |
jiraya autopilot runs <id> | Lista o histórico de execuções. |
jiraya autopilot trigger-add <id> --kind webhook | Adiciona um gatilho de webhook e mostra a URL. |
jiraya autopilot trigger-list <id> | Lista os gatilhos com os seus IDs. |
jiraya autopilot trigger-update <id> <trigger-id> | Muda a programação, o fuso, o rótulo ou ativa e desativa o gatilho. |
jiraya autopilot trigger-rotate-url <id> <trigger-id> | Renova a URL de um webhook. |
jiraya autopilot trigger-delete <id> <trigger-id> | Remove um gatilho. |
jiraya autopilot delete <id> | Exclui o autopilot. |
No modo create_issue, a flag --issue-title-template define o título das tarefas criadas. O único marcador aceito é {{date}}, a data da execução no formato AAAA-MM-DD.
Os filtros de eventos do webhook são configurados pelo app.
Atualizado em