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 集成的直接链接
如果需要以下任一功能，请选择 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 和 Server。
安装 Mastra GitHub App安装 Mastra GitHub App的直接链接
该集成由 Mastra GitHub App 提供支持。
App 会读取仓库内容，并监听已配置 branch 上的 push 事件。它会将部署状态作为 check run 写回。
在 Mastra platform dashboard 中打开组织设置。页面包含 GitHub App 部分。
选择 Install GitHub App，然后选择要安装到的 GitHub 账户或组织。
如果你不是 GitHub 组织的所有者，GitHub 会创建待管理员批准的 installation request。Dashboard 会同时跟踪待处理请求和已完成的安装。
选择 App 可以访问的仓库。可以限定到特定仓库，也可以授予其访问该账户所有仓库的权限。
随时可以在 GitHub 的 App 设置中撤销或更改仓库访问权限。
如果 GitHub 日后更新 App 所需的权限，dashboard 会显示 outdated permissions 警告和批准链接。在管理员重新批准前，仓库操作会返回 403。
待处理的安装请求待处理的安装请求的直接链接
当非管理员请求在组织中安装 App 时，请求会保持待处理状态，直到组织管理员在 GitHub.com 上批准。Dashboard 会：
- 在活跃安装旁列出待处理请求。
- 允许同一用户同时请求访问多个 GitHub 账户。
- 打开页面时与 GitHub 核对待处理状态，并移除管理员已拒绝或请求者已撤回的请求。
若要取消待处理请求，请在 dashboard 中选择旁边的 Cancel。
从模板创建项目从模板创建项目的直接链接
模板是最快的入门方式。Platform 会基于 Mastra 模板创建新仓库，将其链接到新项目，预配模板声明的所有托管数据库，并运行首次部署。
在 dashboard 中选择 Create project，然后选择 Start from a template。
选择模板和新仓库所属的 GitHub 账户。为仓库命名，并选择是否设为私有。
配置模板的托管数据库要求。模板可以声明所需的数据库（例如 Turso 或 Neon），你需要为每项要求选择 Provider 和区域。
添加模板特定的环境变量（例如 AI Provider API Key）。Platform 会自动设置
MASTRA_GATEWAY_API_KEY和MASTRA_PLATFORM_ACCESS_TOKEN，确保使用 Gateway 的模板代码在首次部署时即可运行。选择 Create project。Platform 会创建仓库、写入
.mastra-project.json配置文件、预配托管数据库，并触发 Studio 和 Server 的初始部署。
初始部署会等待托管数据库完成预配后再开始，因此模板的首次构建可以读取数据库连接环境变量。
关联现有仓库关联现有仓库的直接链接
如果已有位于 GitHub 仓库中的 Mastra 项目，请使用此流程。
在控制台中选择 Create project 和 Connect an existing repository；也可以打开现有项目，从项目设置中选择 Link repository。
选择一项安装，再选择仓库。仓库搜索会覆盖 App 在该安装中有权访问的所有仓库。
选择 Studio 和 Server 的部署 branch。两个目标默认都使用仓库的默认 branch；它们可以共享一个 branch，也可以使用不同 branch。
可以为项目禁用 Studio 或 Server。如果二者都已配置，手动 Deploy from GitHub drawer 默认会同时选择两个目标。
选择 Link repository。Platform 会验证仓库中是否已有指向其他项目的
.mastra-project.json文件。如果有，dashboard 会发出警告，并提供 Overwrite 选项，在关联时替换该文件。
关联后，下次向已配置 branch 推送时会触发部署。
.mastra-project.json 冲突mastra-projectjson-conflicts的直接链接
Platform 会向每个已关联仓库写入 .mastra-project.json 文件，用于标识项目。关联已经包含该文件的仓库时，dashboard 会在提交前检查其内容：
- 缺失：Platform 在关联时创建文件。
- 匹配：文件已经指向当前要关联的项目，无需更改。
- 冲突：文件指向其他项目。可以取消操作，也可以显式覆盖该文件。
有关文件 schema，请参阅配置。
推送时部署推送时部署的直接链接
关联仓库后，每次向已配置 branch 推送都会触发部署：
- 向 Studio branch 推送会触发 Studio 部署。
- 向 Server branch 推送会触发 Server 部署。
- 如果两个目标共享一个 branch，一次推送会并行触发两项部署。
每次部署都会包含 commit SHA、branch，以及引入该 commit 的 pull request 编号（如果有）。构建在 platform 内运行，并以 commit 上的 check run 形式向 GitHub 报告状态。
每个部署目标一次只运行一个构建。如果构建进行时收到新的推送，platform 会取消同一目标较早排队的构建，并运行最新构建。Studio 和 Server 构建会独立跟踪，因此配置两个目标后可以并行运行。
手动 GitHub 部署手动 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 会提示管理员重新批准权限。