跳转到内容
For the complete documentation index, see llms.txt. This page is also available as Markdown.

发布政策

OpenHuman 如何发布版本,包括分支模型、CI 通道、最低版本门槛和密钥轮换。

本运行手册涵盖发布如何上线。它还说明了当最新版本才是受支持流程时,如何阻止用户在过时的桌面安装包上完成 OAuth(包括 Gmail)。

分发

  • GitHub Releases 中的 tinyhumansai/openhuman 是桌面构建的主要来源。

  • Tauri 更新器端点(见 scripts/prepareTauriConfig.js 以及发布工作流)应将用户指向当前发布产物。

  • 当你放弃某条发布线时,要退役旧的稳定产物:

    • 从 GitHub Releases 中移除或隐藏已废弃的安装程序资产。

    • 将网站和 CDN 下载链接指向 releases/latest.

    • 刷新更新器清单(例如 Gist 或 latest.json),使其不再指向已弃用的构建。

    • 检查旧的直接 URL 是否重定向,或者返回 404 或 410。尝试来自文档或书签中已知的旧资产 URL,并确认它们不再提供主要安装路径。

OAuth 的最低应用版本

生产环境 Web 构建会在构建时嵌入最低受支持应用版本,因此 OAuth 深度链接无法在已弃用的二进制文件上完成。每个安装包都带有该构建创建时设置的最低版本线。要为从不升级的用户提高这条下限,需要他们安装一个新发布版本,或者通过应用内更新。

变量
用途

VITE_MINIMUM_SUPPORTED_APP_VERSION

例如 0.51.0。桌面应用必须至少达到此版本才能完成 openhuman://oauth/success.

VITE_LATEST_APP_DOWNLOAD_URL

可选;默认为 https://github.com/tinyhumansai/openhuman/releases/latest。当门禁阻止 OAuth 时会打开该地址。

将这些配置为 GitHub Actions 变量。将它们同时设置在独立的 pnpm build 步骤和 tauri-apps/tauri-action 步骤中,位于 .github/workflows/build-desktop.yml (可复用矩阵, release-production.yml 和 release-staging.yml 调用它),这样已发布安装包中的 Vite bundle 会包含该门禁。本地开发时保留 VITE_MINIMUM_SUPPORTED_APP_VERSION 未设置,即可禁用该门禁。

代码位于 app/src/utils/oauthAppVersionGate.ts, app/src/utils/desktopDeepLinkListener.ts.

