> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Runbook de Operações

> Runbook para deployments, incidentes e monitoramento.

# Runbook de Operações

Esta página é o runbook publicado para deployments, incidentes e monitoramento.

Para confiabilidade de migração do Supabase em produção, use o runbook dedicado:

* [Confiabilidade de Migração do Supabase (Produção)](/pt-BR/operations/supabase-migration-reliability)

## Checklist de CI/CD

* Execute lint, docs lint, typecheck, testes e builds antes do merge.
* Trate as verificações de link do Mintlify e a validação de build da documentação como parte do caminho normal de verificação.
* Use tags de release somente após o contrato do repositório estar verde.
* Rastreie builds de container, validação de migração, revisão de dependências e varredura de segredos como backlog de hardening até que sejam adicionados aos workflows padrão.

## Incidentes Comuns

1. **Falha do webhook** – inspecione `/internal/runtime`, verifique erros de verificação, reenvie os envelopes afetados.
2. **Violação de rate limit** – pause as campanhas, ajuste o backoff do scheduler, documente os erros `130429`/`131056`.
3. **Falha de journey/campanha** – revise `journey_runs`, reenvie via `/internal/webhooks/:id/replay`, registre nas notas adversariais.

## Metas de Monitoramento

* latência do webhook
* profundidade da fila
* falhas de validação de template
* throughput por número de telefone
* eventos de backoff por taxa de pareamento
* distribuições de erro de entrega
* desvio de feature flags

## Tarefas de Rotina

* Rotacionar credenciais, registrar eventos de auditoria.
* Atualizar as notas adversariais após correções.
* Revisar políticas de retenção para payloads brutos e rejeições.

## Triagem do conector gb-agent

Use este bloco quando um operador reportar um estado de rascunho do gb-agent travado ou inesperado. Detalhes completos da superfície em [Plataforma → Conector gb-agent](/pt-BR/platform/gb-agent-connector).

| Sintoma                                                                  | Causa provável                                                  | Primeira verificação                                                                                                                    |
| ------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Gatilho de inbox desativado com "Endpoint não configurado"               | Nenhuma URL/token de conector nas configurações do workspace    | Configurações → Integrações → gb-agent; confirme que o segredo do Vault existe                                                          |
| Gatilho de inbox desativado com "Endpoint inseguro"                      | A URL configurada não é https ou contém userinfo/query/fragment | Substitua por uma URL https limpa; o mapeador da UI rejeita deliberadamente URLs inseguras                                              |
| "Rascunho já em fila" em toda tentativa                                  | Existe um rascunho pendente do conector em `message_drafts`     | Resolva o rascunho existente (Aceitar/Editar/Rejeitar) ou execute release\_stuck\_outbox\_jobs se estiver arrendado e travado           |
| Operador relata que o cartão de pré-visualização de handoff está ausente | A feature flag `inbox.gbAgentHandoffPreview` está desativada    | Defina `NEXT_PUBLIC_FLAG_INBOX_GB_AGENT_HANDOFF_PREVIEW=1` no projeto Vercel apps/app; reimplante                                       |
| Operador relata que uma ação em que não clicou foi executada             | Isso nunca deveria acontecer — o conector é somente dry-run     | Registre como bug; verifique `responder_runs.metadata.policyDecisions` para `requiresHumanApproval: true` e `externalSendQueued: false` |