Mastra platform 上的 GitHub 集成
GitHub 集成会将 Mastra platform 项目关联到 GitHub 仓库。当你向仓库推送更改时，Studio 和 Server 会自动部署。
该集成仅适用于托管在 GitHub.com 上的仓库。目前不支持自托管的 GitHub Enterprise 实例。
仓库关联后，平台会：
- 在每次推送到配置分支时构建并部署 Studio 和 Server。
- 为从模板创建的项目创建托管数据库和 Gateway API key。
- 在每次部署中展示 commit、分支和 pull request 上下文。
- 将构建状态作为 check runs 报告回 GitHub，并通过实时状态徽章和内联日志报告到项目 dashboard。
何时使用 GitHub 集成何时使用 GitHub 集成的直接链接
当你需要以下任一功能时，请选择 GitHub 集成：
- 从
main或任何其他分支推送即部署，包括为 Studio 和 Server 使用不同分支。 - 从 Mastra 模板脚手架创建项目的托管入门流程，包括新仓库、托管数据库和 gateway API key。
- 在平台 dashboard 中查看 pull request 和 commit 上下文以便分诊。
CLI 流程（mastra studio deploy 和 mastra server deploy）仍可用于临时部署和 GitHub 以外的 CI 提供器。仅使用 CLI 的路径请参阅 Studio 和 Server。
安装 Mastra GitHub App安装 Mastra GitHub App的直接链接
该集成由 Mastra GitHub App 提供支持。
该 App 读取仓库内容并监听配置分支上的 push 事件。它会将部署状态作为 check runs 写回。
在 Mastra platform dashboard 中打开组织设置。页面包含 GitHub App 部分。
选择 Install GitHub App，然后选择要安装到的 GitHub 账户或组织。
如果你不拥有该 GitHub 组织，GitHub 会创建一个待处理的 installation request，需要由 admin 批准。dashboard 会将待处理请求与已完成的安装一起跟踪。
选择 App 可以访问的仓库。你可以限定到特定仓库，或授予对该账户上所有仓库的访问权限。
你可以随时从 GitHub 的 App 设置中撤销或更改仓库访问权限。
如果 GitHub 之后更新了 App 所需的权限，dashboard 会显示 outdated permissions 警告和审批链接。在 admin 重新批准之前，仓库操作会返回 403。
待处理的安装请求待处理的安装请求的直接链接
当非 admin 用户请求在组织上安装 App 时，该请求会保持待处理，直到组织 admin 在 GitHub.com 上批准。dashboard 会：
- 在活跃安装旁边列出待处理请求。
- 允许同一用户一次请求访问多个 GitHub 账户。
- 打开页面时与 GitHub 核对待处理状态，移除 admin 已拒绝或请求者已撤回的请求。
要取消待处理请求，请在 dashboard 中选择其旁边的 Cancel。
从模板创建项目从模板创建项目的直接链接
模板是开始使用的最快方式。平台会从 Mastra 模板创建一个新仓库并将其关联到新项目。然后它会创建模板声明的任何托管数据库，并运行首次部署。
在 dashboard 中选择 Create project，然后选择 Start from a template。
选择一个模板，并选择拥有新仓库的 GitHub 账户。命名仓库并选择是否设为私有。
配置模板的托管数据库需求。模板可以声明所需数据库（例如 Turso 或 Neon），你可以为每项需求选择提供器和区域。
添加任何模板特定的环境变量（例如 AI 提供器 API 密钥）。平台会自动填充
MASTRA_GATEWAY_API_KEY和MASTRA_PLATFORM_ACCESS_TOKEN，使与 Gateway 通信的模板代码在首次部署时即可工作。选择 Create project。平台会创建带有
.mastra-project.json配置文件的仓库，创建其托管数据库，然后触发初始 Studio 和 Server 部署。
初始部署会在开始前等待托管数据库完成创建，因此模板的首次构建可以看到数据库连接环境变量。
关联现有仓库关联现有仓库的直接链接
当你已有位于 GitHub 仓库中的 Mastra 项目时，请使用此流程。
在 dashboard 中选择 Create project 并选择 Connect an existing repository，或打开现有项目并在项目设置中选择 Link repository。
选择一个安装，然后选择仓库。仓库搜索会覆盖该安装中 App 有权访问的每个仓库。
选择 Studio 和 Server 部署分支。两个目标默认都使用仓库的默认分支，它们可以共享一个分支或使用不同分支。
你可以为项目禁用 Studio 或 Server。当两者都已配置时，手动 Deploy from GitHub 抽屉默认会选中两个目标。
选择 Link repository。平台会验证仓库是否已有指向其他项目的
.mastra-project.json文件。如果有，dashboard 会发出警告，并提供在关联时替换该文件的 Overwrite 选项。
关联后，下一次推送到配置分支会触发部署。
.mastra-project.json 冲突mastra-project-json-conflicts的直接链接
平台会在每个关联的仓库中写入 .mastra-project.json 文件以标识项目。当你关联已有该文件的仓库时，dashboard 会在提交前检查其内容：
- 缺失：平台会在关联时创建文件。
- 匹配：文件已指向你正在关联的项目，因此无需更改。
- 冲突：文件指向其他项目。你可以取消或显式覆盖该文件。
该文件的 schema 请参阅配置。
推送即部署推送即部署的直接链接
仓库关联后，每次推送到配置分支都会触发部署：
- 推送到 Studio 分支会触发 Studio 部署。
- 推送到 Server 分支会触发 Server 部署。
- 如果两个目标共享一个分支，一次推送会并行触发两个部署。
每次部署都会携带 commit SHA、分支以及（如果可用）引入该 commit 的 pull request 编号。构建在平台内运行，并作为 check runs 将状态报告回 GitHub 上的 commit。
每个部署目标一次只运行一个构建。如果构建进行中又收到新推送，平台会取消该目标较旧的排队构建并运行最新构建。Studio 和 Server 构建独立跟踪，因此当两个目标都已配置时它们可以并行运行。
手动 GitHub 部署手动 GitHub 部署的直接链接
你也可以在不推送的情况下从 dashboard 触发部署。打开项目并选择 Deploy from GitHub。选择目标（Studio、Server 或两者）以及分支，然后提交。平台会针对该分支的 head commit 运行部署，并将触发器记录为 GitHub Workflow 部署。
跟踪部署跟踪部署的直接链接
项目从模板创建或关联到仓库后，Setup 页面会为每个部署目标显示一行。每一行：
- 显示实时状态徽章，轮询部署直到完成。
- 通过部署 ID 链接到部署详情页。
- 提供 Show logs 切换开关，可内联流式查看构建和运行时日志。部署活跃期间，Server 日志每三秒轮询一次。
权限和撤销权限和撤销的直接链接
要停止仓库触发的部署，请执行以下任一操作：
- 取消仓库关联：在 Project settings → Repository 中从项目取消关联。项目会保留其历史记录，之后你可以重新关联其他仓库。
- 移除仓库访问权限：在 GitHub.com 上移除 Mastra GitHub App 的仓库访问权限。现有部署会继续运行，但新的推送不会触发部署。
- 卸载 GitHub App：从 GitHub 账户卸载 App。这会移除对该账户上所有仓库的访问权限。
如果 GitHub 撤销或轮换了 App 的安装 token，仓库读取会返回 github_app_permissions_outdated 错误，dashboard 会提示 admin 重新批准权限。