GitHub Actions 統合

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

すべてのアクションは archyl-com/actions で公開されており、@v1 でバージョン管理されています。

前提条件

アクションを使用する前に、以下が必要です：

1. Archyl API キー — プロフィール > APIキー で書き込みスコープ付きのキーを作成
2. 組織 ID — 組織の設定ページで確認
3. プロジェクト ID — プロジェクトの URL または設定ページで確認
4. これらを GitHub のシークレットと変数として保存します：

Settings > Secrets > Actions:
  ARCHYL_API_KEY       # Your API key (secret)

Settings > Variables > Actions:
  ARCHYL_ORG_ID        # Organization UUID
  ARCHYL_PROJECT_ID    # Project UUID

クイックスタート

最も手早く始めるには、Archyl の再利用可能なワークフローを使います — PR 用と main ブランチへのプッシュ用の 2 つです：

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

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

jobs:
  # Conformance check + drift score on PRs (run in parallel)
  pr-checks:
    if: github.event_name == 'pull_request'
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

  # Generate context + sync + release on merge to main
  main-sync:
    if: github.event_name == 'push'
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      sync: true
      release: true
      release-environment: 'production'
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

これにより、完全なアーキテクチャガバナンスループが実現します。適合性ルールがすべての PR を検証し、ドリフトスコアがコードとモデルの一致度を追跡し、マージ時にはモデルが自動的に同期されます。

個別のアクション

Conformance Check

プルリクエストで変更されたファイルに対して適合性ルールを実行します。違反をインラインで注釈し、PR コメントでサマリーを投稿します。

- uses: archyl-com/actions/conformance-check@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

入力

出力

出力の使用

- uses: archyl-com/actions/conformance-check@v1
  id: conformance
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    fail-on: none  # Don't fail, handle manually

- name: Custom handling
  if: steps.conformance.outputs.status == 'fail'
  run: |
    echo "Found ${{ steps.conformance.outputs.total-violations }} violations"
    echo "Errors: ${{ steps.conformance.outputs.errors }}"
    echo "Warnings: ${{ steps.conformance.outputs.warnings }}"

Drift Score

アーキテクチャのドリフトスコア（コードベースが C4 モデルとどれだけ一致しているか）を計算します。オプションで、スコアがしきい値を下回った場合にビルドを失敗させる品質ゲートを適用できます。

- uses: archyl-com/actions/drift-score@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    threshold: 70

入力

出力

Generate Context

AI エージェントや LLM 向けに最適化された、アーキテクチャコンテキストを含む archyl.txt ファイルを生成します。ファイルが変更された場合は自動でコミットすることもできます。

- uses: archyl-com/actions/generate-context@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    commit: 'true'

入力

出力

Auto CR

コードが main にマージされたときに、Archyl でアーキテクチャ変更リクエストを自動作成します。diff を分析してアーキテクチャに関わる変更を検出し、レビューのために追跡します。

- uses: archyl-com/actions/auto-cr@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

入力

出力

Release

CI パイプラインから Archyl のリリースを作成または更新します。デプロイを追跡し、環境や C4 要素に関連付け、DORA メトリクスに反映できます。

- uses: archyl-com/actions/release@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    status: deployed
    environment: production

入力

出力

Sync

archyl.yaml DSL ファイルを Archyl と同期します。アーキテクチャをコードとして宣言し、コミットのたびに変更をプッシュできます。

- uses: archyl-com/actions/sync@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

入力

出力

再利用可能なワークフロー

Archyl は、よくあるシナリオ向けに複数のアクションを組み合わせた 2 つの再利用可能なワークフローを提供しています。

archyl-pr.yml

プルリクエストごとに適合性チェックとドリフトスコアを並列で実行します。

jobs:
  archyl:
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70        # Fail if drift score drops below 70
      fail-on: error              # Fail on error-level conformance violations
      comment-on-pr: true         # Post PR comments with results
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

organization-id、project-id、api-key 以外の入力はすべてオプションです。

archyl-main.yml

main へのプッシュ時に generate-context、sync、release を実行します。各ジョブは個別にオン/オフを切り替えられます。

jobs:
  archyl:
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      generate-context: true       # Generate and auto-commit archyl.txt
      context-format: markdown     # LLM-optimized format
      sync: true                   # Sync archyl.yaml to Archyl
      sync-file: archyl.yaml       # Path to your archyl.yaml
      release: true                # Create a release record
      release-status: deployed
      release-environment: production
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

その他の CI プラットフォーム

GitLab CI

Archyl は GitLab 向けに include 可能な CI テンプレートを提供しています。マージリクエストで適合性チェックとドリフトスコアを実行し、デフォルトブランチへのプッシュ時にコンテキストを生成します。

セットアップ：

1. Settings > CI/CD > Variables で必要な CI/CD 変数を追加します：

   • ARCHYL_API_KEY（マスク、保護）
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. .gitlab-ci.yml にテンプレートを include します：

include:
  - remote: 'https://raw.githubusercontent.com/archyl-com/actions/main/ci-templates/gitlab/.archyl-ci.yml'

これにより、パイプラインに 3 つのジョブが追加されます：

• archyl:conformance — マージリクエストで実行
• archyl:drift-score — マージリクエストで実行
• archyl:generate-context — デフォルトブランチへのプッシュ時に実行

オプションの変数：ARCHYL_API_URL、ARCHYL_DRIFT_THRESHOLD。

Bitbucket Pipelines

Archyl のパイプラインテンプレートを bitbucket-pipelines.yml にコピーします。

セットアップ：

1. Settings > Repository variables で必要なリポジトリ変数を追加します：

   • ARCHYL_API_KEY（Secured を有効化）
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. パイプラインのステップを追加します：

pipelines:
  pull-requests:
    '**':
      - step:
          name: "Archyl Conformance Check"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq git
            - # ... conformance check script
      - step:
          name: "Archyl Drift Score"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq
            - # ... drift score script

  branches:
    main:
      - step:
          name: "Archyl Generate Context"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq git
            - # ... generate context script

完全なテンプレートは archyl-com/actions/ci-templates/bitbucket/archyl-pipelines.yml で入手できます。

組み合わせの例

6 つのアクションすべてを組み合わせた完全なワークフロー：

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

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

jobs:
  # --- PR checks (parallel) ---

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

  drift:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          threshold: 70
          comment-on-pr: 'true'

  # --- Main branch (after merge) ---

  generate-context:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/generate-context@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          commit: 'true'

  sync:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  auto-cr:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: archyl-com/actions/auto-cr@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  release:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/release@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          status: deployed
          environment: production
          source-url: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}

結果の確認

CI からトリガーされたすべてのチェックの結果は Archyl に表示されます：

• 適合性チェック — 適合性ダッシュボード（エージェントハブ > ダッシュボード タブ）に表示されます。チェックをクリックすると、ファイルごとにグループ化された違反を確認できます。
• ドリフトスコア — プロジェクトのドリフトセクションに表示されます。スコアの推移を時系列で追跡できます。
• 変更リクエスト — リクエストセクションに表示されます。アーキテクチャの変更を受け入れる前にレビューできます。
• リリース — リリースセクションと環境ページに表示されます。DORA メトリクスに反映されます。
• 同期結果 — C4 モデルに即座に反映されます。

適合性ダッシュボードの詳細は 適合性ルール を参照してください。

セルフホスト Archyl

Archyl をオンプレミスで実行している場合は、各アクションの api-url 入力にインスタンスの URL を設定します：

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

すべてのアクションで、デフォルトは https://api.archyl.com です。