CI/CD 統合ガイド

Framedash CLI はあらゆる CI/CD システムと統合できます。このガイドでは Jenkins と TeamCity のすぐに使える例を紹介します。

前提条件

1. CI 環境に CLI をインストール:

npm install -g @framedash/cli

2. パフォーマンスゲートの例では jq と bc を使用します。CI エージェントにインストールされていることを確認してください。
3. Framedash ダッシュボードの 設定 > API キー で API キーを作成します。
4. プロジェクト設定ページから プロジェクト ID を確認します。

環境変数

CI システムのシークレット管理で以下を設定してください:

変数	必須	説明
FRAMEDASH_API_KEY	はい	API キー（アップロード: fd_admin_*、読み取り専用: fd_*）
FRAMEDASH_PROJECT_ID	はい	対象プロジェクトの UUID
FRAMEDASH_BASE_URL	いいえ	カスタム API ホスト URL（デフォルト: https://app.framedash.dev）

---

Jenkins

認証情報の設定

API キーを Jenkins 認証情報（Secret text）として保存します:

1. Jenkins の管理 > 認証情報 > System > グローバル認証情報 を開きます
2. ID framedash-api-key で Secret text 認証情報を追加します
3. ID framedash-project-id で Secret text 認証情報を追加します

宣言的パイプライン

ビルド後テレメトリ確認

自動テスト実行後にゲームビルドがテレメトリを送信していることを確認します:

pipeline {
    agent any

    environment {
        FRAMEDASH_API_KEY = credentials('framedash-api-key')
        FRAMEDASH_PROJECT_ID = credentials('framedash-project-id')
    }

    stages {
        stage('Build') {
            steps {
                sh 'your-game-build-command'
            }
        }

        stage('Automated Test') {
            steps {
                sh 'your-automated-test-command'
            }
        }

        stage('Verify Telemetry') {
            steps {
                sh '''
                    framedash auth
                    framedash status --format json > status.json
                    echo "Project status:"
                    framedash status --format table
                '''
            }
        }
    }
}

パフォーマンスリグレッションゲート

パフォーマンスメトリクスが閾値を下回った場合にビルドを失敗させます:

pipeline {
    agent any

    environment {
        FRAMEDASH_API_KEY = credentials('framedash-api-key')
        FRAMEDASH_PROJECT_ID = credentials('framedash-project-id')
    }

    stages {
        stage('Build & Test') {
            steps {
                sh 'your-game-build-and-test-command'
            }
        }

        stage('Performance Gate') {
            steps {
                sh '''
                    RESULT=$(framedash query \
                        "SELECT avg(fps) as avg_fps, \
                                avg(frame_time_ms) as avg_frame_time \
                         FROM events \
                         WHERE event_name = 'performance_sample' \
                           AND timestamp > now() - INTERVAL 1 HOUR" \
                        --format json)

                    AVG_FPS=$(echo "$RESULT" | jq -r '.data[0].avg_fps // 0')

                    echo "Average FPS: $AVG_FPS"

                    if [ "$(echo "$AVG_FPS < 30" | bc -l)" -eq 1 ]; then
                        echo "FAILED: FPS below 30 threshold ($AVG_FPS)"
                        exit 1
                    fi

                    echo "PASSED: FPS meets threshold"
                '''
            }
        }
    }

    post {
        failure {
            echo 'Performance regression detected. Check the Framedash dashboard for details.'
        }
    }
}

マップキャプチャアップロード

レベルビルド後にマップ画像を自動アップロードします:

pipeline {
    agent any

    environment {
        FRAMEDASH_API_KEY = credentials('framedash-api-key')
        FRAMEDASH_PROJECT_ID = credentials('framedash-project-id')
    }

    stages {
        stage('Build Level') {
            steps {
                sh 'your-level-build-command'
            }
        }

        stage('Capture Maps') {
            steps {
                sh 'your-map-capture-command --output-dir ./map_captures'
            }
        }

        stage('Upload Maps') {
            steps {
                sh '''
                    framedash map-capture \
                        --input-dir ./map_captures \
                        --upload
                '''
            }
        }
    }
}

コンテンツレジストリ同期

ゲームデータとコンテンツレジストリを同期します:

pipeline {
    agent any

    environment {
        FRAMEDASH_API_KEY = credentials('framedash-api-key')
        FRAMEDASH_PROJECT_ID = credentials('framedash-project-id')
    }

    stages {
        stage('Sync Content') {
            steps {
                sh '''
                    framedash content import ./game-content.json
                    echo "Content registry updated"
                    framedash content list --format table
                '''
            }
        }
    }
}

共有ライブラリ

複数のゲームプロジェクトを持つ組織向けに、Jenkins 共有ライブラリを作成できます:

