> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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-TW/docs/mastra-platform/studio) 和 [Server](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/server)。

## 安裝 Mastra GitHub App

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

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

1. 在 [Mastra platform 控制面板](https://projects.mastra.ai)中開啟組織設定。頁面包含 **GitHub App** 區段。

2. 選取**安裝 GitHub App**，然後選擇要安裝至哪個 GitHub 帳戶或組織。

   如果你並非 GitHub 組織的擁有者，GitHub 會建立待處理的**安裝要求**，必須由管理員核准。控制面板會同時追蹤待處理要求與已完成的安裝。

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

   你隨時可以從 GitHub 的 App 設定撤銷或變更儲存庫存取權。

> **備註:** 如果 GitHub 日後更新 App 所需的權限，控制面板會顯示**權限已過期**警告及核准連結。在管理員重新核准前，儲存庫操作會傳回 `403`。

### 待處理的安裝要求

非管理員要求在組織中安裝 App 時，要求會保持待處理狀態，直到組織管理員在 GitHub.com 上核准為止。控制面板會：

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

若要取消待處理要求，請在控制面板中選取旁邊的**取消**。

## 從範本建立專案

範本是最快的入門方式。platform 會從 Mastra 範本建立新儲存庫、將其連結至新專案、佈建範本宣告的受管理資料庫，並執行第一次部署。

1. 在控制面板中選取**建立專案**，然後選擇**從範本開始**。

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

3. 設定範本的受管理資料庫需求。範本可以宣告必要資料庫（例如 Turso 或 Neon），你可為每項需求選擇 Provider 與區域。

4. 加入範本專用的環境變數（例如 AI Provider API 金鑰）。platform 會自動植入 `MASTRA_GATEWAY_API_KEY` 和 `MASTRA_PLATFORM_ACCESS_TOKEN`，讓與 Gateway 通訊的範本程式碼在第一次部署時即可運作。

5. 選取**建立專案**。platform 會建立儲存庫、將 `.mastra-project.json` 設定檔寫入其中、佈建受管理資料庫，並觸發最初的 Studio 與 Server 部署。

初次部署會等待受管理資料庫完成佈建後才開始，因此範本的第一次建置可以取得資料庫連線環境變數。

## 連結現有儲存庫

如果 GitHub 儲存庫中已有 Mastra 專案，請使用此流程。

1. 在控制面板中選取**建立專案**並選擇**連接現有儲存庫**，或開啟現有專案，再從專案設定選取**連結儲存庫**。

2. 挑選一項安裝，再選擇儲存庫。儲存庫搜尋範圍涵蓋 App 在該項安裝中可存取的所有儲存庫。

3. 選擇 Studio 和 Server 部署分支。兩個目標都預設為儲存庫的預設分支，可以共用一個分支，也可以使用不同分支。

   你可以停用專案的 Studio 或 Server。兩者皆已設定時，手動**從 GitHub 部署**抽屜預設會選取這兩個目標。

4. 選取**連結儲存庫**。platform 會驗證儲存庫是否已有指向其他專案的 `.mastra-project.json` 檔案。如果有，控制面板會發出警告，並提供**覆寫**選項，以便在連結時取代該檔案。

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

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

platform 會將 `.mastra-project.json` 檔案寫入每個已連結的儲存庫，以識別專案。連結已有此檔案的儲存庫時，控制面板會在提交前檢查內容：

- **缺少**：platform 會在連結時建立檔案。
- **相符**：檔案已指向要連結的專案，因此不需變更。
- **衝突**：檔案指向其他專案。你可以取消或明確覆寫檔案。

如需檔案結構描述，請參閱[設定](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/configuration)。

## 推送即部署

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

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

每次部署都包含提交 SHA、分支，以及引入該提交的提取要求編號（若有）。建置會在 platform 內執行，並以提交上的 check run 向 GitHub 回報狀態。

每個部署目標一次只會執行一項建置。若建置進行期間收到新的推送，platform 會取消相同目標先前排入佇列的建置，並執行最新建置。Studio 與 Server 建置會分別追蹤，因此設定兩個目標時可平行執行。

### 手動 GitHub 部署

你也可以從控制面板觸發部署，不必推送。開啟專案，選取**從 GitHub 部署**，挑選目標（Studio、Server 或兩者）與分支後提交。platform 會針對該分支的最新提交執行部署，並將觸發方式記錄為 **GitHub Workflow** 部署。

## 追蹤部署

從範本建立專案或連結至儲存庫後，**設定**頁面會為每個部署目標顯示一列。每列會：

- 顯示即時狀態徽章，輪詢部署直到完成。
- 透過部署 ID 連結至部署詳細資料頁面。
- 提供**顯示記錄**切換開關，以內嵌方式串流建置與執行階段記錄。部署進行期間，Server 記錄每三秒輪詢一次。

## 權限與撤銷

若要停止從儲存庫部署，請執行下列其中一項操作：

- 在**專案設定 → 儲存庫**中**取消連結儲存庫**。專案會保留記錄，之後可以重新連結其他儲存庫。
- 在 GitHub.com 上**移除 Mastra GitHub App 的儲存庫存取權**。現有部署會繼續執行，但新的推送不會觸發部署。
- 從 GitHub 帳戶**解除安裝 GitHub App**。這會移除該帳戶中所有儲存庫的存取權。

如果 GitHub 撤銷或輪替 App 的安裝權杖，儲存庫讀取操作會傳回 `github_app_permissions_outdated` 錯誤，控制面板也會提示管理員重新核准權限。

## 相關內容

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