Diagrama de pipeline CI/CD: do commit à produção, passo a passo

Peça um diagrama de CI/CD e você normalmente recebe uma fileira de caixas: build, teste, deploy. Não está errado, mas não responde a quase nenhuma das perguntas que as pessoas levam até ele. O que exatamente vai para o deploy? Quem pode mandar mudanças para produção? Onde estão as aprovações? Como fazemos rollback, e o que nos diz que precisamos fazer isso?

Este guia mostra como desenhar um diagrama de pipeline CI/CD que responda a essas perguntas, usando como exemplo um setup comum: pull requests no estilo do GitHub, um registro de contêineres e deploys GitOps no Kubernetes com Argo CD. As regras valem igualmente para outras ferramentas.

O que um diagrama de pipeline deve mostrar

• Gatilhos. O que dispara cada parte: um pull request, um merge na main, uma tag, um agendamento.
• Etapas e sua ordem. Lint, testes, build, scan, deploy, verificação.
• Artefatos. O que passa de uma etapa para outra, geralmente uma imagem de contêiner. Mostre como ele é identificado: por uma tag ou, melhor ainda, por um digest.
• Ambientes. Onde o artefato roda e em que ordem ele chega lá.
• Pontos de controle. Aprovações manuais, verificações obrigatórias e políticas que barram uma mudança.
• Credenciais. Qual sistema pode alterar qual ambiente.
• Feedback. Como os sinais da produção param ou revertem uma versão com problema.

Uma fileira de etapas cobre os dois primeiros itens. O resto é onde acontecem os incidentes e as auditorias.

O exemplo: GitOps no Kubernetes

1. Um desenvolvedor abre um pull request no repositório da aplicação.
2. O CI roda a cada push: lint, testes unitários, build da imagem e scan. Em um merge na main, ele envia a imagem para o registro e anota o digest dela.
3. Em seguida, o CI faz commit do novo digest da imagem no overlay de staging de um repositório de configuração separado.
4. O Argo CD no cluster de staging percebe o commit, puxa a configuração e sincroniza o cluster.
5. Para promover a versão, alguém abre um pull request que copia a referência para o overlay de produção. Uma revisão obrigatória é o ponto de aprovação.
6. Depois do merge, o Argo CD de produção sincroniza, e o Argo Rollouts, um controller separado dentro do cluster, libera a nova versão como canary: primeiro para uma pequena parte do tráfego, depois para todo ele.
7. Durante o canary, o Argo Rollouts roda uma análise sobre as métricas do Prometheus. Se a análise falhar, o rollout é abortado, o tráfego volta para a versão estável e alertas acionam o engenheiro de plantão.

Dois detalhes deste diagrama passam despercebidos com facilidade e importam muito. O CI nunca fala com um cluster: ele só envia a imagem para o registro e faz commit no Git. E a produção só muda por meio de um commit revisado, que também é o jeito de fazer rollback: reverta o commit e o Argo CD sincroniza a versão anterior.

Push ou pull: desenhe onde ficam as credenciais

Em um pipeline baseado em push, o CI guarda credenciais do cluster e roda ele mesmo o comando de deploy. Em um setup GitOps baseado em pull, um agente dentro de cada cluster, como o Argo CD ou o Flux, puxa o estado desejado do Git e o aplica, então nada fora do cluster precisa de acesso de escrita a ele.

As duas abordagens são válidas, e o diagrama deve deixar a escolha evidente. No push, desenhe uma conexão do CI para cada cluster e rotule-a com a credencial usada. No pull, desenhe o repositório de configuração alimentando o agente de cada cluster, sem nenhuma conexão do CI para cluster algum. Assim, quem revisa enxerga num relance o raio de impacto de um segredo de CI vazado.

Se o CI precisa de acesso à nuvem, por exemplo para enviar imagens, anote como ele obtém esse acesso. No diagrama, tokens de curta duração via OpenID Connect contam uma história bem melhor do que uma chave de longa duração guardada como segredo.

