Gerenciamento de Releases: Rastreie Cada Deploy Pela Sua Arquitetura

Dois meses atrás, participei de um post-mortem onde a questão central era enganosamente simples: "Qual versão do Serviço de Pagamento está rodando em produção agora?"

Quatro pessoas deram três respostas diferentes. Uma verificou a página de releases do GitHub. Outra abriu o ArgoCD. Uma terceira rolou pelo canal de deploy do Slack. A quarta — que realmente fez o deploy — estava de férias.

Isso não era uma startup. Era uma equipe com pipeline de CI/CD maduro, boas práticas de tagging e um diagrama de arquitetura bem mantido no Archyl. O diagrama dizia exatamente quais sistemas existiam, como se conectavam, que protocolos falavam. Só não conseguia dizer qual versão de qualquer coisa estava realmente rodando. Em lugar nenhum.

Essa lacuna tem me incomodado há um tempo. Documentação de arquitetura diz a estrutura de um sistema. Histórico de deploy diz o estado de um sistema. Essas duas coisas deveriam viver juntas. Hoje, vivem.

Releases, Vinculadas à Arquitetura

O Gerenciamento de Releases do Archyl rastreia deploys como objetos de primeira classe no seu workspace de arquitetura. Uma release tem uma versão, um status, um ambiente, um changelog e — criticamente — um link para o elemento C4 a que pertence.

Essa última parte é o que torna isso diferente do seu dashboard de CI/CD. Uma execução do GitHub Actions diz que v2.4.0 foi deployada. Mas deployada onde, no contexto da sua arquitetura? Qual sistema? Qual container? As releases do Archyl respondem isso conectando eventos de deploy diretamente aos sistemas e containers no seu diagrama C4.

Quando você abre o painel de detalhes de um sistema, vê suas releases recentes ao lado dos relacionamentos, ADRs e API contracts. O diagrama de arquitetura se torna um mapa vivo — não apenas do que existe, mas do que foi entregue e quando.

Três Formas de Ingestão

Não queríamos que o rastreamento de releases significasse mais trabalho manual. Se você já faz deploy através de um pipeline, as releases deveriam fluir para o Archyl automaticamente.

GitHub Actions — Publicamos uma GitHub Action oficial que você coloca no seu workflow de deploy. Uma configuração mínima são duas linhas no seu YAML. A action envia a versão, SHA do commit, ambiente e changelog para o Archyl em cada deploy bem-sucedido.

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}

É isso. Cada release tagueada agora aparece no seu workspace de arquitetura.

Webhooks — Configure um endpoint de webhook nas configurações do seu projeto, depois aponte os webhooks de release do GitHub ou GitLab para ele. Quando uma nova release é publicada ou uma tag é criada, o Archyl recebe o evento e cria uma entrada de release automaticamente.

API REST — Para equipes usando Jenkins, CircleCI, Bitbucket Pipelines ou qualquer outra ferramenta de CI/CD, o endpoint de ingestão aceita um payload JSON simples. Autentique com uma chave de API, envie a versão e metadados, e a release aparece no Archyl.

Ambientes

Nem todos os deploys são iguais. Fazer push para staging é rotina. Fazer push para produção é um evento. O Gerenciamento de Releases rastreia ambos, separadamente.

Ambientes são definidos pelo usuário e codificados por cor. Crie "Desenvolvimento", "Staging", "Produção" — ou o que sua equipe usar. Cada release é tagueada com seu ambiente alvo.

A Timeline

A timeline de releases é a visualização principal. Releases são agrupadas por mês, exibidas em ordem cronológica reversa, com badges de versão, tags de ambiente e indicadores de status.

Cada entrada de release mostra: Versão, Status (Deployada, Em Progresso, Planejada, Falhou, Revertida), Ambiente, Elemento vinculado, Fonte e Changelog.

A Matriz de Deploy

Para equipes gerenciando múltiplos serviços em múltiplos ambientes, construímos uma segunda visualização: a Matriz de Deploy.

É uma grade onde as linhas são seus sistemas e containers, as colunas são seus ambientes, e cada célula mostra a última release deployada naquela combinação. De relance, você pode ver que a Account API está na v3.1.0 em produção mas v3.2.0-beta em staging.

A matriz torna a divergência de ambientes visível. Quando versões de staging e produção divergem, você percebe imediatamente.

Ciclo de Vida de Status

Releases nem sempre são limpas. Deploys falham. Releases são revertidas. Rastreamos o ciclo de vida completo: Planejada, Em Progresso, Deployada, Falhou, Revertida.

Transições de status são automáticas ao usar integrações de CI/CD, ou manuais ao criar releases pela interface.

Vinculação a Elementos de Arquitetura

Cada release pode ser vinculada a um sistema, um container, ou ambos. Isso é o que dá contexto arquitetural às releases.

No diagrama, elementos vinculados mostram seu histórico de releases no painel de detalhes. Clique com o botão direito em um container e você vê não apenas seus relacionamentos e contratos, mas sua timeline de deploy. É onde documentação de arquitetura e realidade operacional convergem.

Por Que Isso Importa

Diagramas de arquitetura sempre foram uma foto no tempo. Mostram o que o sistema é. Mas não mostram o que o sistema está fazendo. O Gerenciamento de Releases coloca o histórico de deploy onde ele pertence: na própria arquitetura.

Começando

Navegue até as Configurações do seu projeto e abra a aba Releases. Escolha seu método de integração e siga o guia de configuração. Crie seus ambientes, vincule um sistema ou container alvo, e entregue sua primeira release.

Sua arquitetura é mais do que estrutura. Agora suas ferramentas refletem isso.

Quer aprender mais sobre conectar sua arquitetura à realidade? Veja como API Contracts vinculam suas especificações ao diagrama, ou como Solicitações de Mudança de Arquitetura trazem workflows de pull request ao seu modelo C4.