Mastra platform 的 GitHub 整合
GitHub 整合會將 Mastra platform 項目連接至 GitHub 儲存庫。當你將變更推送至儲存庫時，Studio 和 Server 便會自動部署。
此整合只適用於託管在 GitHub.com 的儲存庫，目前不支援自行託管的 GitHub Enterprise 執行個體。
連接儲存庫後，platform 會：
- 每次推送至已設定的分支時，建置並部署 Studio 和 Server。
- 為使用範本建立的項目佈建託管數據庫及 Gateway API 金鑰。
- 在每次部署中顯示提交、分支及拉取請求的相關內容。
- 以 check run 將建置狀態回報至 GitHub，並透過即時狀態徽章及內嵌日誌在項目儀表板上顯示狀態。
何時使用 GitHub 整合何時使用 GitHub 整合 的直接連結
如有以下任何需要，請選用 GitHub 整合：
- 從
main或任何其他分支推送即部署，包括分別用於 Studio 和 Server 的分支。 - 使用託管的入門流程，從 Mastra 範本建立項目骨架，包括全新儲存庫、託管數據庫及 Gateway API 金鑰。
- 在 platform 儀表板內查看拉取請求及提交的相關內容，以便進行問題分類。
CLI 流程（mastra studio deploy 和 mastra server deploy）仍可用於臨時部署及 GitHub 以外的 CI Provider。如要使用純 CLI 路徑，請參閱 Studio 和 Server。
安裝 Mastra GitHub App安裝 Mastra GitHub App 的直接連結
此整合由 Mastra GitHub App 提供支援。
App 會讀取儲存庫內容，並監聽已設定分支上的 push 事件。它會以 check run 寫回部署狀態。
在 Mastra platform 儀表板開啟你的機構設定。頁面內有 GitHub App 部分。
選擇 Install GitHub App，然後選擇要安裝 App 的 GitHub 帳戶或機構。
如果你並非該 GitHub 機構的擁有者，GitHub 會建立待管理員批准的 installation request。儀表板會同時追蹤待處理請求和已完成的安裝。
選擇 App 可以存取的儲存庫。你可以將範圍限定為特定儲存庫，亦可授予存取帳戶上所有儲存庫的權限。
你可隨時在 GitHub 的 App 設定中撤銷或更改儲存庫存取權限。
如果 GitHub 其後更新 App 所需的權限，儀表板會顯示 outdated permissions 警告及批准連結。在管理員重新批准前，儲存庫操作會傳回 403。
待處理的安裝請求待處理的安裝請求 的直接連結
當非管理員要求在某機構安裝 App 時，請求會維持待處理狀態，直至機構管理員在 GitHub.com 批准為止。儀表板會：
- 在有效安裝旁列出待處理請求。
- 讓同一位用戶同時要求存取多個 GitHub 帳戶。
- 當你開啟頁面時，根據 GitHub 的資料核對待處理狀態，並移除管理員已拒絕或請求者已撤回的請求。
如要取消待處理請求，請在儀表板中選擇旁邊的 Cancel。
從範本建立項目從範本建立項目 的直接連結
範本是最快的入門方式。Platform 會從 Mastra 範本建立新儲存庫、將其連接至全新項目、佈建範本所宣告的所有託管數據庫，並執行首次部署。
在儀表板中選擇 Create project，然後選擇 Start from a template。
選取範本及新儲存庫所屬的 GitHub 帳戶。為儲存庫命名，並選擇是否設為私人儲存庫。
設定範本的託管數據庫要求。範本可以宣告所需的數據庫（例如 Turso 或 Neon），而你可為每項要求選擇 Provider 和區域。
加入範本專用的環境變數（例如 AI Provider API 金鑰）。Platform 會自動預先設定
MASTRA_GATEWAY_API_KEY和MASTRA_PLATFORM_ACCESS_TOKEN，讓與 Gateway 通訊的範本程式碼可在首次部署時正常運作。選擇 Create project。Platform 會建立儲存庫、在其中寫入
.mastra-project.json設定檔、佈建託管數據庫，並觸發 Studio 和 Server 的初始部署。
初始部署會等待託管數據庫完成佈建後才開始，因此範本的首次建置可取得數據庫連線環境變數。
連接現有儲存庫連接現有儲存庫 的直接連結
如果 GitHub 儲存庫內已有 Mastra 項目，請使用此流程。
在儀表板中選擇 Create project，然後選擇 Connect an existing repository；你亦可開啟現有項目，並在項目設定中選擇 Link repository。
選取安裝，然後選擇儲存庫。儲存庫搜尋涵蓋 App 在該安裝中可以存取的所有儲存庫。
選擇 Studio 和 Server 的部署分支。兩個目標預設均使用儲存庫的預設分支，而它們可以共用同一分支，亦可使用不同分支。
你可以為項目停用 Studio 或 Server。當兩者均已設定時，手動 Deploy from GitHub 抽屜預設會選取兩個目標。
選擇 Link repository。Platform 會驗證儲存庫中是否已有指向其他項目的
.mastra-project.json檔案。如果有，儀表板會發出警告，並提供 Overwrite 選項，在連接時取代該檔案。
連接後，下次推送至已設定的分支便會觸發部署。
.mastra-project.json 衝突mastra-projectjson-conflicts 的直接連結
Platform 會在每個已連接的儲存庫中寫入 .mastra-project.json 檔案，以識別項目。當你連接已有此檔案的儲存庫時，儀表板會在提交前檢查其內容：
- 缺少：Platform 會在連接時建立檔案。
- 相符：檔案已指向你正在連接的項目，毋須更改。
- 衝突：檔案指向另一個項目。你可以取消，或明確選擇覆寫檔案。
檔案結構請參閱設定。
推送即部署推送即部署 的直接連結
連接儲存庫後，每次推送至已設定的分支都會觸發部署：
- 推送至 Studio 分支會觸發 Studio 部署。
- 推送至 Server 分支會觸發 Server 部署。
- 如果兩個目標共用同一分支，一次推送會並行觸發兩項部署。
每次部署都會帶有提交 SHA、分支，以及引入該提交的拉取請求編號（如有）。建置會在 platform 內執行，並以提交上的 check run 將狀態回報至 GitHub。
每個部署目標同一時間只會執行一個建置。如果建置期間收到新的推送，platform 會取消同一目標較早且仍在輪候的建置，並執行最新建置。Studio 和 Server 建置會獨立追蹤，因此設定兩個目標後，它們可以並行執行。
手動 GitHub 部署手動 GitHub 部署 的直接連結
你亦可在不推送的情況下，從儀表板觸發部署。開啟項目，選擇 Deploy from GitHub，選取目標（Studio、Server 或兩者）及分支，然後提交。Platform 會針對該分支的最新提交執行部署，並將觸發方式記錄為 GitHub Workflow 部署。
追蹤部署追蹤部署 的直接連結
從範本建立項目或將其連接至儲存庫後，Setup 頁面會為每個部署目標顯示一列。每列會：
- 顯示即時狀態徽章，定期查詢部署狀態直至完成。
- 透過部署 ID 連結至部署詳細資料頁面。
- 提供 Show logs 切換按鈕，在頁面內串流建置及運行時日誌。部署有效期間，Server 日誌每三秒查詢一次。
權限與撤銷權限與撤銷 的直接連結
如要停止從某儲存庫部署，請執行以下其中一項操作：
- 在 Project settings → Repository 中取消連接儲存庫。項目會保留其歷史記錄，而你可稍後重新連接另一個儲存庫。
- 在 GitHub.com 移除 Mastra GitHub App 的儲存庫存取權限。現有部署會繼續執行，但新的推送不會再觸發部署。
- 從 GitHub 帳戶解除安裝 GitHub App。這會移除對該帳戶所有儲存庫的存取權限。
如果 GitHub 撤銷或輪替 App 的安裝權杖，讀取儲存庫時會傳回 github_app_permissions_outdated 錯誤，而儀表板會提示管理員重新批准權限。