アーキテクチャダイアグラムは何が存在するかを示します。今やそれに加えて、何がリリースされたかも示します。Archyl の新しいリリース管理機能では、GitHub Actions、Webhooks、REST API からの取り込みにより、システムと環境をまたいでデプロイメントを追跡できます。

リリース管理：アーキテクチャ全体のデプロイメントを追跡する

2ヶ月前、ポストモーテムに同席しました。中心的な問いは一見シンプルでした。「本番環境で現在動いている決済サービスのバージョンは？」

4人が3つの異なる回答をしました。一人は GitHub Releases ページを確認しました。もう一人は ArgoCD を開きました。三人目は Slack のデプロイチャンネルをスクロールしました。四人目——実際にデプロイした本人——は休暇中でした。

これはスタートアップではありません。成熟した CI/CD パイプライン、適切なタグ付け慣行、そして Archyl で適切にメンテナンスされたアーキテクチャダイアグラムを持つチームでした。ダイアグラムはどのシステムが存在し、どう接続され、どのプロトコルを使っているかを正確に教えてくれました。ただ、何が実際にどのバージョンで動いているかは教えてくれませんでした。どこにおいても。

このギャップがずっと気になっていました。アーキテクチャドキュメントはシステムの構造を教えてくれます。デプロイ履歴はシステムの状態を教えてくれます。この2つは一緒にあるべきです。今日、それが実現しました。

アーキテクチャにリンクされたリリース

Archyl のリリース管理は、アーキテクチャワークスペースのファーストクラスオブジェクトとしてデプロイメントを追跡します。リリースにはバージョン、ステータス、環境、変更ログ、そして——重要なことに——所属する C4 要素へのリンクがあります。

最後の点が CI/CD ダッシュボードとの違いを生みます。GitHub Actions のランは v2.4.0 がデプロイされたことを教えてくれます。しかし、アーキテクチャの文脈でどこにデプロイされたのか？どのシステム？どのコンテナ？Archyl のリリースは、デプロイイベントを C4 ダイアグラム上のシステムやコンテナに直接接続することでこれに答えます。

システムの詳細パネルを開くと、リレーションシップ、ADR、API コントラクトと並んで最近のリリースが表示されます。アーキテクチャダイアグラムは生きたマップになります——何が存在するかだけでなく、何がいつリリースされたかも示します。

3つの取り込み方法

リリース追跡がさらなる手動作業を意味することは避けたかったのです。すでにパイプラインでデプロイしているなら、リリースは自動的に Archyl に流れ込むべきです。

GitHub Actions — デプロイメントワークフローに組み込める公式 GitHub Actionを公開しています。最小限のセットアップは YAML の2行です。Action はデプロイが成功するたびに、バージョン、コミット SHA、環境、変更ログを Archyl に送信します。カスタムフィールドもサポートしています——特定のシステムやコンテナへのリンク、ステータスの設定、著者情報の含有。

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

以上です。すべてのタグ付きリリースがアーキテクチャワークスペースに表示されるようになります。

Webhooks — プロジェクト設定で webhook エンドポイントを設定し、GitHub または GitLab のリリース webhook をそこに向けます。新しいリリースが公開されるかタグがプッシュされると、Archyl がイベントを受信し自動的にリリースエントリを作成します。タグパターン（例：v*）を設定してどのタグがリリースを作成するかをフィルタリングし、デフォルト環境を指定して webhook で作成されたリリースが適切な場所に配置されるようにできます。

REST API — Jenkins、CircleCI、Bitbucket Pipelines、その他の CI/CD ツールを使うチーム向けに、取り込みエンドポイントはシンプルな JSON ペイロードを受け付けます。API キーで認証し、バージョンとメタデータを送信すれば、リリースが Archyl に表示されます。これはユニバーサルなエスケープハッチです——HTTP リクエストを送信できるツールなら、リリースを報告できます。

3つの方法すべてがプロジェクト設定の Releases タブで設定でき、コピー可能なコードスニペットと自動入力された API キーが提供されます。

環境

すべてのデプロイが同じではありません。ステージングへのプッシュは日常的です。本番へのプッシュはイベントです。リリース管理はこの2つを別々に追跡します。

環境はユーザー定義でカラーコード付きです。「Development」「Staging」「Production」——チームが使う名前で作成します。各リリースはターゲット環境でタグ付けされ、本番デプロイのみ、または現在ステージングにあるものだけを表示するようにタイムラインをフィルタリングできます。

環境モデルは柔軟です。単一のサービスを運用するチームは2つの環境かもしれません。40のマイクロサービスを管理するプラットフォームチームは5つかもしれません。プロジェクトに合うものを定義すれば、リリースはそれに応じて自動整理されます。

タイムライン

リリースタイムラインがプライマリビューです。リリースは月ごとにグループ化され、逆時系列で表示され、バージョンバッジ、環境タグ、ステータスインジケーターが付いています。「最近何が起きたか？」への回答が一目で分かります。