Gmail / Google Cloud OAuth

  • Google Cloud Console 中的重定向 URI 必须与当前后端 + 隧道回调路径匹配。

  • 桌面方案(openhuman://)是稳定的。当 VITE_MINIMUM_SUPPORTED_APP_VERSION 被设置时,已安装的二进制必须满足最低版本要求。

发布清单

  1. 提升 app/package.json 和 crates/openhuman-app/tauri.conf.json (以及根目录 Cargo.toml / core)按现有版本工作流进行。

  2. 在放弃对旧安装包的支持时,在该发布之前或同时将 VITE_MINIMUM_SUPPORTED_APP_VERSION 设置为新的最低版本线(仓库 Actions 变量 + 上面的两个工作流步骤)。

  3. 从面向用户的界面中移除、重定向或退役旧的稳定安装程序和过时的更新器条目(GitHub Release 资产、网站、CDN、更新器订阅源)。确认已弃用的产物无法从默认安装/更新流程中访问。

  4. 在全新安装的 releases/latest 上对 Gmail 连接进行冒烟测试。

  5. 完成 手动冒烟检查清单。然后将已完成的签署块原样粘贴为 GitHub 提交评论,所有已勾选的项目保持勾选,发在已验证的 v<version>-staging 带标签提交上。晋升流程没有发布 PR。在批准生产运行之前, Release-Approval 审查者会检查两件事。首先,签署评论是否存在于 staging 标签提交上。其次,生产运行是否针对那些已验证的内容:要么将 staging 标签的 SHA 作为 commit_sha传入,要么确认只有 [skip ci] 版本提升提交将它与运行目标分开。任何更多内容都属于新内容,QA 尚未冒烟测试过,因此请先重新运行 staging。

分支模型和 CI 线路

两个长期存在的分支,两条 CI 线路:

  • main:所有功能和修复 PR 的落点。每个 PR 都会运行 CI Fast(ci-fast-hosted.yml),并对变更区域执行质量检查和完整单元测试套件,差异覆盖率门槛为 80% 或更高。

  • release:维护者晋升的快照,发布版本就是从这里切出。 main 所切出的版本。目标为 release 以及对 release 的每次推送都会运行 CI Full(ci-full.yml):完整单元测试、Rust mock-backend E2E、Playwright Web E2E,以及 Linux 上的桌面 E2E。macOS 和 Windows 桌面 E2E 是手动触发,默认关闭,直到各自都有原生驱动,因此跨平台桌面信号是可选启用的。 CI Full 门禁 检查会汇总除 Playwright 规格运行之外的所有线路。该运行目前不阻塞(continue-on-error,因为在 CI 争用下它容易不稳定),因此绿色门禁并不能证明 Playwright 规格已通过。切版前请检查该线路的结果。只有 Playwright 产物构建会受门禁控制。

流程:

  1. 维护者触发 promote-main-to-release.yml,它会从 main 推送一个合并提交到 release ,无需 PR。重新触发会刷新 release 为最新的 main ,并保留已在 release上的修复提交。如果 release 已经包含 main,则什么也不做。

  2. CI Full 会在晋升推送上运行。如果发现问题,任何有写入权限的人都可以直接针对 release打开修复 PR。修复 PR 会运行两条线路:用于快速 lint 和覆盖率反馈的 CI Fast,以及作为阻止合并的 CI Full 门禁 检查的 CI Full。合并后的推送会在合并结果上重新运行 CI Full。

  3. 一旦 release HEAD 上的 CI Full 变绿,就使用 release-production.yml切出生产版本。如果 QA 需要先验证 main ,也可以改为从 main 触发 staging。发布工作流不会检查 CI Full 门禁,因此操作人员在切版前必须验证 CI 证据。

  4. 从 release 回合并 release 推送一个合并提交到 main ,使用 scripts/release/merge-release-into-main.sh。它会在可能时快进,否则会创建一个带版本号的合并提交,例如 chore(release): merge release v1.2.4 back into main。提升和修复提交会沿此路径回流。来自 main 的 staging 切版不需要回合并。版本提升提交会携带 [skip ci].

此模型所需的 GitHub 设置(仓库 Settings > Rules): main 要求 PR CI Gate 状态检查用于 PR; release 要求对非绕过角色的 PR 进行 CI Full 门禁 状态检查(它运行在目标为 release 的 PR 上);release GitHub App 在两个规则集的绕过列表中,因此 promote 和 release 工作流可以直接推送。

工作流:staging 和 production

每个环境只有一个 GitHub Actions 工作流。按意图选择,不要切换标志。staging 遵循所选的 main 或 release 触发 ref;production 始终检出 release,不管 GitHub 工作流 UI 显示的触发 ref 是什么。

工作流
分支
提升
推送的标签
并发组
何时使用

main 或 release

补丁 仅

v<version>-staging

release-staging

从所选分支为 QA 切出 staging 构建。

release

补丁 / 次要 / 主要 (release_type 输入)

v<version>

release-production

从已验证的 release HEAD(或固定的 commit_sha).

这两个流程使用的构建、签名、Sentry 调试文件和产物上传流水线位于 .github/workflows/build-desktop.yml 中,作为一个可复用的 workflow_call 工作流。上面这两个工作流负责 ref 解析、版本提升、打标签,以及发布和清理。构建本身是共享的。

Android / Google Play

Android 发布由单独的 .github/workflows/android-compile.yml 工作流处理。它会构建发布版 Android App Bundle(.aab),使用 Play 上传密钥签名,并在启用发布时上传到 Google Play。未签名和已签名的 AAB 会作为 Actions 产物保留,用于审计和调试。

手动 Android 上传使用同一个工作流:

所需的 GitHub Actions 密钥:

密钥
用途

ANDROID_UPLOAD_KEYSTORE_BASE64

Base64 编码的 Play 上传 keystore(.jks)。请使用上传密钥,而不是 Google 应用签名密钥。

ANDROID_UPLOAD_KEY_ALIAS

上传密钥的 keystore 别名。

ANDROID_UPLOAD_KEYSTORE_PASSWORD

keystore 密码。

ANDROID_UPLOAD_KEY_PASSWORD

密钥密码。

GOOGLE_PLAY_SERVICE_ACCOUNT_JSON

Play Console 服务账户的原始 JSON,具有 com.openhuman.app.

可选的 GitHub Actions 变量:

变量
默认值
用途

ANDROID_PLAY_TRACK

internal

要上传到的 Play 轨道(internal, alpha, beta,或 production).

ANDROID_PLAY_STATUS

completed

Play 发布状态(completed, draft, inProgress, halted).

Google Play 要求每次上传的 Android versionCode 都必须高于上一次。发布提升脚本会更新 app/src-tauri-mobile/tauri.conf.json, app/src-tauri-mobile/Cargo.toml 和 app/src-tauri-mobile/Cargo.lock 以及桌面文件,因此生成的 Android tauri.properties 会随每次发布一起变更。

切出 staging 构建

  1. 通过 workflow_dispatch 从 release 运行 Release (Staging)(可选地固定一个可达的 release commit_sha). create_tag = false 进行提升和提交,而不打标签或构建。

  2. 工作流会在 补丁 上提升 release,提交 chore(staging): vX.Y.Z [skip ci],推送,并在该提交处创建一个不可变的 vX.Y.Z-staging 标签。

  3. 构建矩阵从标签运行,而不是从 release HEAD 运行,因此即使 release 已经前进,重跑也会重新构建相同内容。

  4. 提升提交(以及在 release上的其他内容)会回合并到 main.

  5. 失败时,staging 标签会自动删除。源分支上的提升提交 release 会保留,因此下一次切版会从 vX.Y.(Z+1).

没有单独的 staging 分支。staging 切版和生产发布都位于 release,而只有标签后缀(-staging 或无)以及创建该标签的工作流将它们区分开来。

发布生产版本

  1. 通过 workflow_dispatch 运行 Release Production,使用所需的 release_type (补丁 / 次要 / 主要),从 release HEAD 或固定的、可达的 release commit_sha.

  2. 该运行首先等待 review-approval 作业(environment: Release-Approval)。在任何内容被推送之前, 必需审查者 必须先批准。然后 prepare-build 在 release,提交 chore(release): vX.Y.Z [skip ci]上提升版本、推送、打标签 vX.Y.Z,构建并发布。

  3. release 会在切版后立即回合并到 main 。

标签策略和回滚

  • 命名:staging 标签使用 SemVer 预发布后缀 -staging (v1.2.4-staging,因此它们会排在对应的生产标签之前。

  • 冲突:如果目标标签在本地或 origin上已存在,两个工作流都会快速失败。删除旧标签(仅限组织维护者)或将版本号提升到其之后。

  • 生产回滚:失败的构建矩阵会触发 cleanup-failed-release,它会删除草稿 GitHub Release 和 v<version> 标签。

  • staging 回滚:失败的 staging 构建会删除 v<version>-staging 标签。源分支上的提升提交会保留。下一次 staging 切版会从新的补丁号继续,这样会留下一个小的补丁号空档,而不是与并发合并竞争。

  • 删除标签:你需要与 main相同的写入权限。工作流清理通过 actions/github-script使用工作流的 token 运行。GitHub App token 仅由 prepare-build 用于提升提交和标签推送。手动删除(git push --delete origin <tag>)需要同等的维护者权限。

Release App 令牌:审批门禁和轮换

release-production.yml 提升版本、提交到 release 并回合并到 main,使用 GitHub App token(secrets.XGITHUB_APP_ID / secrets.XGITHUB_APP_PRIVATE_KEY)推送这些提交和标签,从而绕过分支保护。相同的 App 还会将 staging 提升推送到所选的 main 或 release 源(release-staging.yml)以及晋升合并提交(promote-main-to-release.yml)。私钥泄露(通过日志、被攻破的 action 或配置错误的 runner)会让攻击者向受保护分支推送任意提交(CWE-250)。有两个控制措施可限制损害。

手动审批门禁

该 review-approval 作业会在 prepare-build 之前运行,并将每个生产运行停放在 Release-Approval GitHub 环境上,因此在任何推送发生之前都必须由人工批准。

一次性设置(仓库 Settings > Environments):

  1. 创建一个名为 Release-Approval 的环境(必须是精确名称,因为工作流会原样引用它)。

  2. 在 Deployment protection rules 下,启用 Required reviewers,并添加允许授权生产推送到 main的维护者。若 Prevent self-review 关闭,审查者不能批准自己的运行。对于发布门禁,请保持开启,让第二个人来批准。

  3. 可选地将等待计时器设为 0。这个门禁是人工决策,而不是延迟。

当生产运行开始时, review-approval 作业会显示“Waiting”。批准者打开运行并点击 Review deployments > Approve。拒绝或取消会跳过 prepare-build,因此不会有任何内容被推送。

季度密钥轮换

轮换 XGITHUB_APP_PRIVATE_KEY 每个季度一次(如有任何疑似泄露则立即轮换)。在 3 月、6 月、9 月和 12 月末执行。

  1. 在 GitHub App 设置中(Org > Settings > Developer settings > GitHub Apps > 该 release App),在 Private keys 下点击 Generate a private key。下载新的 .pem.

  2. 更新仓库密钥:Settings > Secrets and variables > Actions > XGITHUB_APP_PRIVATE_KEY,然后粘贴完整的新密钥(包括 -----BEGIN/END----- 行)。 XGITHUB_APP_ID 保持不变。

  3. 触发一次低风险的验证运行,例如 Release(Staging),并确认 Generate GitHub App token 步骤成功且推送已通过身份验证。除非你确实要切出一个真实的 bump 提交,否则不要将 Release Production 用于此目的。即使在 create_release = false, prepare-build 仍然会提升版本并提交到 release。Staging 时 create_tag = false 也会提交,但会跳过标签和构建,因此是风险较低的探测方式。

  4. 回到 App 设置中的 Private keys,删除旧密钥,这样只会保留刚签发的密钥有效。

  5. 在 PR 描述或运维日志中记录轮换日期,以便下一位负责人能看到上次发生的时间。

轮换会使任何泄露的旧密钥副本失效,从而将暴露窗口限制在一个季度内。

最后更新于