GitHub 集成

Git 仓库是绝大多数软件项目的核心。我们与 GitHub 集成，以便在你的拉取请求中直接提供 Tuist 洞察，并节省部分配置工作，例如同步默认分支。

设置#

你需要在组织的 Integrations 标签页中安装 Tuist GitHub 应用：

你也可以直接从 GitHub 安装该应用。如有需要，请登录 Tuist，授权 GitHub 应用以便 Tuist 验证你对安装的访问权限，然后选择要连接的 Tuist 组织。你必须拥有安装该应用的 GitHub 组织（或个人 GitHub 账户）。仅显示你管理的 Tuist 组织和你的个人 Tuist 账户。如果只有一个可用账户，Tuist 会自动连接，不会显示选择器。当你从 Tuist 开始时，组织已预先选中，此步骤将被跳过。

之后，你可以在 GitHub 仓库与 Tuist 项目之间添加项目连接：

安装应用后，你也可以在不使用仪表板的情况下链接项目：

• CLI：tuist project repository connect owner/name，并使用 tuist project repository disconnect 移除链接。
• REST API： 对 /api/projects/{account_handle}/{project_handle}/vcs-connection 执行 PUT 和 DELETE。
• Model Context Protocol：connect_project_repository 和 disconnect_project_repository 工具。

该仓库必须是 GitHub 应用安装可访问的仓库，且项目采用仓库的默认分支。账户令牌需要 project:admin:write 作用域。

GitHub Enterprise Server#

Tuist 还与自托管的 GitHub Enterprise Server (GHES) 实例集成。在 GitHub 集成卡片中，切换到 Enterprise server 标签页，输入你的 GHES 基础 URL（例如 https://github.example.com），然后点击安装。

由于 GitHub 应用限定于单个 GitHub 实例，Tuist 无法在其 github.com 应用上复用于你的 GHES——相反，安装按钮会引导你完成 GitHub 的 App manifest flow：GHES 会指导管理员在该实例上注册一个新的 Tuist 应用，然后将新应用的凭据交还给 Tuist。Tuist 会以每安装为单位加密存储这些凭据，并从此将其用于每次 API 调用、webhook 签名以及指向你仓库的链接。

无需额外的 Tuist 服务器配置；manifest 流程会自动生成并提供所有内容。

应用权限和 webhook 事件#

Tuist 需要以下 仓库权限 以支持 PR 评论和包大小检查：

Tuist 使用 check_run webhook 事件来处理包大小检查操作。manifest 流程会自动配置此订阅。

对于在 github.com 上使用自托管 Tuist 服务器的手动应用设置，请参阅 自托管指南。

独立的浏览器和 API URL#

如果工程师通过内部主机名访问 GitHub Enterprise，而第三方服务使用外部代理，请在点击安装前配置这两个地址：

API URL 是完整的 REST API 基础 URL，包括 /api/v3 或你的代理公开的等效路径。Tuist 不会向显式的 API URL 追加 /api/v3。如果一个主机名同时适用于你的浏览器和 Tuist，请将其留空；现有连接将继续使用 <Server URL>/api/v3。

这两个地址都必须路由到 同一个 GitHub Enterprise 实例。你的浏览器只需能够访问 Server URL，无需访问 API 代理。Tuist 的服务器只需能够访问 API URL，无需访问内部浏览器主机名。

对于外部代理：

• 使用 HTTPS，并采用 Tuist 服务器信任的证书，且公共 DNS 解析为公共 IP 地址。API URL 覆盖不会绕过 Tuist 的私有 IP/SSRF 保护。覆盖必须指向你的 Enterprise 实例，而不是 github.com 或 *.github.com 端点。
• 将每个 Tuist 出站 IP 地址 加入允许列表。
• 转发 Tuist 使用的 REST API 端点，包括 POST /api/v3/app-manifests/{code}/conversions、POST /api/v3/app/installations/{installation_id}/access_tokens 以及用于评论和检查的仓库 API 端点。这些是 GitHub 的上游路径；如果你的代理公开了不同的前缀，请相应转换它们。
• 将请求转发到 GitHub，不要使用 HTTP 重定向或交互式登录页面。Tuist 不会自动跟随 Enterprise API 重定向，因此它们无法绕过公共 IP 检查。在设置期间，在 Tuist 获得应用凭据之前，manifest 转换端点必须是可访问的。GitHub Actions 日志下载是一个例外：Tuist 仅通过 HTTPS 跟随签名的归档重定向，检查并将每个目标固定到公共 IP，且不转发安装令牌。

GitHub 可能会使用其内部主机名返回分页链接。Tuist 会将来自配置的 GitHub 实例的链接重新基于 API URL，保留你代理的路径前缀；指向无关来源的链接将被拒绝。

另外，GitHub 必须能够将 webhook 交付到 https://tuist.dev/webhooks/github（或者在你自托管的 Tuist 服务器上为 /webhooks/github）。工程师必须能够返回 Tuist 以完成浏览器回调。API URL 不会改变这两个目的地。

组织管理员还可以使用集成卡片中的 Save API URL 来更改或清除现有 Enterprise 集成上的 API URL。无需重新安装应用或重新连接项目。清除它将恢复 <Server URL>/api/v3。保存操作会验证 URL 格式，而不是代理连通性。由于安装查找会被缓存，webhook 处理可能需要长达一分钟才能使用更改后的地址；已经在途的请求可能仍会使用之前的地址。

拉取/合并请求评论#

GitHub 应用会发布 Tuist 运行报告，其中包括 PR 摘要，以及指向最新 预览 或 测试 的链接：

Tuist 会在结果到达时更新一条评论。Gradle 构建会为每个根项目和请求的任务集单独显示；重新运行相同的任务会替换该次调用的先前结果。完整的构建历史记录仍然可在 Tuist 上查看。

评论默认启用，以保留现有集成的报告功能。要为项目关闭或重新开启评论，请打开 Project Settings → Integrations 并切换 GitHub → Run report comments。每个项目都有自己的设置；仓库连接仍在组织设置中管理。

禁用评论不会禁用构建或测试上传、GitHub Actions 作业摘要、仓库连接或其他 GitHub 集成功能。现有评论不会被删除。

GitHub Actions 作业摘要#

Tuist CLI 和 Gradle 插件将测试和构建结果写入 GitHub Actions 中的 作业摘要。该摘要链接到 Tuist 上的完整报告，其中提供更丰富的见解，例如不稳定测试和包大小差异。

对于 Gradle，每个成功上传的构建或测试报告都会附加其自己的摘要，保留由 gradle/actions/setup-gradle 等工具写入的其他内容。这需要包含作业摘要支持的插件版本；较旧的 Gradle 插件版本仅通过 GitHub 应用的 PR 评论进行报告。作业摘要不需要连接 GitHub 应用，禁用 Run report comments 也不会影响它们。

当 GitHub Actions 摘要目的地可用时，Gradle 会在退出前等待上传和摘要完成，即使启用了 uploadInBackground。GitHub 会在工作流步骤结束时捕获摘要。

这在配合 合并队列 使用时特别有用。合并队列运行不附加到拉取请求，因此不会发布评论，但作业摘要仍会显示结果。