企业官网建设流程全解析

Windmill Git Sync 的 GitHub App 权限升级指南：Webhook 推送部署、自动 PR 与 Checks 校验

【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill

Windmill 正在把原本需要你以 GitHub Action 形式运行的 git sync（代码仓库 ↔ Windmill 工作区双向同步）工作迁移到应用自身内部，让双向同步开箱即用。本文以仓库内官方文档 docs/git-sync-github-app-permissions.md 为主体，结合 docs/git-sync-pull-design.md 设计文档与后端、前端源码，逐项讲解 Windmill GitHub App 新增的三项权限各自的用途、安全性边界、批准前后的行为差异，以及 GitHub Enterprise Server（GHES）自管理应用的配置方法，帮助你在了解原理的前提下安全地完成权限升级。

一、背景：为什么 Windmill 的 GitHub App 需要新权限

Windmill 的 Git Sync 功能负责让 Git 仓库与 Windmill 工作区保持同步：脚本、流程、应用等对象既可以从工作区推送到仓库（Windmill → 仓库），也可以从仓库拉取部署到工作区（仓库 → Windmill）。

过去，仓库 → Windmill 这个方向并不开箱即用：客户需要自己安装一个 GitHub Action，在仓库中存放带有 Windmill 长期令牌（token）的 secret，由 Action 调用wmill sync push把仓库内容推回 Windmill 实例。这带来几个问题：需要手工编写并维护 workflow 文件、需要为每个仓库配置令牌、还要求 GitHub 托管的 runner 能连通客户自建实例的 URL。

Windmill 正在把这项工作迁入应用本身，因此 GitHub App 需要申请少量新的权限。这些权限全部限定在你安装该 App 的仓库范围内，并且不会在 App 已有权限之外新增任何对你代码的访问能力——它们只是让 Windmill 能以你的身份在那些仓库上执行几类特定的 API 操作。

配套的设计文档 docs/git-sync-pull-design.md 明确指出，不同部署形态下「GitHub runner → 实例」「GitHub webhook → 实例」「实例 → GitHub」三条通路的可达性各不相同，而「实例 → GitHub 出站」对所有人都成立；把 pull 与 PR 逻辑放到实例侧，正是为了在所有连通性形态下都能工作，并在此基础上按可达性优雅降级：可达则用 webhook 即时触发，不可达则退化为轮询。

二、新增的三项权限与它们各自启用的能力

以下三项权限均为Read and write（读写）级别，对应 Windmill GitHub App 的权限升级请求：

设计文档 docs/git-sync-pull-design.md 对这三项权限做了更细的拆解（均为 write 级别）：

