> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Mastra platform 的 GitHub 整合

GitHub 整合會將 Mastra platform 項目連接至 GitHub 儲存庫。當你將變更推送至儲存庫時，Studio 和 Server 便會自動部署。

> **備註:** 此整合只適用於託管在 GitHub.com 的儲存庫，目前不支援自行託管的 GitHub Enterprise 執行個體。

連接儲存庫後，platform 會：

- 每次推送至已設定的分支時，建置並部署 Studio 和 Server。
- 為使用範本建立的項目佈建託管數據庫及 Gateway API 金鑰。
- 在每次部署中顯示提交、分支及拉取請求的相關內容。
- 以 check run 將建置狀態回報至 GitHub，並透過即時狀態徽章及內嵌日誌在項目儀表板上顯示狀態。

## 何時使用 GitHub 整合

如有以下任何需要，請選用 GitHub 整合：

- 從 `main` 或任何其他分支推送即部署，包括分別用於 Studio 和 Server 的分支。
- 使用託管的入門流程，從 Mastra 範本建立項目骨架，包括全新儲存庫、託管數據庫及 Gateway API 金鑰。
- 在 platform 儀表板內查看拉取請求及提交的相關內容，以便進行問題分類。

CLI 流程（`mastra studio deploy` 和 `mastra server deploy`）仍可用於臨時部署及 GitHub 以外的 CI Provider。如要使用純 CLI 路徑，請參閱 [Studio](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/studio) 和 [Server](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/server)。

## 安裝 Mastra GitHub App

此整合由 Mastra GitHub App 提供支援。

App 會讀取儲存庫內容，並監聽已設定分支上的 `push` 事件。它會以 check run 寫回部署狀態。

1. 在 [Mastra platform 儀表板](https://projects.mastra.ai)開啟你的機構設定。頁面內有 **GitHub App** 部分。

2. 選擇 **Install GitHub App**，然後選擇要安裝 App 的 GitHub 帳戶或機構。

   如果你並非該 GitHub 機構的擁有者，GitHub 會建立待管理員批准的 **installation request**。儀表板會同時追蹤待處理請求和已完成的安裝。

3. 選擇 App 可以存取的儲存庫。你可以將範圍限定為特定儲存庫，亦可授予存取帳戶上所有儲存庫的權限。

   你可隨時在 GitHub 的 App 設定中撤銷或更改儲存庫存取權限。

> **備註:** 如果 GitHub 其後更新 App 所需的權限，儀表板會顯示 **outdated permissions** 警告及批准連結。在管理員重新批准前，儲存庫操作會傳回 `403`。

### 待處理的安裝請求

當非管理員要求在某機構安裝 App 時，請求會維持待處理狀態，直至機構管理員在 GitHub.com 批准為止。儀表板會：

- 在有效安裝旁列出待處理請求。
- 讓同一位用戶同時要求存取多個 GitHub 帳戶。
- 當你開啟頁面時，根據 GitHub 的資料核對待處理狀態，並移除管理員已拒絕或請求者已撤回的請求。

如要取消待處理請求，請在儀表板中選擇旁邊的 **Cancel**。

## 從範本建立項目

範本是最快的入門方式。Platform 會從 Mastra 範本建立新儲存庫、將其連接至全新項目、佈建範本所宣告的所有託管數據庫，並執行首次部署。

1. 在儀表板中選擇 **Create project**，然後選擇 **Start from a template**。

2. 選取範本及新儲存庫所屬的 GitHub 帳戶。為儲存庫命名，並選擇是否設為私人儲存庫。

3. 設定範本的託管數據庫要求。範本可以宣告所需的數據庫（例如 Turso 或 Neon），而你可為每項要求選擇 Provider 和區域。

4. 加入範本專用的環境變數（例如 AI Provider API 金鑰）。Platform 會自動預先設定 `MASTRA_GATEWAY_API_KEY` 和 `MASTRA_PLATFORM_ACCESS_TOKEN`，讓與 Gateway 通訊的範本程式碼可在首次部署時正常運作。

5. 選擇 **Create project**。Platform 會建立儲存庫、在其中寫入 `.mastra-project.json` 設定檔、佈建託管數據庫，並觸發 Studio 和 Server 的初始部署。

初始部署會等待託管數據庫完成佈建後才開始，因此範本的首次建置可取得數據庫連線環境變數。

## 連接現有儲存庫

如果 GitHub 儲存庫內已有 Mastra 項目，請使用此流程。

1. 在儀表板中選擇 **Create project**，然後選擇 **Connect an existing repository**；你亦可開啟現有項目，並在項目設定中選擇 **Link repository**。

2. 選取安裝，然後選擇儲存庫。儲存庫搜尋涵蓋 App 在該安裝中可以存取的所有儲存庫。

3. 選擇 Studio 和 Server 的部署分支。兩個目標預設均使用儲存庫的預設分支，而它們可以共用同一分支，亦可使用不同分支。

   你可以為項目停用 Studio 或 Server。當兩者均已設定時，手動 **Deploy from GitHub** 抽屜預設會選取兩個目標。

4. 選擇 **Link repository**。Platform 會驗證儲存庫中是否已有指向其他項目的 `.mastra-project.json` 檔案。如果有，儀表板會發出警告，並提供 **Overwrite** 選項，在連接時取代該檔案。

連接後，下次推送至已設定的分支便會觸發部署。

### `.mastra-project.json` 衝突

Platform 會在每個已連接的儲存庫中寫入 `.mastra-project.json` 檔案，以識別項目。當你連接已有此檔案的儲存庫時，儀表板會在提交前檢查其內容：

- **缺少**：Platform 會在連接時建立檔案。
- **相符**：檔案已指向你正在連接的項目，毋須更改。
- **衝突**：檔案指向另一個項目。你可以取消，或明確選擇覆寫檔案。

檔案結構請參閱[設定](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/configuration)。

## 推送即部署

連接儲存庫後，每次推送至已設定的分支都會觸發部署：

- 推送至 **Studio 分支**會觸發 Studio 部署。
- 推送至 **Server 分支**會觸發 Server 部署。
- 如果兩個目標共用同一分支，一次推送會並行觸發兩項部署。

每次部署都會帶有提交 SHA、分支，以及引入該提交的拉取請求編號（如有）。建置會在 platform 內執行，並以提交上的 check run 將狀態回報至 GitHub。

每個部署目標同一時間只會執行一個建置。如果建置期間收到新的推送，platform 會取消同一目標較早且仍在輪候的建置，並執行最新建置。Studio 和 Server 建置會獨立追蹤，因此設定兩個目標後，它們可以並行執行。

### 手動 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` 錯誤，而儀表板會提示管理員重新批准權限。

## 相關內容

- [Mastra platform 概覽](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/overview)
- [Mastra platform 上的 Studio](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/studio)
- [Mastra platform 上的 Server](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/server)
- [設定](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/configuration)