Regras para um diagrama de pipeline legível

Deixe o artefato visível

Rotule a conexão que entra no registro com o artefato e a forma como ele é identificado: image shop-api, by digest. Tags podem ser movidas; um digest sempre aponta para a mesma imagem. Se você também gera um SBOM ou uma assinatura, mostre-os ao lado da imagem.

Desenhe os ambientes como molduras

Cada ambiente é uma moldura com seu agente de deploy e seu cluster dentro. A ordem das molduras mostra o caminho de promoção, e qualquer coisa que pule uma moldura chama atenção na hora.

Dê a cada ponto de controle um nó próprio

Uma aprovação é uma etapa com um responsável, não um rótulo em uma seta. Desenhe-a como um nó entre ambientes e diga quem aprova: approve: release manager ou 2 reviews required.

Feche o ciclo

Um pipeline que termina em "deploy" não tem feedback. Desenhe o que observa a produção e o que isso pode fazer: parar um canary, acionar uma pessoa, disparar um rollback.

Deixe os detalhes dos jobs no arquivo de CI

Doze jobs de teste em paralelo pertencem à configuração de CI. No diagrama, basta um nó de etapa com um rótulo curto (lint, test, build, scan).

Erros comuns

• Nenhum artefato. Caixas ligadas por setas que não carregam nada em particular. Quem lê não consegue saber o que está sendo promovido.
• Ambientes como etapas. "Deploy em staging" e "deploy em prod" como duas caixas em sequência escondem que são lugares diferentes, com permissões diferentes.
• Falta o caminho de rollback. Se ninguém consegue apontá-lo no diagrama, provavelmente ele nunca foi testado.
• Cada job como um nó. O diagrama vira o log do CI.
• Ferramentas em vez de responsabilidades. Uma caixa com o nome de um produto diz menos que build and scan image.

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. No pack DevOps, adicione nós Repositório para o repositório da aplicação e o de configuração e um Pipeline de CI/CD para o CI. Adicione um Registro do pack Docker.
3. Adicione uma Moldura do pack Básico para cada ambiente, com um nó Implantação do pack DevOps para o Argo CD (e o Argo Rollouts em produção) e um Cluster Kubernetes do pack Nuvem dentro.
4. Adicione uma forma Losango do pack Básico para o ponto de aprovação.
5. Adicione os nós Métricas e Alerta do pack DevOps e nós Pessoa do pack Modelo C4 para o desenvolvedor e o engenheiro de plantão.
6. Conecte as portas, rotule cada conexão com o que passa por ela e deixe a conexão de feedback tracejada.

O exemplo usa 15 nós de diagrama, o limite do plano Free. Para um pipeline com observabilidade embutida, abra /examples/cicd-observability; para o lado do cluster, veja como desenhar um diagrama de arquitetura Kubernetes.

Perguntas frequentes

Devo desenhar cada job de CI? Não. Agrupe os jobs em etapas e deixe os detalhes no arquivo de CI. Desenhe um job separado só quando ele for um ponto de controle, como um scan de segurança que bloqueia o release.

Como mostro feature flags? Como um sistema separado ao lado da produção, com uma conexão para os serviços que leem as flags. Flags mudam o comportamento sem deploy, então merecem uma linha própria no diagrama.

Onde ficam os segredos no diagrama? Mostre qual sistema guarda qual credencial e para quê, não os segredos em si. No caso do CI, anote se ele usa tokens OIDC de curta duração ou chaves armazenadas.

Preciso de um diagrama por repositório? Normalmente, um diagrama por caminho de entrega. Se muitos serviços compartilham o mesmo pipeline, desenhe-o uma vez e liste os serviços em uma nota.

Como mantenho o diagrama atualizado? Revise-o quando o pipeline mudar, do mesmo jeito que você revisa o arquivo de CI. Coloque no README do repositório um link para o diagrama ao vivo, para que exista uma única cópia.

Comece grátis — um assento, sem cartão de crédito.