リリース管理

リリース管理は、デプロイメントをアーキテクチャワークスペースのファーストクラスオブジェクトとして追跡します。すべてのリリースは C4 要素にリンクされ、ダイアグラムで実際に稼働しているものをリアルタイムで確認できます。

コアコンセプト

リリース

リリースは、環境にデプロイされた特定のバージョンを表します。各リリースには以下の情報があります：

環境

環境はデプロイメントターゲットを表します。ユーザー定義でカラーコード化されています。

一般的なセットアップには以下があります：

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

ワークフローに必要な数の環境を作成できます。各リリースにはターゲット環境がタグ付けされます。

ステータスライフサイクル

リリースは以下のステータスを経由します：

リリース追跡のセットアップ

1. 環境の作成

1. プロジェクトの 設定 に移動
2. リリース タブを開く
3. 環境 の下で 環境を追加 をクリック
4. 名前を入力し色を選択
5. ドラッグしてデプロイメントステージ順に並べ替え

2. デフォルトリンクターゲットの設定

リリースをデフォルトで関連付けるシステムとオプションでコンテナを設定：

1. リリース設定タブで デフォルトリンクターゲット を見つける
2. ドロップダウンからシステムを選択
3. オプションでそのシステム内のコンテナを選択
4. このターゲットは、取り込まれたリリースが要素を指定しない場合に使用される

3. 統合方法の選択

Archyl はリリースを自動的に取り込む3つの方法をサポートしています。

統合方法

GitHub Actions

公式 Archyl GitHub Action をデプロイメントワークフローに追加します。

最小セットアップ：

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

完全な設定：

- 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

このアクションは、デプロイ成功時にバージョン、コミット SHA、環境、変更履歴を Archyl に送信します。

Webhook

GitHub または GitLab からリリースイベントを受信するように Webhook 取り込みを設定します。

1. リリース設定タブで Webhook を有効化
2. 表示された Webhook URL をコピー
3. GitHub または GitLab で、その URL を指す新しい Webhook を追加
4. Release または Tag push イベントタイプを選択

設定オプション：

新しいリリースが公開されるか、一致するタグがプッシュされると、Archyl は自動的にリリースエントリを作成します。

REST API

HTTP リクエストが可能なあらゆる CI/CD ツール（Jenkins、CircleCI、Bitbucket Pipelines、カスタムパイプラインなど）で使用できます。

エンドポイント： POST /api/v1/projects/:projectId/releases

ヘッダー：

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

ペイロード：

{
  "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"
}

設定タブには、API キーと要素 ID が自動入力されたコピー可能なコードスニペットが表示されます。

ビュー

リリースタイムライン

メインのビューです。リリースは月ごとに新しい順にグループ化されます。各エントリには以下が表示されます：

• バージョンバッジ
• ステータスインジケーター
• 環境タグ（カラーコード）
• リンクされたシステムまたはコンテナ
• ソース（GitHub Action、Webhook、API、手動）
• 相対タイムスタンプ

リリースをクリックすると、完全な変更履歴、日付、ソースへのリンクを含む詳細パネルが開きます。

フィルタリング：

• 環境別（例：本番デプロイのみ表示）
• ステータス別（例：失敗したデプロイメントのみ表示）
• リンク要素別

デプロイメントマトリックス

複数のサービスを複数の環境で管理するチーム向けのグリッドビュー。

• 行 — システムとコンテナ
• 列 — 環境
• セル — その組み合わせにデプロイされた最新リリース

マトリックスにより、環境のドリフトが一目でわかります。ステージングと本番のバージョンが分岐すると、すぐに気づけます。

リリースとアーキテクチャのリンク

すべてのリリースは、システム、コンテナ、またはその両方にリンクできます。

自動リンク

GitHub Actions や Webhook を使用する場合、リリースは設定でコンフィギュレーションされたデフォルトターゲットにリンクされます。system-id と container-id を指定することで、リリースごとにターゲットを上書きできます。

手動リンク

UI からリリースを作成する場合：

1. 新規リリース をクリック
2. バージョン、ステータス、変更履歴を入力
3. ターゲットのシステムおよび/またはコンテナを選択
4. 環境を選択
5. 作成 をクリック

ダイアグラムでの表示

C4 ダイアグラム上の任意の要素を右クリックして詳細パネルを開きます。リンクされたリリースは、関係、ADR、API コントラクトと並んで リリース セクションに表示されます。要素には最新のリリースバージョンと環境が表示されます。

手動でのリリース作成

すべてのリリースがパイプラインから来るわけではありません。手動でリリースを作成するには：

1. リリース タブに移動
2. 新規リリース をクリック
3. バージョンを入力し、ステータスと環境を選択
4. 変更履歴を記入（Markdown 対応）
5. システムおよび/またはコンテナにリンク
6. 作成 をクリック

手動リリースは、タイムラインでソースが 手動 と表示されます。

ベストプラクティス

セマンティックバージョニングの使用

• セマンティックバージョニングでリリースにタグ付け（例：v1.2.3）
• 本番以外のリリースにはプレリリース識別子を含める（例：v2.0.0-rc.1）
• 環境間でバージョン文字列の一貫性を保つ

すべての環境を追跡

• すべてのデプロイメントステージの環境を作成
• ステージングを省略しない — デプロイメントマトリックスは完全なパイプラインを表示するときが最も有用
• マトリックスビューを使用して環境のドリフトを早期に発見

取り込みの自動化

• 手動入力の代わりに GitHub Actions や Webhook を使用
• 統合を一度設定すれば、すべてのデプロイメントが自動的に記録される
• 手動作成はホットフィックスや例外的なデプロイメントに限定

変更履歴の記載

• すべてのリリースに意味のある変更履歴を含める
• 何が変更されたか、なぜ変更されたかを要約
• 可能な場合は関連する Issue やプルリクエストにリンク

適切なレベルにリンク

• アプリケーション全体をデプロイする場合は システム にリンク
• システム内の個別サービスをデプロイする場合は コンテナ にリンク
• 一貫性を保つ — 慣例を選んでそれに従う

次のステップ

• API コントラクト — API 仕様のドキュメント化
• アーキテクチャインサイト — アーキテクチャの問題を検出
• アーキテクチャ変更リクエスト — レビューワークフローを通じた変更提案