vars/framedashReport.groovy

def call(Map config = [:]) {
    def queryDays = config.get('days', 7)

    withCredentials([
        string(credentialsId: config.apiKeyCredentialId ?: 'framedash-api-key', variable: 'FRAMEDASH_API_KEY'),
        string(credentialsId: config.projectIdCredentialId ?: 'framedash-project-id', variable: 'FRAMEDASH_PROJECT_ID')
    ]) {
        sh """
            echo "Framedash dashboard (${queryDays}-day summary):"
            framedash dashboard --days ${queryDays} --format table
        """
    }
}

Jenkinsfile での使用例:

@Library('your-shared-lib') _

pipeline {
    agent any
    stages {
        stage('Framedash Report') {
            steps {
                framedashReport(days: 7)
            }
        }
    }
}

---

TeamCity

パラメータ設定

ビルド構成に 構成パラメータ として追加します:

1. ビルド構成 > パラメータ を開きます
2. パラメータ env.FRAMEDASH_API_KEY を追加（タイプ: Password、spec: password display='hidden'）
3. パラメータ env.FRAMEDASH_PROJECT_ID を追加（タイプ: Text）

または プロジェクト レベルで定義してビルド構成間で共有することもできます。

ビルドステップ

ビルド後テレメトリ確認

コマンドライン ビルドステップを追加します:

ステップ名: Verify Framedash Telemetry

#!/bin/bash
set -euo pipefail

echo "Verifying Framedash authentication..."
framedash auth

echo "Project status:"
framedash status --format table

パフォーマンスリグレッションゲート

コマンドライン ビルドステップを追加します:

ステップ名: Framedash Performance Gate

#!/bin/bash
set -euo pipefail

echo "Querying performance metrics..."
RESULT=$(framedash query \
    "SELECT avg(fps) as avg_fps, \
            avg(frame_time_ms) as avg_frame_time \
     FROM events \
     WHERE event_name = 'performance_sample' \
       AND timestamp > now() - INTERVAL 1 HOUR" \
    --format json)

AVG_FPS=$(echo "$RESULT" | jq -r '.data[0].avg_fps // 0')

echo "Average FPS: $AVG_FPS"

if [ "$(echo "$AVG_FPS < 30" | bc -l)" -eq 1 ]; then
    echo "##teamcity[buildProblem description='FPS below threshold: $AVG_FPS']"
    exit 1
fi

echo "##teamcity[buildStatisticValue key='framedash.avgFps' value='$AVG_FPS']"
echo "Performance gate passed"

ヒント

TeamCity のサービスメッセージを使用して、カスタム統計やビルド問題を報告できます。buildStatisticValue メッセージにより、FPS を TeamCity の統計チャートで追跡できます。

マップキャプチャアップロード

コマンドライン ビルドステップを追加します:

ステップ名: Upload Map Captures

#!/bin/bash
set -euo pipefail

echo "Validating map captures..."
framedash map-capture --input-dir ./map_captures --dry-run

echo "Uploading map captures..."
framedash map-capture --input-dir ./map_captures --upload

ファネル分析レポート

コンバージョンファネルを追跡するコマンドラインビルドステップを追加します:

#!/bin/bash
set -euo pipefail

echo "Funnel analysis (7-day window):"
framedash funnel \
    --steps "tutorial_start,tutorial_complete,first_purchase" \
    --days 7 \
    --format table

ビルド構成テンプレート（Kotlin DSL）

Kotlin DSL を使用する TeamCity プロジェクト向け:

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

object FramedashPerformanceGate : BuildType({
    name = "Framedash Performance Gate"

    params {
        password("env.FRAMEDASH_API_KEY", "", display = ParameterDisplay.HIDDEN)
        text("env.FRAMEDASH_PROJECT_ID", "")
        text("framedash.minFps", "30", label = "Minimum FPS Threshold")
    }

    steps {
        script {
            name = "Install Framedash CLI"
            scriptContent = "npm install -g @framedash/cli"
        }
        script {
            name = "Performance Gate"
            scriptContent = """
                #!/bin/bash
                set -euo pipefail

                MIN_FPS=%framedash.minFps%

                RESULT=${'$'}(framedash query \
                    "SELECT avg(fps) as avg_fps FROM events \
                     WHERE event_name = 'performance_sample' \
                       AND timestamp > now() - INTERVAL 1 HOUR" \
                    --format json)

                AVG_FPS=${'$'}(echo "${'$'}RESULT" | jq -r '.data[0].avg_fps // 0')

                echo "Average FPS: ${'$'}AVG_FPS (threshold: ${'$'}MIN_FPS)"

                if [ "${'$'}(echo "${'$'}AVG_FPS < ${'$'}MIN_FPS" | bc -l)" -eq 1 ]; then
                    echo "##teamcity[buildProblem description='FPS below threshold']"
                    exit 1
                fi

                echo "##teamcity[buildStatisticValue key='framedash.avgFps' value='${'$'}AVG_FPS']"
            """.trimIndent()
        }
    }
})

メタランナー

再利用可能なメタランナーを作成します。プロジェクトの .teamcity/pluginData/metaRunners/ ディレクトリに Framedash_Performance_Gate.xml として保存します:

<?xml version="1.0" encoding="UTF-8"?>
<meta-runner name="Framedash Performance Gate">
  <description>Check game performance metrics via Framedash CLI</description>
  <settings>
    <parameters>
      <param name="framedash.minFps" value="30"
             spec="text description='Minimum acceptable FPS' label='Min FPS'" />
      <param name="framedash.queryDays" value="7"
             spec="text description='Number of days to query' label='Query Days'" />
    </parameters>
    <build-runners>
      <runner name="Framedash Performance Gate" type="simpleRunner">
        <parameters>
          <param name="script.content"><![CDATA[
#!/bin/bash
set -euo pipefail

framedash auth

MIN_FPS=%framedash.minFps%

RESULT=$(framedash query \
    "SELECT avg(fps) as avg_fps FROM events \
     WHERE event_name = 'performance_sample' \
       AND timestamp > now() - INTERVAL %framedash.queryDays% DAY" \
    --format json)

AVG_FPS=$(echo "$RESULT" | jq -r '.data[0].avg_fps // 0')

echo "Average FPS: $AVG_FPS (threshold: $MIN_FPS)"

if [ "$(echo "$AVG_FPS < $MIN_FPS" | bc -l)" -eq 1 ]; then
    echo "##teamcity[buildProblem description='FPS below threshold: $AVG_FPS < $MIN_FPS']"
    exit 1
fi

echo "##teamcity[buildStatisticValue key='framedash.avgFps' value='$AVG_FPS']"
echo "Performance gate passed"
]]></param>
          <param name="teamcity.step.mode" value="default" />
          <param name="use.custom.script" value="true" />
        </parameters>
      </runner>
    </build-runners>
  </settings>
</meta-runner>

---

共通パターン

SQL ベースの品質ゲート

framedash query と SQL ファイルで再現可能なチェックを実行します:

-- checks/fps-threshold.sql
SELECT
    avg(fps) as avg_fps,
    min(fps) as min_fps,
    quantile(0.05)(fps) as p5_fps
FROM events
WHERE event_name = 'performance_sample'
  AND timestamp > now() - INTERVAL 1 DAY

framedash query --file checks/fps-threshold.sql --format json

出力形式の使い分け

CI でのパースには --format json と jq を使用します:

# 単一値を抽出
framedash dashboard --days 1 --format json | jq '.data.kpis.totalEvents'

# プロジェクトステータスを確認
framedash status --format json | jq '.data.project.name'

ビルドログの可読性には --format table を使用します:

framedash dashboard --days 7 --format table
framedash retention --days 30 --format table

ナイトリーパフォーマンスレポート

パフォーマンスサマリーを生成するナイトリービルドをスケジュールします:

#!/bin/bash
set -euo pipefail

echo "=== Framedash Nightly Report ==="
echo ""
echo "--- Project Status ---"
framedash status --format table
echo ""
echo "--- 7-Day Dashboard ---"
framedash dashboard --days 7 --format table
echo ""
echo "--- Player Retention ---"
framedash retention --days 30 --format table
echo ""
echo "--- Alert Rules ---"
framedash alerts list --format table

---

トラブルシューティング

認証エラー

Error: Unauthorized (401)

• FRAMEDASH_API_KEY が設定済みで有効であることを確認してください
• framedash auth でキーをテストしてください
• マップアップロードには管理者キー（fd_admin_*）が必要です

レート制限

Error: Too Many Requests (429)

• CLI は X-RateLimit-Reset のリセット時刻を表示します
• パイプラインスクリプトにバックオフ付きリトライを追加してください
• より高い制限が必要な場合はプランのアップグレードを検討してください

ネットワーク / プロキシ

CI 環境がプロキシを使用している場合:

export HTTPS_PROXY=http://proxy.example.com:8080
framedash auth

CLI が見つからない

CLI が CI エージェントの PATH にインストールされていることを確認してください:

# インストールを確認
which framedash || npm install -g @framedash/cli

# グローバルインストールなしで npx を使用
npx @framedash/cli auth

次のステップ

• CLI リファレンス — コマンドの完全なドキュメント
• API リファレンス — REST API の詳細
• CI プロファイリング — 自動パフォーマンスプロファイリング設定