Governança dos workflows de produção

Todo workflow que entra no n8n de produção deve ser rastreável no n8n, no GitHub e na documentação operacional. O repositório privado 1Nort-Digital/n8n-workflows é a fonte versionada dos artefatos aprovados.

Pacote obrigatório

Cada workflow precisa manter, no mesmo pull request:

• manifesto válido;
• README funcional e técnico;
• export JSON sanitizado;
• casos e evidências de teste;
• runbook e procedimento de rollback;
• changelog;
• checksum SHA-256 do export aprovado.

Exports nunca podem conter credenciais, dados de execução, pinData, cookies, payloads reais ou informações pessoais. Credenciais aparecem apenas como aliases lógicos; o vínculo com o segredo real existe somente no ambiente seguro.

Identidade

O slug canônico segue o formato dominio-capacidade-evento-vMajor. O nome visível deve indicar ambiente, domínio, capacidade, evento e versão principal. IDs do n8n em desenvolvimento e produção são registrados separadamente e não substituem o slug.

Ciclo de vida

draft → review → approved → canary → production → deprecated → archived

Uma alteração material invalida a aprovação anterior. Workflows críticos exigem revisão adicional e não podem ter o autor como único aprovador.

Gates de promoção

1. Registro: owners, criticidade, dados, dependências e aliases definidos.
2. Revisão: schema, sanitização, scanner de segredos, testes e runbook aprovados.
3. Aprovação: commit, versão e checksum congelados; credenciais de produção preparadas.
4. Canário: tráfego limitado, métricas e alertas observados, rollback pronto.
5. Go-live: expansão gradual e documentação reconciliada com o estado real.

Regras técnicas mínimas

• Webhooks validam autenticação ou assinatura antes de processar dados.
• Triggers repetíveis possuem idempotência e janela de deduplicação.
• Retries são limitados e usam backoff; não existe retry infinito.
• Timeouts, concorrência, DLQ ou compensação são documentados.
• Logs e evidências não carregam segredos ou PII.
• Workflows expostos por MCP exigem finalidade e allowlist documentadas.

Mudança emergencial

Uma correção emergencial deve ser mínima, observável e seguida de reconciliação no GitHub em até um dia útil. O export corrigido, a justificativa, os aprovadores e as evidências precisam entrar no histórico.

Nomenclatura e tags no n8n

Os nomes e as tags visíveis para o time são em português. As tags evitam acentos para manter filtros e scripts previsíveis.

Exemplo:

[PROD] 210 | ATENDIMENTO | Receber mensagens WhatsApp | v1

categoria:210-atendimento-entrada
ciclo:producao
papel:entrada
nivel:principal
criticidade:critica
escopo:compartilhado
sistema:whatsapp
sistema:redis

Consulte a taxonomia completa antes de criar ou renomear um workflow. Os valores técnicos do manifesto Git, como lifecycle, continuam definidos pelo schema e não são as tags exibidas no n8n.