• Repository webhooks: write：用安装令牌动态创建/删除仓库级 webhook（POST /repos/{owner}/{repo}/hooks），这是 Webhook 即时同步的基础。
• Pull requests: write：由实例侧代替你创建 promotion 与 fork 场景的 PR——这两类 PR 针对的分支（wm_deploy/**与wm-fork/**）本来就是 Windmill 自己推送的，把「开 PR」移入部署流水线后，全程只需出站连接，不再依赖入站 webhook。
• Checks: write：通过 Checks API 发布 PR 差异预览检查（"Windmill diff"），以及部署状态检查。

每项能力的实际作用

1. Repository webhooks —— push 即部署

连接仓库后，Windmill 会为每个已连接仓库创建一个专属 webhook。它会在 webhook 上自行设置事件：push，以及供 Checks 使用的pull_request。当仓库有 push 事件时，实例校验通过后即触发对应工作区的拉取部署，实现「push 即部署」，替代原来的 push-to-Windmill GitHub Action。

2. Pull requests —— 自动打开 promotion / fork PR

在 promotion 模式或 workspace fork 场景下，Windmill 的部署会推送wm_deploy/**（promotion）或wm-fork/**（fork）分支；拿到 Pull requests 写权限后，Windmill 会在部署完成时自动替你打开（或重新打开）针对目标分支的 PR，替代gh pr create的 GitHub Action。

3. Checks —— PR 上的 "Windmill diff" 检查

订阅pull_request事件后，Windmill 可以在 PR 打开或同步时运行一次dry_run: true的拉取预览，并通过 Checks API 在 PR 上发布一个 "Windmill diff" 检查运行，直观展示这次改动应用到工作区后会变更哪些对象——相当于把原来依赖客户 CI 的 dry-run 预览搬到 Windmill 实例侧完成。

三、权限边界与安全性：作用域收窄、能力最小化

升级权限前需要明确三点安全边界：

限定在已安装仓库内。所有新权限都只作用于你安装该 App 的仓库，不涉及组织级或其他仓库的任何数据。

不新增代码访问。Windmill → 仓库方向一直使用 App 的Contents: write权限（负责提交变更）。新增的三项权限与Contents权限互不相干，因此不会扩大 App 对代码内容的读写范围——webhook 只能创建/删除 hook，Pull requests 只能操作 PR，Checks 只能读写检查运行。

事件由 Windmill 按仓库设置，应用级订阅列表无需改动。Windmill 为每个已连接仓库创建独立 webhook，并自行设置其事件（push，加上用于 Checks 的pull_request）。你不需要去修改 GitHub App 级别的 "Subscribe to events"（订阅事件）列表——这些事件之所以可用，仅仅是因为上述权限被授予了。

从实现上看，backend/windmill-native-triggers/src/github/external.rs 中已有通过 GitHub REST API 创建仓库级 webhook 的先例（POST /repos/{owner}/{repo}/hooks，payload 携带name: "web"、active: true、事件列表与回调 URL），git sync 的 webhook 创建/删除复用同一套 REST 模式。而事件到达后的验签则复用 backend/windmill-trigger-http/src/http_trigger_auth.rs 中已有的 GitHub HMAC 校验逻辑：读取X-Hub-Signature-256请求头，去掉sha256=前缀后按 SHA-256 + Hex 编码比对 payload 签名。

四、批准权限：安全、可逆、逐项 opt-in

批准是安全且可逆的

权限升级请求可以在 GitHub 侧批准，也可以随时在 App 安装设置中撤销；每个功能都是**从工作区的 git sync 设置中逐项选择开启（opt-in）**的，即使批准了权限，不开启对应开关也不会产生任何行为变化。

待批准期间：一切照旧

权限更新待定时，现有同步和任何 GitHub Actions 工作流都保持原样继续工作：

• Windmill → 仓库方向的提交依赖的Contents: write不受新权限影响；
• 你已安装的 push-to-Windmill /gh pr create/ dry-run 等 GitHub Action 依然可以运行；
• 尚未批准的新能力不会生效，但不会破坏任何已有流程。

自动 pull 开启但 webhook 权限尚未授予时

如果某个仓库在 webhook 权限被授予之前就开启了自动 pull（automatically deploy changes from Git），Windmill 会每隔约一分钟轮询一次被跟踪的分支（设计文档中默认轮询间隔为 60 秒），直到它能成功注册 webhook 为止。也就是说，即时性会暂时退化为近实时，但自动部署功能本身不会停摆。

同理，设计文档描述了一个自动化的可达性自测：实例创建 webhook 后，GitHub 会立即投递一次ping事件，若约 10 秒内未收到，实例会删除该 hook 并回退到轮询模式，同时在界面上提示「实例无法从 GitHub 访问——正在使用轮询（间隔 X 分钟）」，无需人工猜测防火墙配置。当 webhook 已激活时，轮询间隔会放宽（如 10 分钟）作为兜底，而不是完全关闭——这正是「webhook 保延迟、轮询保正确」的 ArgoCD 式模型。

五、源码视角：新权限背后的实现机制

Webhook 创建与删除

git sync 为每个仓库创建 webhook 时，会为该仓库生成一个独立 secret（存储在该仓库的 git-sync 设置中，加密保存），webhook 的回调 URL 形如{base_url}/api/w/{workspace}/github_app/webhook——该端点按工作区隔离，托管 App 与自管理/GHES App 共用同一接收器。仓库断开连接或关闭自动 pull 时，webhook 会被删除；设置变更时重建；还可以通过GET /repos/.../hooks按 URL 前缀过滤检测孤儿 hook。

事件验签与路由

webhook 送达后，实例用存储的 secret 对X-Hub-Signature-256做 HMAC 校验（复用 http_trigger_auth.rs 中mod github的Githubwebhook handler 实现），校验通过后进入 reconcile（协调）环节。设计文档强调了一个关键安全原则：webhook 与轮询都只是「提示」，真正的 pull 才是权威。触发器从不携带内容，只促使实例用自己的凭据把远端 HEAD 与last_synced_sha对比，若分支确实移动了才入队既有的 pull 任务——因此伪造或重放的触发器最多只会产生一次廉价的空操作，无法注入任何内容。

循环预防

Windmill 自己提交的 commit 带有[WM]前缀（供 CI 忽略），且 Windmill 作者（bot）触发的 push 事件会被跳过；入队前还会对比head_sha与last_synced_sha，pull 任务成功后会记录已同步的 sha。三重机制确保「pull → 部署 → deployment callback → 提交 → push 事件 → 再 pull」不会形成自激循环。

前端设置入口

在 frontend/src/lib/components/git_sync/GitSyncRepositoryCard.svelte 中可以看到每个仓库的auto_pull设置对象：mode取值'auto' | 'polling'（auto表示优先尝试 webhook、失败回退轮询），sync_forks默认开启；且代码注释明确「只有 GitHub App 支持的仓库能注册 webhook，PAT 仓库只能轮询」。仓库卡片上还会展示只读的last_pull_status（最近一次同步的状态、时间、任务 id 与错误信息）。

需要说明的是，git sync 属于 Windmill 的企业版（EE）能力：在 backend/windmill-api/src/git_sync_oss.rs 与 backend/windmill-git-sync/src/git_sync_oss.rs 的开源实现中，相关函数均为空操作占位（注释注明 "Git sync is an enterprise feature and not part of the open-source version"），完整逻辑在私有（EE）特性分支中实现。

六、自管理应用（GitHub Enterprise Server）

如果你使用 GitHub Enterprise Server（GHES），上述功能通过自管理应用以完全相同的方式工作：每次 API 调用都走应用自身的端点https://<ghes-host>/api/v3，而不是 github.com。

与托管 App 的关键差异是：没有「更新待批准」这回事，因为你拥有这个应用。你需要：

1. 在应用设置中自行授予上述三项权限（Webhooks、Pull requests、Checks，均为 Read and write）；
2. 在安装（installation）上接受权限更新。

入口路径为：Settings → Developer settings → GitHub Apps → Permissions & events。

其余行为与托管 App 一致：

• Webhook 仍按仓库逐个创建，所以应用级的 "Subscribe to events" 列表同样无需修改；
• 你的 Windmill base URL 只需要从 GHES 主机可达，而不需要暴露到公网。这在「GHES 与 Windmill 实例处于同一内网」的私有网络场景下特别实用——设计文档甚至指出这可以做到完全隔离（air-gapped）运行：最难处理的 github.com 场景，反而是 GHES 场景下最容易的。

实例侧的 GHES 自管理应用配置界面位于 frontend/src/lib/components/instanceSettings/GhesAppSettings.svelte，其中包含github_enterprise_app.self_managed开关、安装发现（discovery）与工作区分配等管理逻辑。

七、与现有 CI 共存：各能力的回退与迁移

权限升级是一次捆绑的单次更新（每次更新都会向既有安装的组织管理员重新弹出授权提示）。批准前或未使用 App 的场景下，各项新能力都有明确的回退路径：

对于正在运行wmill sync push之类 GitHub Action 的老用户：现有 CI 可以原样保留。触发器基于 sha 幂等，重复触发无害，两者天然共存。设计文档还建议，若需要，可后续通过 Contents API 检测到 workflow 文件后提供一键清理——但这不是迁移的前提。

面向三类用户的迁移路径

• 已安装托管 App 的用户（绝大多数）：迁移成本仅为「追加一次增量权限授权」，不需要重新连接仓库。旧权限在等待批准期间继续生效，因此迁移是惰性的、永不被阻塞的；若开启自动 pull 时遭遇 403（权限待批），界面会给出直达组织安装页的深链接引导批准，并立即开始轮询，用户不会卡在等待组织管理员上。
• 未安装 App、使用令牌/SSH 凭据的用户：无需批准任何权限，直接开启开关即走轮询；可选择性升级为「安装 Windmill GitHub App 以获得即时同步」。
• GHES 自管理应用用户：无集中审批环节，迁移就是一步——把实例 webhook URL 与生成的 secret 填入应用设置即可，且通常可内网运行。

参考资源（均为当前仓库内文件，可按需深入阅读）：

• 权限说明原文：docs/git-sync-github-app-permissions.md
• 自动 pull（拉取式同步）完整设计：docs/git-sync-pull-design.md
• GitLab 同步配置参考：docs/git-sync-gitlab-setup.md
• GitHub webhook 创建/删除 REST 实现：backend/windmill-native-triggers/src/github/external.rs
• GitHubX-Hub-Signature-256HMAC 校验：backend/windmill-trigger-http/src/http_trigger_auth.rs
• Git sync 设置前端界面：frontend/src/lib/components/git_sync/GitSyncRepositoryCard.svelte、frontend/src/lib/components/git_sync/GitSyncSection.svelte
• GHES 自管理应用设置界面：frontend/src/lib/components/instanceSettings/GhesAppSettings.svelte

【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill