# Gradleビルドインサイト {#gradle-build-insights}

TuistのGradleプラグインはビルド分析をTuistに送信でき、タスクの実行状況とビルドパフォーマンスを可視化します。

## アップロード動作の設定 {#configure-upload-behavior}

デフォルトでは:
- ローカルビルドの場合、ビルド分析はバックグラウンドでアップロードされます。
- CI実行の場合、短命なエージェントでのテレメトリ損失を防ぐため、ビルド分析はフォアグラウンドでアップロードされます。

`tuist`拡張機能内の`uploadInBackground`を使用して、この動作を制御できます:

```kotlin
tuist {
    uploadInBackground = false // always upload in the foreground
}
```

## 設定リファレンス {#configuration-reference}

`uploadInBackground`オプションは、`settings.gradle.kts`内の`tuist`拡張ブロックで利用できます:

| オプション | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| `uploadInBackground` | `Boolean?` | `null` (ローカルではバックグラウンド、CIではフォアグラウンド) | ローカルビルドのビルドインサイトをバックグラウンドでアップロードするかどうか。 |

この設定は、`buildCache`ブロック内のリモートキャッシュ設定には影響しません。

## レポートアクター claim {#report-actor-claim}

ビルドおよびテストレポートのリクエストには、`TUIST_ACTOR_ID`を組織スコープのラベルに明示的に設定するか、設定で`buildInsights.actorId`を構成した場合のみ、オプションの`x-tuist-actor-id`ヘッダーが含まれます。デフォルトではラベルは送信されず、プラグインはオペレーティングシステムのユーザー名を検出しません。環境変数による上書きが優先されます。報告される識別子を省略するには、いずれかの上書きを空文字列に設定してください。これにより、個別の認証情報によって確立された識別子が削除されるわけではありません。無効な上書きは、フォールバックせず、claimを省略します。カスタムプロキシが不明なヘッダーを拒否する場合は、`TUIST_ACTOR_ID=""`でオプトアウトしてください。

```kotlin
tuist {
    buildInsights {
        actorId = providers.environmentVariable("CORPORATE_ACTOR_ID").getOrElse("")
    }
}
```

アクター識別子は、スペース以外の印刷可能ASCII文字で構成される1〜128バイトです。プロジェクトのレポートを表示できるすべての人（プロジェクトが公開されている場合は公開ビューアーを含む）に表示され、レポートとともにエクスポートされます。公開したくないシークレットや個人情報は含めないでください。ダッシュボードでは、検証済みの個別認証情報が優先されます。それ以外の場合、クライアントから送信される識別子は明示的に**未検証**として扱われます。これらは権限を付与したり、Tuistユーザーに自動的にリンクしたりすることはありません。古いサーバーは属性ヘッダーを無視し、新しいサーバーはそれなしでも古いクライアントを受け入れ続けます。識別子のない新しい共有トークンレポートは、公開組織ではなく**不明**として表示されます。履歴レポートは以前の属性を保持します。ビルドおよびテストのリストでは、検証済みユーザーフィルターと未検証の報告識別子フィルターが区別されます。

## ネットワーク信頼済みパブリッシング {#network-trusted-publishing}

セルフホスト型のデプロイメントでは、開発者の認証情報なしで、信頼されたネットワークからのGradleビルドおよびテストレポートを明示的に許可できます。オペレーターはまずインスタンスで`TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true`を構成し、再起動する必要があります。これはサポートされているすべてのプロジェクトに適用され、ダッシュボードの設定はありません。<.localized_link href="/guides/server/self-host/server#network-trusted-access">セルフホスティングガイド</.localized_link>をご覧ください。

リポジトリで宛先を一度設定します:

```kotlin
tuist {
    project = "organization/project"
    url = "https://tuist.internal.example"
    buildCache { enabled = false }
}
```

ビルドおよびテストのレポートには、認証済みキャッシュエンドポイントの検出は必要ありません。インスタンスが別途ネットワーク信頼済みキャッシュアクセスを有効にしている場合、または開発者がトークンをプロビジョニングしている場合を除き、キャッシュを無効にしてください。署名されていないテストレポートは、シャードおよび既存ビルドの参照を省略し、隔離や不安定性の自動化をトリガーしません。認証情報が実際に存在しない場合、隔離ルックアップはスキップされます。有効な認証情報がある場合、既存の認証済み動作が維持されます。認証情報が存在する場合、それらが使用され、無効な認証情報は認証情報なしのパブリッシングへのフォールバックではなく失敗します。認証情報がない場合、プラグインはセルフホスト型サーバーが認証情報なしのレポートを許可するかどうかを自動的に検出します。クライアントフラグや`buildInsights`設定は必要ありません。認証情報なしのクライアントをアップグレードする前に、すべてのサーバーレプリカを検出対応バージョンにアップグレードしてください。検出機能のない古いサーバー、無効化されたインスタンス、および検出エラーは引き続き認証を必要とし、認証済みパブリッシングは互換性を保ちます。明示的に空の`TUIST_TOKEN`は、認証情報なしのパブリケーションを有効にするのではなく、安全側に倒れて失敗します。シークレットのないフォークまたはDependabotジョブの場合は、その変数を空文字列として定義するのではなく、削除してください。

サーバーは認証情報なしのレポートIDを割り当てます。送信を繰り返すと2番目のレポートが作成される可能性があります。このモードは、冪等な再試行や認証済みテストレポートとの相関を保証しません。このようなレポートは、VCSコメントや自動障害エージェントイベントをトリガーできません。ネットワークアクセスはパブリッシングの信頼境界であり、報告されたアクターの身元の証明ではありません。

## カスタムメタデータ {#custom-metadata}

異なるチーム、ハードウェア、またはワークフローからの実行を比較するために、Gradleビルドにタグとキーバリューデータを添付します。タグはダッシュボードフィルターとして利用でき、値は各ビルドの詳細ページ、アプリケーションプログラミングインターフェース、およびModel Context Protocolツールに表示されます。

環境変数でメタデータを設定します:

```sh
export TUIST_BUILD_TAGS="nightly,android"
export TUIST_BUILD_VALUE_TICKET="TUIST-123"
export TUIST_BUILD_VALUE_RUNNER="macos-14"
```

`settings.gradle.kts`でメタデータを構成することもできます:

```kotlin
tuist {
    buildInsights {
        tag("nightly")
        tag("android")
        value("ticket", "TUIST-123")
        value("runner", "macos-14")
    }
}
```

同じ値が両方の場所で構成されている場合、`settings.gradle.kts`内の値が優先されます。

タグには文字、数字、ハイフン、アンダースコアのみを含めることができます。ビルドには最大50個のタグを付けることができ、各タグは最大50文字まで含めることができます。ビルドには最大20個のキーバリューエントリを付けることができ、各キーは最大50文字、各値は最大500文字まで含めることができます。これらはXcodeビルドメタデータに使用される同じサーバー側の制限です。プラグインはレポートを送信する前に、無効なタグとサイズ超過または空のメタデータエントリをスキップするため、無効な構成によってビルドインサイトレポートの残りが保存されなくなることはありません。タグの制約を満たさない値には、キーバリューメタデータを使用してください。

カスタムメタデータは、ダッシュボード、アプリケーションプログラミングインターフェース、およびModel Context Protocolツールを通じてプロジェクトメンバーに表示されます。認証情報、アクセストークン、その他の機密データには使用しないでください。Tuistはこのメタデータを含むGradleビルドデータを90日間保持します。詳細については、<.localized_link href="/guides/server/data-retention">データ保持ポリシー</.localized_link>をご覧ください。