Gerenciamento de Releases

O Gerenciamento de Releases rastreia deploys como objetos de primeira classe no seu workspace de arquitetura. Cada release é vinculada a um elemento C4, dando aos seus diagramas uma visão ao vivo do que está realmente em execução.

Conceitos Fundamentais

Releases

Uma release representa uma versão específica implantada em um ambiente. Cada release possui:

Ambientes

Ambientes representam alvos de deploy. São definidos pelo usuário e codificados por cores.

Configurações comuns incluem:

• Desenvolvimento → Staging → Produção
• Dev → QA → Pré-prod → Produção

Crie quantos ambientes seu fluxo de trabalho exigir. Cada release é marcada com seu ambiente de destino.

Ciclo de Vida do Status

As releases passam por estes status:

Configurando o Rastreamento de Releases

1. Crie Ambientes

1. Vá para as Configurações do seu projeto
2. Abra a aba Releases
3. Em Ambientes, clique em Adicionar Ambiente
4. Insira um nome e escolha uma cor
5. Arraste para reordenar os ambientes por estágio de deploy

2. Configure um Alvo de Vinculação Padrão

Defina o sistema e, opcionalmente, um contêiner aos quais as releases devem ser vinculadas por padrão:

1. Na aba de configurações de Releases, encontre Alvo de vinculação padrão
2. Selecione um sistema no menu suspenso
3. Opcionalmente, selecione um contêiner dentro desse sistema
4. Esse alvo é usado quando as releases ingeridas não especificam um elemento

3. Escolha um Método de Integração

O Archyl oferece três formas de ingerir releases automaticamente.

Métodos de Integração

GitHub Actions

Adicione a GitHub Action oficial do Archyl ao seu workflow de deploy.

Configuração mínima:

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

Configuração completa:

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}
    environment: production
    system-id: <your-system-uuid>
    container-id: <your-container-uuid>
    changelog: "Bug fixes and performance improvements"
    status: deployed

A action envia a versão, o SHA do commit, o ambiente e o changelog para o Archyl a cada deploy bem-sucedido.

Webhooks

Configure a ingestão por webhooks para receber eventos de release do GitHub ou do GitLab.

1. Na aba de configurações de Releases, habilite Webhooks
2. Copie a URL do webhook exibida
3. No GitHub ou no GitLab, adicione um novo webhook apontando para essa URL
4. Selecione o tipo de evento Release ou Tag push

Opções de configuração:

Quando uma nova release é publicada ou uma tag correspondente recebe push, o Archyl cria automaticamente uma entrada de release.

API REST

Para qualquer ferramenta de CI/CD capaz de fazer requisições HTTP — Jenkins, CircleCI, Bitbucket Pipelines ou pipelines personalizados.

Endpoint: POST /api/v1/projects/:projectId/releases

Headers:

Authorization: Bearer <api-key>
Content-Type: application/json

Payload:

{
  "version": "v2.4.0",
  "status": "deployed",
  "changelog": "Added payment retry logic",
  "environmentId": "<environment-uuid>",
  "systemId": "<system-uuid>",
  "containerId": "<container-uuid>",
  "sourceUrl": "https://github.com/org/repo/releases/tag/v2.4.0"
}

A aba de configurações exibe trechos de código copiáveis, com as chaves de API e os IDs dos elementos preenchidos automaticamente.

Visualizações

Linha do Tempo de Releases

A visualização principal. As releases são agrupadas por mês, em ordem cronológica reversa. Cada entrada mostra:

• Badge da versão
• Indicador de status
• Tag do ambiente (codificada por cor)
• Sistema ou contêiner vinculado
• Origem (GitHub Action, webhook, API, manual)
• Timestamp relativo

Clique em qualquer release para abrir o painel de detalhes, com o changelog completo, as datas e um link de volta para a origem.

Filtros:

• Por ambiente (ex.: mostrar apenas deploys de produção)
• Por status (ex.: mostrar apenas deploys que falharam)
• Por elemento vinculado

Matriz de Deploy

Uma visualização em grade para equipes que gerenciam vários serviços em vários ambientes.

• Linhas — Sistemas e contêineres
• Colunas — Ambientes
• Células — Última release implantada para aquela combinação

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

Vinculando Releases à Arquitetura

Cada release pode ser vinculada a um sistema, a um contêiner ou a ambos.

Vinculação Automática

Ao usar GitHub Actions ou webhooks, as releases são vinculadas ao alvo padrão definido nas configurações. Você pode sobrescrever o alvo em cada release especificando system-id e container-id.

Vinculação Manual

Ao criar uma release pela interface:

1. Clique em Nova Release
2. Preencha a versão, o status e o changelog
3. Selecione o sistema e/ou o contêiner de destino
4. Escolha o ambiente
5. Clique em Criar

Visualizando no Diagrama

Clique com o botão direito em qualquer elemento do diagrama C4 para abrir o painel de detalhes. As releases vinculadas aparecem na seção Releases, junto com os relacionamentos, ADRs e contratos de API. O elemento exibe a versão e o ambiente da sua release mais recente.

Criando Releases Manualmente

Nem toda release vem de um pipeline. Para criar uma release à mão:

1. Acesse a aba Releases
2. Clique em Nova Release
3. Insira a versão e selecione um status e um ambiente
4. Escreva um changelog (Markdown suportado)
5. Vincule a um sistema e/ou contêiner
6. Clique em Criar

Releases manuais têm a origem marcada como Manual na linha do tempo.

Boas Práticas

Use Versionamento Semântico

• Marque as releases com semver (ex.: v1.2.3)
• Inclua identificadores de pré-release para releases que não são de produção (ex.: v2.0.0-rc.1)
• Mantenha as strings de versão consistentes entre ambientes

Rastreie Todos os Ambientes

• Crie ambientes para cada estágio de deploy
• Não pule o staging — a matriz de deploy é mais útil quando mostra o pipeline completo
• Use a visualização de matriz para detectar divergências entre ambientes cedo

Automatize a Ingestão

• Use GitHub Actions ou webhooks em vez de entrada manual
• Configure a integração uma vez e cada deploy chega automaticamente
• Reserve a criação manual para hotfixes ou deploys excepcionais

Escreva Changelogs

• Inclua um changelog significativo em cada release
• Resuma o que mudou e por quê
• Vincule issues ou pull requests relacionados quando possível

Vincule ao Nível Certo

• Vincule a sistemas ao implantar uma aplicação inteira
• Vincule a contêineres ao implantar serviços individuais dentro de um sistema
• Seja consistente — escolha uma convenção e mantenha-a

Próximos Passos

• Contratos de API — Documente suas especificações de API
• Insights de Arquitetura — Detecte problemas arquiteturais
• Solicitações de Mudança de Arquitetura — Proponha mudanças através de um fluxo de revisão