Gestione delle Release

La Gestione delle Release traccia i deploy come oggetti di prima classe nel tuo workspace architetturale. Ogni release è collegata a un elemento C4, dando ai tuoi diagrammi una vista live di ciò che è effettivamente in esecuzione.

Concetti Fondamentali

Release

Una release rappresenta una versione specifica deployata in un ambiente. Ogni release ha:

Ambienti

Gli ambienti rappresentano destinazioni di deploy. Sono definiti dall'utente e con codifica colore.

Configurazioni comuni includono:

• Development → Staging → Production
• Dev → QA → Pre-prod → Production

Crea quanti ambienti richiede il tuo workflow. Ogni release è taggata con il suo ambiente di destinazione.

Ciclo di Vita degli Stati

Le release attraversano questi stati:

Configurare il Tracciamento delle Release

1. Crea gli Ambienti

1. Vai nelle Impostazioni del progetto
2. Apri la scheda Release
3. Sotto Ambienti, clicca su Aggiungi Ambiente
4. Inserisci un nome e scegli un colore
5. Trascina per riordinare gli ambienti per fase di deploy

2. Configura un Collegamento di Destinazione Predefinito

Imposta il sistema e opzionalmente un container dove le release dovrebbero essere collegate per impostazione predefinita:

1. Nella scheda impostazioni Release, trova Collegamento di Destinazione Predefinito
2. Seleziona un sistema dal dropdown
3. Opzionalmente seleziona un container all'interno di quel sistema
4. Questa destinazione viene usata quando le release ingerite non specificano un elemento

3. Scegli un Metodo di Integrazione

Archyl supporta tre modi per ingerire release automaticamente.

Metodi di Integrazione

GitHub Actions

Aggiungi la GitHub Action ufficiale di Archyl al tuo workflow di deploy.

Setup minimale:

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

Configurazione 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 fix e miglioramenti delle prestazioni"
    status: deployed

L'action invia versione, commit SHA, ambiente e changelog ad Archyl ad ogni deploy riuscito.

Webhook

Configura l'ingestione webhook per ricevere eventi di release da GitHub o GitLab.

1. Nella scheda impostazioni Release, abilita Webhook
2. Copia l'URL del webhook visualizzato
3. In GitHub o GitLab, aggiungi un nuovo webhook che punta a quell'URL
4. Seleziona il tipo di evento Release o Tag push

Opzioni di configurazione:

Quando una nuova release viene pubblicata o un tag corrispondente viene pushato, Archyl crea automaticamente una voce di release.

API REST

Per qualsiasi strumento CI/CD che può effettuare richieste HTTP -- Jenkins, CircleCI, Bitbucket Pipelines o pipeline personalizzate.

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

Header:

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

Payload:

{
  "version": "v2.4.0",
  "status": "deployed",
  "changelog": "Aggiunta logica di retry per i pagamenti",
  "environmentId": "<environment-uuid>",
  "systemId": "<system-uuid>",
  "containerId": "<container-uuid>",
  "sourceUrl": "https://github.com/org/repo/releases/tag/v2.4.0"
}

La scheda impostazioni mostra snippet di codice copiabili con chiavi API e ID elementi auto-popolati.

Viste

Timeline delle Release

La vista principale. Le release sono raggruppate per mese in ordine cronologico inverso. Ogni voce mostra:

• Badge della versione
• Indicatore di stato
• Tag dell'ambiente (con codifica colore)
• Sistema o container collegato
• Sorgente (GitHub Action, webhook, API, manuale)
• Timestamp relativo

Clicca su qualsiasi release per aprire il pannello dettagli con il changelog completo, le date e un link alla sorgente.

Filtri:

• Per ambiente (es. mostra solo i deploy in produzione)
• Per stato (es. mostra solo i deploy falliti)
• Per elemento collegato

Matrice di Deploy

Una vista a griglia per team che gestiscono più servizi su più ambienti.

• Righe -- Sistemi e container
• Colonne -- Ambienti
• Celle -- Ultima release deployata per quella combinazione

La matrice rende visibile la divergenza degli ambienti a colpo d'occhio. Quando le versioni di staging e produzione divergono, lo noti immediatamente.

Collegare le Release all'Architettura

Ogni release può essere collegata a un sistema, un container o entrambi.

Collegamento Automatico

Quando si usano GitHub Actions o webhook, le release vengono collegate alla destinazione predefinita configurata nelle impostazioni. Puoi sovrascrivere la destinazione per release specificando system-id e container-id.

Collegamento Manuale

Quando crei una release tramite l'interfaccia:

1. Clicca su Nuova Release
2. Compila versione, stato e changelog
3. Seleziona il sistema e/o container di destinazione
4. Scegli l'ambiente
5. Clicca su Crea

Visualizzazione sul Diagramma

Fai clic destro su qualsiasi elemento nel diagramma C4 per aprire il pannello dettagli. Le release collegate appaiono nella sezione Release insieme a relazioni, ADR e contratti API. L'elemento mostra la versione e l'ambiente della release più recente.

Creare Release Manualmente

Non tutte le release vengono da una pipeline. Per creare una release manualmente:

1. Naviga alla scheda Release
2. Clicca su Nuova Release
3. Inserisci la versione, seleziona stato e ambiente
4. Scrivi un changelog (supporto markdown)
5. Collega a un sistema e/o container
6. Clicca su Crea

Le release manuali hanno la sorgente marcata come Manuale nella timeline.

Best Practice

Usa il Versionamento Semantico

• Tagga le release con semver (es. v1.2.3)
• Includi identificatori pre-release per release non di produzione (es. v2.0.0-rc.1)
• Mantieni le stringhe di versione consistenti tra gli ambienti

Traccia Tutti gli Ambienti

• Crea ambienti per ogni fase di deploy
• Non saltare lo staging -- la matrice di deploy è più utile quando mostra la pipeline completa
• Usa la vista matrice per individuare precocemente la divergenza degli ambienti

Automatizza l'Ingestione

• Usa GitHub Actions o webhook invece dell'inserimento manuale
• Configura l'integrazione una volta e ogni deploy fluisce automaticamente
• Riserva la creazione manuale per hotfix o deploy eccezionali

Scrivi i Changelog

• Includi un changelog significativo con ogni release
• Riassumi cosa è cambiato e perché
• Collega a issue o pull request correlate quando possibile

Collega al Livello Giusto

• Collega ai sistemi quando deployi un'intera applicazione
• Collega ai container quando deployi servizi individuali all'interno di un sistema
• Sii consistente -- scegli una convenzione e mantienila

Prossimi Passi

• Contratti API -- Documentare le tue specifiche API
• Insight Architetturali -- Rilevare problemi architetturali
• Richieste di Modifica Architetturale -- Proporre modifiche attraverso un workflow di revisione