跳至內容

Gradle 建置洞察

Tuist 的 Gradle 外掛可以將建置分析資料傳送至 Tuist，讓你清楚了解工作執行與建置效能。

設定上傳行為#

預設情況下：

  • 本機建置的建置分析資料會在背景上傳。
  • CI 執行的建置分析資料會在前台上傳，以避免在短暫存在的代理程式上遺失遙測資料。

你可以使用 uploadInBackground 內的 tuist 擴充功能來控制此行為：

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

設定參考#

uploadInBackground 選項可在 settings.gradle.kts 中的 tuist 擴充區塊中使用：

選項類型預設值說明
uploadInBackgroundBoolean?null（本機背景上傳，CI 前台上傳）是否在本機建置時於背景上傳建置洞察。

此設定不會影響 buildCache 區塊中的遠端快取設定。

報告參與者聲明#

只有在將 TUIST_ACTOR_ID 明確設定為組織範圍標籤，或在設定中設定 buildInsights.actorId 時，建置與測試報告請求才會包含可選的 x-tuist-actor-id 標頭。預設不會傳送任何標籤，此外掛亦不會偵測作業系統使用者名稱。環境變數覆寫具有優先權。將任一覆寫設為空字串以省略報告的識別碼；這不會移除由個別憑證建立的身份。無效的覆寫會省略聲明，而非回退。如果自訂 Proxy 拒絕不熟悉的標頭，請使用 TUIST_ACTOR_ID="" 選擇退出。

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

參與者識別碼為 1–128 位元組的非空格可列印 ASCII 字元。任何能夠檢視專案報告的人都可以看到這些識別碼，包括專案公開時的公開檢視者，並且會隨報告匯出。請勿包含你不想公開的機密或個人資訊。在儀表板中，已驗證的個別憑證具有優先權；否則由用戶端傳送的識別碼會明確標示為未驗證。它們永遠不會授予權限或自動連結至 Tuist 使用者。舊版伺服器會忽略歸因標頭，而新版伺服器仍會接受沒有該標頭的舊版用戶端。沒有識別碼的新共用權杖報告會顯示未知，而非發布組織；歷史報告會保留其先前的歸因。建置與測試清單會將已驗證使用者篩選器與未驗證報告識別碼篩選器分開。

網路信任發布#

自行託管部署可以明確允許來自其信任網路的 Gradle 建置與測試報告，而無需開發人員憑證。營運者必須先在實例上設定 TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true 並重新啟動。這適用於每個支援的專案；儀表板中沒有相關設定。請參閱自行託管指南。

在儲存庫中一次性設定目的地：

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

建置與測試報告不需要經過身份驗證的快取端點探索。除非實例另行啟用網路信任快取存取，或開發人員提供權杖，否則請停用快取。未簽名的測試報告會省略分片與現有建置參考，且不會驅動隔離或不穩定性自動化。當確實缺少憑證時，會跳過隔離查詢；若有有效憑證，則保留現有的已驗證行為。如果存在憑證，仍會使用它們，而無效憑證會失敗，而非回退至免憑證發布。當缺少憑證時，外掛會自動探索自行託管伺服器是否允許免憑證報告。不需要用戶端旗標或 buildInsights 設定。在升級免憑證用戶端之前，請將每個伺服器副本升級至支援探索的版本。較舊的沒有探索功能的伺服器、停用的實例以及探索錯誤仍需身份驗證；已驗證發布保持相容。明確設為空的 TUIST_TOKEN 會導致失敗關閉，而非啟用免憑證發布。對於沒有機密的 fork 或 Dependabot 工作，請移除該變數，而非將其定義為空字串。

伺服器會分配免憑證報告 ID。重複提交可能會建立第二份報告；此模式不保證冪等重試或與已驗證測試報告的關聯。此類報告無法觸發 VCS 評論或自動失敗代理事件。網路存取是發布的信任邊界，並非報告參與者身份的證明。

自訂中繼資料#

將標籤與鍵值資料附加到 Gradle 建置，以比較來自不同團隊、硬體或工作流程的執行。標籤可用作儀表板篩選器，而值會出現在每個建置的詳細頁面，以及應用程式介面與 Model Context Protocol 工具中。

使用環境變數設定中繼資料：

bash
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 天。詳情請參閱資料保留政策。