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 區段。
選取安裝 GitHub App，然後選擇要安裝至哪個 GitHub 帳戶或組織。
如果你並非 GitHub 組織的擁有者，GitHub 會建立待處理的安裝要求，必須由管理員核准。控制面板會同時追蹤待處理要求與已完成的安裝。
選取 App 可以存取的儲存庫。你可以將範圍限定為特定儲存庫，或授予帳戶中所有儲存庫的存取權。
你隨時可以從 GitHub 的 App 設定撤銷或變更儲存庫存取權。
如果 GitHub 日後更新 App 所需的權限，控制面板會顯示權限已過期警告及核准連結。在管理員重新核准前，儲存庫操作會傳回 403。
待處理的安裝要求「待處理的安裝要求」的直接連結
非管理員要求在組織中安裝 App 時，要求會保持待處理狀態，直到組織管理員在 GitHub.com 上核准為止。控制面板會：
- 在有效安裝旁列出待處理要求。
- 讓同一位使用者同時要求存取多個 GitHub 帳戶。
- 開啟頁面時，依據 GitHub 核對待處理狀態，並移除管理員已拒絕或要求者已撤回的要求。
若要取消待處理要求，請在控制面板中選取旁邊的取消。
從範本建立專案「從範本建立專案」的直接連結
範本是最快的入門方式。platform 會從 Mastra 範本建立新儲存庫、將其連結至新專案、佈建範本宣告的受管理資料庫，並執行第一次部署。
在控制面板中選取建立專案，然後選擇從範本開始。
挑選範本，並選取新儲存庫所屬的 GitHub 帳戶。為儲存庫命名，並選擇是否設為私人儲存庫。
設定範本的受管理資料庫需求。範本可以宣告必要資料庫（例如 Turso 或 Neon），你可為每項需求選擇 Provider 與區域。
加入範本專用的環境變數（例如 AI Provider API 金鑰）。platform 會自動植入
MASTRA_GATEWAY_API_KEY和MASTRA_PLATFORM_ACCESS_TOKEN，讓與 Gateway 通訊的範本程式碼在第一次部署時即可運作。選取建立專案。platform 會建立儲存庫、將
.mastra-project.json設定檔寫入其中、佈建受管理資料庫，並觸發最初的 Studio 與 Server 部署。
初次部署會等待受管理資料庫完成佈建後才開始，因此範本的第一次建置可以取得資料庫連線環境變數。
連結現有儲存庫「連結現有儲存庫」的直接連結
如果 GitHub 儲存庫中已有 Mastra 專案，請使用此流程。
在控制面板中選取建立專案並選擇連接現有儲存庫，或開啟現有專案，再從專案設定選取連結儲存庫。
挑選一項安裝，再選擇儲存庫。儲存庫搜尋範圍涵蓋 App 在該項安裝中可存取的所有儲存庫。
選擇 Studio 和 Server 部署分支。兩個目標都預設為儲存庫的預設分支，可以共用一個分支，也可以使用不同分支。
你可以停用專案的 Studio 或 Server。兩者皆已設定時，手動從 GitHub 部署抽屜預設會選取這兩個目標。
選取連結儲存庫。platform 會驗證儲存庫是否已有指向其他專案的
.mastra-project.json檔案。如果有，控制面板會發出警告，並提供覆寫選項，以便在連結時取代該檔案。
連結後，下次推送至已設定的分支便會觸發部署。
.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 部署」的直接連結
你也可以從控制面板觸發部署，不必推送。開啟專案，選取從 GitHub 部署，挑選目標（Studio、Server 或兩者）與分支後提交。platform 會針對該分支的最新提交執行部署，並將觸發方式記錄為 GitHub Workflow 部署。
追蹤部署「追蹤部署」的直接連結
從範本建立專案或連結至儲存庫後，設定頁面會為每個部署目標顯示一列。每列會：
- 顯示即時狀態徽章，輪詢部署直到完成。
- 透過部署 ID 連結至部署詳細資料頁面。
- 提供顯示記錄切換開關，以內嵌方式串流建置與執行階段記錄。部署進行期間，Server 記錄每三秒輪詢一次。
權限與撤銷「權限與撤銷」的直接連結
若要停止從儲存庫部署，請執行下列其中一項操作：
- 在專案設定 → 儲存庫中取消連結儲存庫。專案會保留記錄，之後可以重新連結其他儲存庫。
- 在 GitHub.com 上移除 Mastra GitHub App 的儲存庫存取權。現有部署會繼續執行，但新的推送不會觸發部署。
- 從 GitHub 帳戶解除安裝 GitHub App。這會移除該帳戶中所有儲存庫的存取權。
如果 GitHub 撤銷或輪替 App 的安裝權杖，儲存庫讀取操作會傳回 github_app_permissions_outdated 錯誤，控制面板也會提示管理員重新核准權限。