Gerenciamento de Releases - Archyl Docs

Rastreie deploys na sua arquitetura com ingestão automatizada via GitHub Actions, webhooks e API REST

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:

Campo Descrição
Versão Tag semver ou identificador (ex.: v2.4.0, 3.12.0-rc.2)
Status Estado atual no ciclo de vida do deploy
Ambiente Ambiente de destino (Produção, Staging, etc.)
Changelog O que mudou nesta release
Origem Como a release foi criada (manual, API, GitHub Action, webhook)
Elemento Vinculado O sistema ou container ao qual esta release pertence

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

Releases passam por estes status:

Status Descrição
Planejado A release existe mas ainda não foi implantada. Útil para rastrear versões futuras.
Em Progresso O deploy está em andamento. Definido automaticamente por integrações CI/CD.
Implantado A release está ao vivo no seu ambiente de destino.
Falhou O deploy não teve sucesso. O registro permanece como histórico do que foi tentado.
Revertido A release foi implantada mas posteriormente revertida.

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 ambientes por estágio de deploy

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

Defina o sistema e opcionalmente um container onde as releases devem ser vinculadas por padrão.

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

O Archyl suporta 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: <uuid-do-seu-sistema>
    container-id: <uuid-do-seu-container>
    changelog: "Correções de bugs e melhorias de performance"
    status: deployed

Webhooks

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

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

API REST

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

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

Visualizações

Timeline de Releases

A visualização principal. Releases são agrupadas por mês em ordem cronológica reversa. Cada entrada mostra versão, indicador de status, tag de ambiente, elemento vinculado, origem e timestamp relativo.

Matriz de Deploy

Uma visualização em grade para equipes gerenciando múltiplos serviços em múltiplos ambientes.

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

A matriz torna a divergência entre ambientes visível de relance.

Boas Práticas

Use Versionamento Semântico

  • Marque releases com semver (ex.: v1.2.3)
  • Inclua identificadores de pré-release para releases de não-produção (ex.: v2.0.0-rc.1)
  • Mantenha 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 de ambiente cedo

Automatize a Ingestão

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

Escreva Changelogs

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

Próximos Passos