Gestion des Releases

La Gestion des Releases suit les déploiements comme objets de première classe dans votre espace d'architecture. Chaque release est liée à un élément C4, donnant à vos diagrammes une vue en temps réel de ce qui tourne réellement.

Concepts Fondamentaux

Releases

Une release représente une version spécifique déployée dans un environnement. Chaque release possède :

Environnements

Les environnements représentent les cibles de déploiement. Ils sont définis par l'utilisateur et associés à un code couleur.

Configurations courantes :

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

Créez autant d'environnements que votre workflow le nécessite. Chaque release est taguée avec son environnement cible.

Cycle de Vie des Statuts

Les releases passent par ces statuts :

Configurer le Suivi des Releases

1. Créer les Environnements

1. Allez dans les Paramètres de votre projet
2. Ouvrez l'onglet Releases
3. Sous Environnements, cliquez sur Ajouter un Environnement
4. Entrez un nom et choisissez une couleur
5. Glissez pour réordonner les environnements par étape de déploiement

2. Configurer une Cible de Liaison par Défaut

Définissez le système et optionnellement un conteneur où les releases seront attachées par défaut :

1. Dans l'onglet Releases des paramètres, trouvez Cible de Liaison par Défaut
2. Sélectionnez un système dans le menu déroulant
3. Optionnellement, sélectionnez un conteneur dans ce système
4. Cette cible est utilisée quand les releases ingérées ne spécifient pas d'élément

3. Choisir une Méthode d'Intégration

Archyl supporte trois façons d'ingérer automatiquement les releases.

Méthodes d'Intégration

GitHub Actions

Ajoutez la GitHub Action officielle d'Archyl à votre workflow de déploiement.

Configuration minimale :

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

Configuration complète :

- 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: "Corrections de bugs et améliorations de performance"
    status: deployed

L'action envoie la version, le SHA du commit, l'environnement et le changelog à Archyl à chaque déploiement réussi.

Webhooks

Configurez l'ingestion par webhook pour recevoir les événements de release depuis GitHub ou GitLab.

1. Dans l'onglet Releases des paramètres, activez les Webhooks
2. Copiez l'URL du webhook affichée
3. Dans GitHub ou GitLab, ajoutez un nouveau webhook pointant vers cette URL
4. Sélectionnez le type d'événement Release ou Tag push

Options de configuration :

Quand une nouvelle release est publiée ou un tag correspondant est poussé, Archyl crée automatiquement une entrée de release.

API REST

Pour tout outil CI/CD capable de faire des requêtes HTTP — Jenkins, CircleCI, Bitbucket Pipelines ou pipelines personnalisés.

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

Headers :

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

Payload :

{
  "version": "v2.4.0",
  "status": "deployed",
  "changelog": "Ajout de la logique de retry pour les paiements",
  "environmentId": "<environment-uuid>",
  "systemId": "<system-uuid>",
  "containerId": "<container-uuid>",
  "sourceUrl": "https://github.com/org/repo/releases/tag/v2.4.0"
}

L'onglet paramètres affiche des snippets de code copiables avec les clés API et IDs d'éléments pré-remplis.

Vues

Timeline des Releases

La vue principale. Les releases sont groupées par mois en ordre chronologique inverse. Chaque entrée affiche :

• Badge de version
• Indicateur de statut
• Tag d'environnement (code couleur)
• Système ou conteneur lié
• Source (GitHub Action, webhook, API, manuelle)
• Horodatage relatif

Cliquez sur une release pour ouvrir son panneau de détail avec le changelog complet, les dates et un lien vers la source.

Filtrage :

• Par environnement (ex. afficher uniquement les déploiements production)
• Par statut (ex. afficher uniquement les déploiements échoués)
• Par élément lié

Matrice de Déploiement

Une vue en grille pour les équipes gérant plusieurs services à travers plusieurs environnements.

• Lignes — Systèmes et conteneurs
• Colonnes — Environnements
• Cellules — Dernière release déployée pour cette combinaison

La matrice rend la dérive d'environnement visible en un coup d'œil. Quand les versions staging et production divergent, vous le repérez immédiatement.

Lier les Releases à l'Architecture

Chaque release peut être liée à un système, un conteneur, ou les deux.

Liaison Automatique

Avec GitHub Actions ou les webhooks, les releases sont liées à la cible par défaut configurée dans les paramètres. Vous pouvez surcharger la cible par release en spécifiant system-id et container-id.

Liaison Manuelle

Lors de la création d'une release via l'interface :

1. Cliquez sur Nouvelle Release
2. Remplissez la version, le statut et le changelog
3. Sélectionnez le système et/ou conteneur cible
4. Choisissez l'environnement
5. Cliquez sur Créer

Visualisation sur le Diagramme

Faites un clic droit sur n'importe quel élément du diagramme C4 pour ouvrir son panneau de détail. Les releases liées apparaissent dans la section Releases aux côtés des relations, ADR et contrats d'API. L'élément affiche sa version de release la plus récente et son environnement.

Créer des Releases Manuellement

Toutes les releases ne viennent pas d'un pipeline. Pour créer une release à la main :

1. Naviguez vers l'onglet Releases
2. Cliquez sur Nouvelle Release
3. Entrez la version, sélectionnez un statut et un environnement
4. Écrivez un changelog (markdown supporté)
5. Liez à un système et/ou conteneur
6. Cliquez sur Créer

Les releases manuelles ont leur source marquée comme Manuelle dans la timeline.

Bonnes Pratiques

Utilisez le Versionnage Sémantique

• Taguez les releases en semver (ex. v1.2.3)
• Incluez des identifiants de pré-release pour les déploiements hors production (ex. v2.0.0-rc.1)
• Gardez les chaînes de version cohérentes entre les environnements

Suivez Tous les Environnements

• Créez des environnements pour chaque étape de déploiement
• Ne sautez pas le staging — la matrice de déploiement est plus utile quand elle montre le pipeline complet
• Utilisez la vue matrice pour détecter la dérive d'environnement tôt

Automatisez l'Ingestion

• Utilisez GitHub Actions ou les webhooks plutôt que la saisie manuelle
• Configurez l'intégration une fois et chaque déploiement arrive automatiquement
• Réservez la création manuelle pour les hotfixes ou déploiements exceptionnels

Écrivez des Changelogs

• Incluez un changelog pertinent avec chaque release
• Résumez ce qui a changé et pourquoi
• Liez aux issues ou pull requests associées quand c'est possible

Liez au Bon Niveau

• Liez aux systèmes lors du déploiement d'une application entière
• Liez aux conteneurs lors du déploiement de services individuels au sein d'un système
• Soyez cohérent — choisissez une convention et respectez-la

Prochaines Étapes

• Contrats d'API — Documentez vos spécifications d'API
• Insights d'Architecture — Détectez les problèmes architecturaux
• Demandes de Changement d'Architecture — Proposez des modifications via un workflow de revue