GitHub Actions 統合

Archyl は、アーキテクチャガバナンスを CI/CD パイプラインに直接統合する2つの公式 GitHub Actions を提供しています：

前提条件

Actions を使用する前に、以下が必要です：

1. Archyl API キー — Profile > API Keys で書き込みスコープ付きのキーを作成
2. Project ID — プロジェクトの URL または設定ページで確認
3. API キーを GitHub シークレットとして保存: Settings > Secrets > Actions > ARCHYL_API_KEY
4. オプションでプロジェクト ID を変数として保存: Settings > Variables > Actions > ARCHYL_PROJECT_ID

Conformance Check Action

プルリクエストごとに適合性ルールを実行し、違反を PR コメントとコミットステータスチェックとして報告します。

クイックセットアップ

# .github/workflows/archyl-conformance.yml
name: Architecture Conformance

on:
  pull_request:
    branches: [main]

jobs:
  conformance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl/archyl/.github/actions/conformance-check@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

動作の仕組み

1. Action が PR で変更されたすべてのファイルを収集
2. ファイル内容が head SHA で取得される
3. ファイル＋内容が評価のために Archyl API に送信される
4. 有効なすべての適合性ルールが変更ファイルに対して評価される
5. コミットステータスが投稿される（合格/不合格）
6. 違反の詳細を含む PR コメントが投稿される
7. Critical または High の違反が見つかった場合、ワークフローが失敗する

PR コメント

違反が見つかると、Archyl は次のようなコメントを投稿します：

Archyl Conformance Check — Failed

12 ファイル分析 — 3 件の違反が見つかりました。

重大度	件数
Critical	1
High	2

コメントは後続のプッシュで更新されます — 重複コメントは作成されません。

入力

出力

出力の使用

後続のステップで出力を使用できます：

- uses: archyl/archyl/.github/actions/conformance-check@main
  id: archyl
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    fail-on-violations: "false"  # 失敗させず、手動で処理

- name: Custom handling
  if: steps.archyl.outputs.passed == 'false'
  run: |
    echo "Found ${{ steps.archyl.outputs.violations }} violations"
    echo "Critical: ${{ steps.archyl.outputs.critical }}"
    echo "High: ${{ steps.archyl.outputs.high }}"

Incremental Discovery Action

デフォルトブランチへのプッシュ時に変更ファイルを分析し、C4 モデルを最新に保つための保留中のディスカバリーを作成します。

クイックセットアップ

# .github/workflows/archyl-discovery.yml
name: Architecture Sync

on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # git diff に必要
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

動作の仕組み

1. Action が前回のコミットと現在のコミット間の git diff を計算
2. 変更ファイルの内容が head SHA で取得される
3. ファイルが AI 分析のために Archyl API に送信される
4. ソースファイルのみが分析される（テストファイル、生成コードなどはスキップ）
5. 新しい C4 要素がレビュー用の保留中のディスカバリーとして作成される
6. 既存の要素は自動的に重複排除される — 重複なし
7. ディスカバリージョブステータスを含むステップサマリーが投稿される

入力

出力

重要な注意事項

• checkout ステップで fetch-depth: 2 が必要（git が diff を計算するため）
• ディスカバリーは保留中の要素を作成します — 承認するまで C4 モデルには表示されません
• ソースファイルのみが分析されます（.go、.ts、.py、.java など） — 設定ファイル、ドキュメント、アセットはスキップされます
• Action は push と pull_request の両方のイベントで動作します

組み合わせワークフロー

推奨セットアップは両方の Actions を併用します — PR で適合性チェック、マージでディスカバリー：

# .github/workflows/archyl.yml
name: Archyl Architecture

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  conformance:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl/archyl/.github/actions/conformance-check@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  discovery:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

これにより、完全なアーキテクチャガバナンスループが実現します：

1. 開発者が PR を作成
2. 適合性ルールがアーキテクチャに対して変更を検証
3. 違反が PR コメントとして報告される
4. 承認・マージ後、インクリメンタルディスカバリーが C4 モデルを更新
5. モデルは次の PR チェックに向けて常に最新

セルフホスト Archyl

Archyl をオンプレミスで実行している場合、api-url 入力をインスタンスに設定します：

- uses: archyl/archyl/.github/actions/conformance-check@main
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    api-url: "https://archyl.internal.company.com/api/v1"

Webhook 代替手段

GitHub Actions よりも Webhook を好む場合、プロジェクト設定で直接 push/PR Webhook を設定できます。詳細は Webhooks を参照してください。

Webhook アプローチ：

• GitHub Action の設定が不要
• API アクセスにプロジェクトオーナーの OAuth トークンを使用
• GitHub と GitLab をサポート
• Archyl のインフラストラクチャで実行（GitHub Action の分数を消費しない）

GitHub Action アプローチ：

• 自分の API キーを使用（より明示的）
• GitHub のインフラストラクチャで実行
• カスタマイズが容易（条件追加、パスフィルタリング、他のステップとの組み合わせ）
• GitHub Actions をサポートするすべての Git プロバイダーで動作