DesktopEditors CI/CD流水线解析:GitHub Actions工作流与WinGet自动发布
DesktopEditors CI/CD流水线解析:GitHub Actions工作流与WinGet自动发布
DesktopEditors 是一款免费开源的桌面办公套件,本文带你拆解它的 CI/CD 流水线:4 个 GitHub Actions 工作流如何分工协作,以及新版本发布后如何通过 WinGet 自动发布 机制,让 Windows 用户一条命令就能升级软件。无需深入代码,普通用户和新手也能看懂这套自动化体系的完整运转逻辑。
一、DesktopEditors 的流水线为什么值得学?
DesktopEditors 采用 super-repository(超级仓库) 模式:主仓库本身几乎不含业务源码,真正的代码分布在 9 个 Git 子模块中(core、sdkjs、web-apps、desktop-apps、desktop-sdk、dictionaries、document-templates、core-fonts、sdkjs-forms),清单定义在 .gitmodules 里。
这种结构带来一个典型难题——子模块版本如何保持同步。而 DesktopEditors 用一套轻量但完整的 GitHub Actions 工作流解决了它,所有配置都在 .github/workflows/ 目录下,总共只有 4 个文件:
| 工作流 | 触发时机 | 核心职责 |
|---|---|---|
check.yml |
手动 / CHANGELOG.md 变更 | 校验更新日志的 Markdown 格式 |
conventional-commits.yml |
每个 PR 打开或更新时 | 检查 PR 标题与提交信息是否符合规范 |
update-submodules.yml |
每天 06:00 定时 / 手动 | 自动同步 9 个子模块并创建 PR |
winget.yml |
发布 Release 时 | 自动向 WinGet 商店推送新版本 |
下面逐个拆解。🔍
二、Check 工作流:更新日志也要过"语法检查"
文件:.github/workflows/check.yml
这个工作流在两种情况下运行:
- 手动触发(
workflow_dispatch) - 向
CHANGELOG.md推送变更时(push的paths过滤,只有改了更新日志才触发,避免浪费资源)
任务本身只有一步:调用 markdownlint-cli2 对 CHANGELOG.md 做格式校验。规则来自仓库根目录的 .markdownlint.json,其中关闭了行宽限制(MD013),并允许同级标题重名(MD024 的 siblings_only)。
💡 新手提示:
paths过滤是 GitHub Actions 的经典优化技巧——只在相关文件变化时运行工作流,能显著节省 CI 分钟数。
三、Conventional Commits 工作流:给提交信息"上安检"
文件:.github/workflows/conventional-commits.yml
这是一个由组织模板仓库统一提供的共享工作流,在 PR 被打开、编辑、同步或重新打开时自动运行(pull_request 事件)。它做的事:
- 通过
gh api拉取 PR 的所有提交记录; - 用正则校验 PR 标题和每条 commit 标题(自动跳过
Merge开头的合并提交); - 不符合格式则直接报错,并给出 10 种合法的类型前缀:
build chore ci docs feat fix perf refactor revert style test
也就是说,一个合格的提交标题必须形如 feat: xxx、fix(winget): xxx 这类 Conventional Commits 格式。这种规范化的提交信息正是后续自动生成变更日志(CHANGELOG.md 按 Features / Bug fixes 分节)的基础。
该工作流还配置了 concurrency 组(以 PR 编号分组 + cancel-in-progress: true):PR 连续推送新提交时,旧运行会被自动取消,只保留最新一次,进一步节省资源。
四、update-submodules 工作流:每天清晨自动"拉齐"子模块
文件:.github/workflows/update-submodules.yml
这是整个流水线中最"省心"的一环,触发条件有二:
- 定时任务:
cron: '0 6 * * *',即每天 06:00 自动运行; - 手动触发:维护者可以随时在 Actions 页面手动执行。
工作流本体只有几行——它是一个 可复用工作流(reusable workflow),直接引用上游 DocumentServer 仓库中现成的更新脚本,并继承 secrets(secrets: inherit),同时声明 contents: write 和 pull-requests: write 权限,用于向本仓库提交更新。
它解决的实际问题:9 个子模块的 main 分支每天都在前进,而超级仓库记录的还是旧的提交指针。该工作流每天自动将每个子模块对齐到其 main 最新提交,并自动开一个 PR,维护者审查合并即可——无需人工执行 git submodule update 再手动提交。
每天 06:00 定时触发
│
▼
逐个检查 9 个子模块 main 分支
│
▼
有新提交?──否──► 结束
│是
▼
创建更新子模块指针的 PR
│
▼
维护者审查 → 合并
五、WinGet 自动发布:Release 一出,商店同步上架
文件:.github/workflows/winget.yml
这是本文的主角。WinGet 是 Windows 10/11 自带的命令行包管理器,用户只需执行 winget install ONLYOFFICE.DesktopEditors 即可安装。而这个工作流让"新版本上架 WinGet"完全自动化,核心配置一览:
name: Publish to WinGet
on:
release:
types: [released] # 触发器:Release 正式发布时
jobs:
publish:
runs-on: windows-latest
steps:
- uses: vedantmgoyal9/winget-releaser@main
with:
identifier: ONLYOFFICE.DesktopEditors
installers-regex: '(x86|x64|arm64)\.exe$'
token: ${{ secrets.WINGET_TOKEN }}
逐行解读:
| 配置项 | 作用 |
|---|---|
release: types: [released] |
只有 Release 真正发布(而非创建、编辑)时才触发,杜绝误发布 |
identifier |
WinGet 中的软件包标识,必须与商店中已注册名称一致 |
installers-regex |
只认 Release 附件中匹配 x86/x64/arm64.exe 的安装包,ZIP 等产物自动忽略 |
token: secrets.WINGET_TOKEN |
用于向 WinGet 官方仓库提交 PR 的凭据,存于仓库 Secrets,不落地明文 |
完整链路是这样的:
打 Tag / 发布 Release(如 v9.3.6)
│
▼
CI 构建出 Windows 安装包(Inno Setup .exe,含 x64/arm64 等架构)
│
▼
Release 附件包含 xxx-x64.exe / xxx-arm64.exe
│
▼
winget.yml 被 [released] 事件唤醒
│
▼
winget-releaser 下载匹配的 .exe,自动生成提交 PR
│
▼
WinGet 官方仓库审查合并 → 用户 winget upgrade 即可拿到新版本
值得注意的是正则 (x86|x64|arm64)\.exe$ 的设计:它让同一个工作流兼容 x86、x64、arm64 三种架构的命名约定,而这套命名规则与 build/windows/ 构建产物(desktop-apps\package\ 下的 Inno Setup 安装器)严格对应。版本号则来自 Git Tag(如 v9.3.6 → 9.3.6),开发期版本记录在 VERSION.txt(当前为 9.3.6-rc.1)。
📦 对用户的意义:官方渠道(如 Nextcloud Office 品牌)之外的社区构建发布到 Release 后,Windows 用户无需手动下载,
winget install ONLYOFFICE.DesktopEditors就能安装,且后续winget upgrade --all可自动升级。
六、流水线全景:从一次提交到用户升级
把 4 个工作流串起来,就是 DesktopEditors 的完整 CI/CD 生命周期:
开发者提交 PR
│ conventional-commits.yml:标题/提交信息必须规范
▼
合并 + 修改 CHANGELOG.md
│ check.yml:更新日志通过 markdownlint
▼
打 Tag、构建并发布 Release(build-common / build-linux / build-windows 三任务,
详见 <a href="https://link.gitcode.com/i/b91adac8f9d9ed8a1142f773a44b8c9b" target="_blank">build/README.md</a>;Windows 端由
<a href="https://link.gitcode.com/i/e2c9d5d34e2ca9834e4b66381e37b2da" target="_blank">build/windows/build.ps1</a> 产出 ZIP 与 Inno 安装器)
│ winget.yml:自动向 WinGet 商店推送
▼
每天 06:00 update-submodules.yml 持续拉齐 9 个子模块,为下个版本蓄力
三平台构建产物各有分工:Linux 走 Docker 容器化构建(docker buildx bake,见 build/linux/),Windows 走 MSVC + CMake 原生构建,macOS 用 Xcode 原生编译(见 build/macos/)——其中 Windows 的 .exe 安装器正是 WinGet 工作流的"燃料"。
七、动手体验:如何复现这套流程
本地克隆仓库即可观察全部工作流定义:
git clone https://gitcode.com/gh_mirrors/deskt/DesktopEditors
cd DesktopEditors
git submodule update --init --recursive
建议按以下顺序体验:
- 看配置:通读 .github/workflows/winget.yml,全文仅 14 行,却是自动上架的完整闭环;
- 试 WinGet:在 Windows 的 PowerShell 中执行
winget search ONLYOFFICE.DesktopEditors,查看商店中的版本与 Release 是否一致; - 查版本:打开 CHANGELOG.md 对照 VERSION.txt,理解
v9.3.6-rc.1这类 rc(候选版)Tag 如何映射到构建版本号。
八、路径速查表 📌
| 文件 | 说明 |
|---|---|
| .github/workflows/check.yml | 更新日志格式检查 |
| .github/workflows/conventional-commits.yml | PR 与提交规范检查 |
| .github/workflows/update-submodules.yml | 每日自动同步子模块 |
| .github/workflows/winget.yml | WinGet 自动发布 |
| .markdownlint.json | Markdown 校验规则 |
| .gitmodules | 9 个子模块清单 |
| build/README.md | 三任务构建模型总览 |
| VERSION.txt | 当前版本号 |
总结
DesktopEditors 的 CI/CD 流水线给出了一个值得借鉴的范本:用 4 个极简工作流覆盖"格式守门 → 提交规范 → 依赖同步 → 商店发布"全链路。其中 winget-releaser + installers-regex 的组合让 WinGet 自动发布只需十几行 YAML,而每日 6 点的子模块自动更新则把 super-repository 的最大痛点变成了"合并 PR 即可"。如果你正在为自己的项目搭建 CI/CD 流水线,这套小而精的架构绝对值得抄作业。✍️