Discord
A integração com o Discord conecta seu servidor do Discord ao Almirant para executar comandos de agentes, receber notificações de eventos do projeto e controlar sessões de trabalho diretamente pelo chat.
Como funciona
O Almirant se integra ao Discord por meio de um bot que usa OAuth2 para se conectar ao seu servidor. O bot pode:
- Executar slash commands -- Comandos como
/implemente/planpara iniciar trabalhos de agente pelo Discord. - Enviar notificações -- O Almirant notifica pelo Discord sobre eventos relevantes (work items, sprints, PRs, CI/CD).
- Controlar sessões -- Botões interativos para interromper, pausar ou responder a perguntas dos agentes.
- Criar threads automáticas -- Cada trabalho de agente cria uma thread dedicada para acompanhar o progresso.
Configurar a integração com o Discord
1. Conectar via OAuth
Ao contrário de outros bots, o Discord usa OAuth2 para uma conexão segura:
- Acesse Configurações > Integrações > Discord.
- Clique em Conectar Discord.
- O Discord solicitará que você selecione um servidor no qual tenha permissões de administrador.
- Autorize as permissões solicitadas (enviar mensagens, criar threads, usar slash commands).
- O Almirant registrará automaticamente os slash commands no seu servidor.
2. Configurar o canal padrão
Após conectar:
- Acesse Configurações > Integrações > Discord.
- Selecione o canal padrão para o qual o bot enviará notificações.
- Salve as configurações.
3. Verificar a conexão
- Nas configurações do Discord, clique em Enviar mensagem de teste.
- Verifique se a mensagem aparece no canal selecionado.
Slash commands
O bot do Discord oferece slash commands para interagir com o Almirant:
| Comando | Descrição |
|---|---|
/implement [work_item_id] | Inicia um trabalho de implementação para o work item especificado |
/plan [work_item_id] | Inicia um trabalho de planejamento para o work item especificado |
/status | Mostra os trabalhos ativos (queued, running, waiting_for_input) |
/status [job_id] | Mostra o status detalhado de um trabalho específico |
Opções dos comandos
Os comandos /implement e /plan aceitam opções adicionais:
| Opção | Descrição |
|---|---|
work_item_id | (Obrigatório) O ID do work item (ex.: A-123) |
provider | (Opcional) O provedor de agente: claude-code, codex ou zipu |
Exemplo de uso
/implement work_item_id:A-1189
/implement work_item_id:A-1189 provider:claude-code
/plan work_item_id:A-1190
/status job_id:abc123-def456
Threads automáticas
Quando você executa um slash command, o bot cria automaticamente uma thread privada para esse trabalho:
- O nome da thread indica o tipo de trabalho e o ID da tarefa.
- Todas as mensagens de progresso do agente vão para a thread.
- Os botões de controle (
Stop,Shutdown) aparecem na thread. - A thread é arquivada automaticamente após 24 horas de inatividade.
Botões interativos
Durante a execução de um trabalho, o bot mostra botões para controlar a sessão:
| Botão | Ação |
|---|---|
| Stop | Interrompe o trabalho atual, mas mantém o estado |
| Shutdown | Interrompe completamente e encerra a sessão |
Quando o agente tem uma pergunta, as opções aparecem como botões ou em um menu de seleção. Selecione a opção desejada para responder.
Notificações
Configure quais eventos do projeto você deseja receber como notificações no Discord:
| Evento | Descrição |
|---|---|
| Work item criado | Um novo work item é criado |
| Work item movido | Um work item muda de coluna no board |
| Work item atribuído | Um work item é atribuído a alguém |
| Work item concluído | Um work item é marcado como done |
| Sprint iniciado/encerrado | Um sprint começa ou termina |
| Milestone concluído | Um milestone é concluído |
| PR aberto/merged | Um pull request é aberto ou recebe merge |
| CI com falha | Uma build de CI falha |
| Trabalho de agente concluído/com falha | Um trabalho de agente termina |
Para configurar as notificações:
- Acesse Configurações > Integrações > Discord.
- Clique em Configurar notificações.
- Ative ou desative os eventos desejados.
- Salve as alterações.
Vincular projetos a canais
Você pode configurar canais específicos para projetos diferentes:
- Acesse as configurações do projeto.
- Na seção Discord, selecione o canal de destino.
- As notificações e threads desse projeto irão para o canal configurado.
Se não houver um canal específico, será usado o canal padrão da organização.
Desconectar o Discord
Para desconectar o bot:
- Acesse Configurações > Integrações > Discord.
- Clique em Desconectar.
- Confirme a desconexão.
Desconectar o bot interromperá os slash commands e as notificações pelo Discord. Os trabalhos em andamento não serão cancelados automaticamente.
Arquitetura da integração
A integração com o Discord é composta por duas rotas principais:
- OAuth routes (
/api/integrations/discord): Gerencia o fluxo OAuth2, conexões, canais e preferências de notificação. - Interactions webhook (
/webhooks/discord/interactions): Recebe e processa slash commands, botões e menus de seleção.
Fluxo de OAuth
Usuario --> GET /authorize --> Discord OAuth --> GET /callback
|
+------------ Token exchange
|
Create connection + Register slash commands
Fluxo de interações
Discord --> POST /webhooks/discord/interactions --> Verify signature
|
+--------------------------+
| | |
PING Command Component
| | |
PONG Queue job Process action
Slash commands registrados
Os comandos são registrados automaticamente na guild durante o OAuth:
implement: Inicia um trabalho de implementaçãoplan: Inicia um trabalho de planejamentostatus: Consulta o status dos trabalhos
Verificação de assinatura
Todas as interações são verificadas com Ed25519 e a chave pública do Discord (DISCORD_PUBLIC_KEY). Isso garante que os requests vêm do Discord.
Variáveis de ambiente
| Variável | Descrição |
|---|---|
DISCORD_CLIENT_ID | ID da aplicação do Discord |
DISCORD_CLIENT_SECRET | Secret da aplicação |
DISCORD_PUBLIC_KEY | Chave pública para verificar assinaturas |
DISCORD_BOT_TOKEN | Token do bot para enviar mensagens |
DISCORD_APPLICATION_ID | ID da aplicação (para slash commands) |
DISCORD_OAUTH_REDIRECT_URI | URI de callback do OAuth |