各リリースエントリには以下が表示されます：

バージョン — semver タグまたは識別子（例：v2.4.0、3.12.0-rc.2）
ステータス — Deployed、In Progress、Planned、Failed、または Rolled Back
環境 — カラーコード付きバッジ（Production、Staging など）
リンクされた要素 — このリリースが属するシステムまたはコンテナ
ソース — リリースの出所（GitHub Action、webhook、API、手動）
変更ログ — 何が変更されたか、誰が著者か、署名情報

リリースをクリックすると、完全な変更ログ、日付（作成、リリース、更新）、影響を受ける C4 要素、ソースへのリンク（コミット、GitHub Release ページなど）を含む詳細パネルが開きます。

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

複数のサービスを複数の環境で管理するチーム向けに、2つ目のビューを構築しました：デプロイメントマトリクス。

これは、行がシステムとコンテナ、列が環境のグリッドで、各セルにはその組み合わせにデプロイされた最新リリースが表示されます。一目で、アカウント API が本番では v3.1.0 だがステージングでは v3.2.0-beta であること、または通知サービスが3週間本番にデプロイされていないことが分かります。

マトリクスは環境のドリフトを可視化します。ステージングと本番のバージョンが乖離したとき、すぐに気づけます。あるサービスが遅れている一方で他のサービスが進んでいるとき、そのギャップは明白です。

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

リリースは常にクリーンとは限りません。デプロイは失敗します。リリースはロールバックされます。完全なライフサイクルを追跡します：

Planned — リリースは存在するがまだデプロイされていない。今後のバージョンの追跡に有用。
In Progress — デプロイメントが進行中。CI/CD 統合によりデプロイステップ中に自動設定。
Deployed — リリースがターゲット環境で稼働中。正常パス。
Failed — デプロイメントが成功しなかった。リリースエントリは試行の記録として残る。
Rolled Back — リリースはデプロイされたが、その後リバートされた。履歴が保持されます——v2.3.1 がロールバックされたこと、いつ、なぜかが分かります。

CI/CD 統合を使用する場合、ステータス遷移は自動です。UI でリリースを作成する場合は手動です。

アーキテクチャ要素へのリンク

すべてのリリースはシステム、コンテナ、またはその両方にリンクできます。これがリリースにアーキテクチャ的なコンテキストを与えるものです。

プロジェクト設定で、デフォルトのリンクターゲット——リリースが紐付けられるシステムとオプションでコンテナ——を設定します。GitHub Actions、webhooks、REST API のコードスニペットは、正しい要素 ID を含むように自動的に更新されます。

ダイアグラム上では、リンクされた要素の詳細パネルにリリース履歴が表示されます。コンテナを右クリックすると、リレーションシップやコントラクトだけでなく、デプロイメントタイムラインも表示されます。ここがアーキテクチャドキュメントと運用の現実が交わる場所です。

なぜこれが重要か

アーキテクチャダイアグラムは常にある時点のスナップショットでした。システムが何であるか——ボックス、矢印、プロトコル——を示します。しかし、システムが何をしているかは示しません。そのサービスは最新バージョンか？最後のデプロイはいつか？先週火曜日のリリースを誰かがロールバックしたか？

これらの質問は、すべてのアーキテクチャレビュー、すべてのインシデント対応、すべてのオンボーディング会話で出てきます。これまで答えは常に「CI/CD ツールを確認して」か「それを担当するチームに聞いて」でした。

リリース管理はデプロイ履歴をそれがあるべき場所に置きます：アーキテクチャ自体の上に。「決済ゲートウェイのバージョンは？」と聞かれたとき、答えはダイアグラム上にあります——別のツールでも、別のタブでも、誰かの頭の中でもなく。

これは API コントラクトや ADR と同じ哲学です。アーキテクチャドキュメントは毎日出てくる本当の質問に答えるべきであり、構造を抽象的に記述するだけではいけません。

はじめに

プロジェクトの設定に移動し、Releases タブを開きます。統合方法——GitHub Action、webhooks、または REST API——を選択し、セットアップガイドに従ってください。環境を作成し、ターゲットのシステムまたはコンテナをリンクし、最初のリリースをデプロイします。

その時点から、すべてのデプロイメントが自動的にアーキテクチャワークスペースに流れ込みます。C4 ダイアグラムは静的なブループリントではなく、実際に何が動いているかの生きた記録になります。

アーキテクチャは構造だけではありません。ツールもそれを反映するようになりました。

アーキテクチャを現実につなげることについてもっと知りたいですか？API コントラクトがスペックをダイアグラムにリンクする方法や、アーキテクチャ変更リクエストが C4 モデルにプルリクエストワークフローをもたらす方法をご覧ください。

リリース管理：アーキテクチャ全体のデプロイメントを追跡する - Archyl Blog