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

# Mastra platform 上的 GitHub 集成

GitHub 集成会将 Mastra platform 项目与 GitHub 仓库关联。向仓库推送更改时，Studio 和 Server 会自动部署。

> **备注:** 该集成仅适用于托管在 GitHub.com 上的仓库，目前不支持自行托管的 GitHub Enterprise 实例。

关联仓库后，platform 会：

- 每次向已配置的 branch 推送时，构建并部署 Studio 和 Server。
- 为从模板创建的项目预配托管数据库和 Gateway API Key。
- 在每次部署中显示 commit、branch 和 pull request 上下文。
- 以 check run 的形式向 GitHub 报告构建状态，并在项目 dashboard 中通过实时状态徽章和内联日志报告状态。

## 何时使用 GitHub 集成

如果需要以下任一功能，请选择 GitHub 集成：

- 从 `main` 或任何其他 branch 推送时部署，包括为 Studio 和 Server 使用不同 branch。
- 通过托管的 onboarding 流程从 Mastra 模板搭建项目，包括全新的仓库、托管数据库和 Gateway API Key。
- 在 platform dashboard 中查看 pull request 和 commit 上下文以进行问题分类。

CLI 流程（`mastra studio deploy` 和 `mastra server deploy`）仍可用于临时部署以及 GitHub 之外的 CI Provider。有关仅使用 CLI 的路径，请参阅 [Studio](https://mastra.zisheng.pro/docs/mastra-platform/studio) 和 [Server](https://mastra.zisheng.pro/docs/mastra-platform/server)。

## 安装 Mastra GitHub App

该集成由 Mastra GitHub App 提供支持。

App 会读取仓库内容，并监听已配置 branch 上的 `push` 事件。它会将部署状态作为 check run 写回。

1. 在 [Mastra platform dashboard](https://projects.mastra.ai) 中打开组织设置。页面包含 **GitHub App** 部分。

2. 选择 **Install GitHub App**，然后选择要安装到的 GitHub 账户或组织。

   如果你不是 GitHub 组织的所有者，GitHub 会创建待管理员批准的 **installation request**。Dashboard 会同时跟踪待处理请求和已完成的安装。

3. 选择 App 可以访问的仓库。可以限定到特定仓库，也可以授予其访问该账户所有仓库的权限。

   随时可以在 GitHub 的 App 设置中撤销或更改仓库访问权限。

> **备注:** 如果 GitHub 日后更新 App 所需的权限，dashboard 会显示 **outdated permissions** 警告和批准链接。在管理员重新批准前，仓库操作会返回 `403`。

### 待处理的安装请求

当非管理员请求在组织中安装 App 时，请求会保持待处理状态，直到组织管理员在 GitHub.com 上批准。Dashboard 会：

- 在活跃安装旁列出待处理请求。
- 允许同一用户同时请求访问多个 GitHub 账户。
- 打开页面时与 GitHub 核对待处理状态，并移除管理员已拒绝或请求者已撤回的请求。

若要取消待处理请求，请在 dashboard 中选择旁边的 **Cancel**。

## 从模板创建项目

模板是最快的入门方式。Platform 会基于 Mastra 模板创建新仓库，将其链接到新项目，预配模板声明的所有托管数据库，并运行首次部署。

1. 在 dashboard 中选择 **Create project**，然后选择 **Start from a template**。

2. 选择模板和新仓库所属的 GitHub 账户。为仓库命名，并选择是否设为私有。

3. 配置模板的托管数据库要求。模板可以声明所需的数据库（例如 Turso 或 Neon），你需要为每项要求选择 Provider 和区域。

4. 添加模板特定的环境变量（例如 AI Provider API Key）。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 的部署 branch。两个目标默认都使用仓库的默认 branch；它们可以共享一个 branch，也可以使用不同 branch。

   可以为项目禁用 Studio 或 Server。如果二者都已配置，手动 **Deploy from GitHub** drawer 默认会同时选择两个目标。

4. 选择 **Link repository**。Platform 会验证仓库中是否已有指向其他项目的 `.mastra-project.json` 文件。如果有，dashboard 会发出警告，并提供 **Overwrite** 选项，在关联时替换该文件。

关联后，下次向已配置 branch 推送时会触发部署。

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

Platform 会向每个已关联仓库写入 `.mastra-project.json` 文件，用于标识项目。关联已经包含该文件的仓库时，dashboard 会在提交前检查其内容：

- **缺失**：Platform 在关联时创建文件。
- **匹配**：文件已经指向当前要关联的项目，无需更改。
- **冲突**：文件指向其他项目。可以取消操作，也可以显式覆盖该文件。

有关文件 schema，请参阅[配置](https://mastra.zisheng.pro/docs/mastra-platform/configuration)。

## 推送时部署

关联仓库后，每次向已配置 branch 推送都会触发部署：

- 向 **Studio branch** 推送会触发 Studio 部署。
- 向 **Server branch** 推送会触发 Server 部署。
- 如果两个目标共享一个 branch，一次推送会并行触发两项部署。

每次部署都会包含 commit SHA、branch，以及引入该 commit 的 pull request 编号（如果有）。构建在 platform 内运行，并以 commit 上的 check run 形式向 GitHub 报告状态。

每个部署目标一次只运行一个构建。如果构建进行时收到新的推送，platform 会取消同一目标较早排队的构建，并运行最新构建。Studio 和 Server 构建会独立跟踪，因此配置两个目标后可以并行运行。

### 手动 GitHub 部署

也可以从 dashboard 触发部署，无需推送。打开项目，选择 **Deploy from GitHub**，选择目标（Studio、Server 或两者）和 branch，然后提交。Platform 会基于该 branch 的 head commit 运行部署，并将 trigger 记录为 **GitHub Workflow** 部署。

## 跟踪部署

从模板创建项目或关联仓库后，**Setup** 页面会为每个部署目标显示一行。每行会：

- 显示实时状态徽章，轮询部署直至完成。
- 通过部署 ID 链接到部署详情页面。
- 提供 **Show logs** 切换开关，内联流式显示构建和运行时日志。部署活跃期间，Server 日志每三秒轮询一次。

## 权限和撤销

若要停止来自某个仓库的部署，请执行以下任一操作：

- 在 **Project settings → Repository** 中解除仓库与项目的关联。项目会保留其历史记录，之后可以重新关联另一个仓库。
- 在 GitHub.com 上移除 Mastra GitHub App 的仓库访问权限。现有部署会继续运行，但新的推送不会再触发部署。
- 从 GitHub 账户卸载 GitHub App。这会移除对该账户所有仓库的访问权限。

如果 GitHub 撤销或轮换 App 的 installation token，读取仓库会返回 `github_app_permissions_outdated` 错误，dashboard 会提示管理员重新批准权限。

## 相关内容

- [Mastra platform 概述](https://mastra.zisheng.pro/docs/mastra-platform/overview)
- [Mastra platform 上的 Studio](https://mastra.zisheng.pro/docs/mastra-platform/studio)
- [Mastra platform 上的 Server](https://mastra.zisheng.pro/docs/mastra-platform/server)
- [配置](https://mastra.zisheng.pro/docs/mastra-platform/configuration)