Codex Security 发布流程全解析：从 Conventional Commit 到 npm 与 GitHub Releases 的自动化发布管线

Codex Security 发布流程全解析从 Conventional Commit 到 npm 与 GitHub Releases 的自动化发布管线【免费下载链接】codex-securityOpenAIs Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/openai/codex-security项目地址: https://gitcode.com/gh_mirrors/co/codex-security导读本文以仓库根目录下的 RELEASING.md 为主体系统讲解 OpenAI Codex Security CLI 与 TypeScript SDKnpm 包openai/codex-security的完整发布流程。你将掌握如何规范 Pull Request 标题以驱动自动化的版本发布分类、0.x 阶段的版本号策略、滚动发布 PRrolling release PR的工作机制与启用方式、手动准备与发布一个版本的完整步骤以及发布后如何校验和修复已发布的版本。文中所有关键环节均结合仓库内的工作流定义.github/workflows 目录与发布脚本sdk/typescript/scripts 目录给出源码级佐证读者既可照做发布一个真实版本也能理解每个自动化步骤背后的设计意图。一、发布体系总览Changelog、版本标识与发布形态Codex Security 采用「GitHub Releases 作为权威 changelog npm 包同步发布」的双通道发布模型二者由同一套版本号串联GitHub Releases是标准变更日志canonical changelog。在新流程下每次发布包含一段简短、经过评审的摘要reviewed summary外加按分类整理的已合并 Pull Request 清单历史发布可能只有自动生成的 notes。版本标识统一Git tag 使用npm-vX.Y.Znpm 包版本为openai/codex-securityX.Y.Z两者永远保持一致。从源码可以验证这一约束被严格执行在 sdk/typescript/scripts/release-automation.mjs 中releaseTagVersion同时校验 tag 名必须匹配npm-vX.Y.Z格式且 tag 版本必须与sdk/typescript/package.json中的 package 版本完全相等否则直接抛错。发布动作本身不是单一步骤而是三个受保护的工作流接力完成后续章节会逐一展开工作流职责触发方式node-release-cut校验版本递增、校验评审过的 release notes、创建精确的npm-vX.Y.Ztagnode-ci在main上成功后自动触发或手动调度node-release安装锁定依赖、测试、打包、发布 npm 并记录 provenance推送npm-v*tag 时触发node-github-release再次核验 npm 包、provenance、tag 与归档后发布 GitHub Release由node-release成功发布后派发或手动调度发布完成的标准是npm 包与 GitHub Release 都已存在且与 tag 一致版本号 bump 本身不构成一次完成的发布。二、Pull Request 标题规范决定 Release 分类的「输入契约」发布分类不是人工整理的而是由 PR 标题按 Conventional Commits 规范机械推导而来。因此标题格式是发布自动化的第一道输入契约。2.1 标题格式type[optional scope][!]: description约束细节type必须是小写、以字母开头且只能包含字母、数字和连字符源码层面见 .github/workflows/validate-pr-title.yml 中的正则^([a-z][a-z0-9-]*)(\([a-z0-9][a-z0-9._/-]*\))?(!)?: $scope若存在必须小写description必须以非空白字符开头且不能以空白字符结尾不能有尾部空格。合法示例feat(cli): add component scan planning fix(windows): preserve Unicode paths docs: explain scan cost limits feat(sdk)!: remove the legacy result field2.2 标题到 Release 分类的映射表标题中的type、scope和!直接决定该 PR 进入哪个 release 分类标题特征Release 分类任意 type 且带!Breaking changesfeatFeaturesfixFixesdocsDocumentationchore(release)、release、test被排除不进入 notes其他任意 typeOther changes需要说明的是release notes 草稿的生成逻辑在 sdk/typescript/scripts/release-pr.mjs 的generateNoteSections中实现其中被排除的变更还包括带skip-release-notes标签的 PR详见visibleChanges函数而 GitHub 侧最终生成 notes 时的分类标签配置见 .github/release.yml。2.3 内部变更与人工覆盖chore(release)专用于发布准备test专用于纯测试改动release是遗留的旧类型、仍然受支持——三者都只能用于不影响包使用者的变更维护者可以给某个 PR 打上skip-release-notes标签将其从 notes 中排除该人工标签优先于标题推导出的分类仓库根目录 .github/workflows/validate-pr-title.yml 会在 PR 打开/编辑/同步时强制校验标题是否符合 Conventional Commit 格式不合法直接报错从而在源头保证分类推导可靠。三、依赖更新策略Dependabot 与版本冻结规则发布质量依赖健康的依赖管理仓库通过 .github/dependabot.yml 配置了每日检查检查范围npm 包、Python 测试依赖、GitHub Actions周末也执行冷却期cooldownOpenAI 自家依赖openai、openai/*无冷却期其他依赖的新版本必须至少发布满 7 天才能合入安全更新豁免安全修复不受上述版本更新冷却期限制人工兜底所有更新仍须经过评审且 CI 通过不会自动合并。一个值得注意的细节是Codex 依赖的三处强一致openai/codex与openai/codex-sdk必须在 TypeScript SDK、MCP appplugins/codex-security/mcp-app/package.json和 triage evals 三处锁定完全相同的精确版本当前在 sdk/typescript/package.json 中为0.155.0。Dependabot 会跨三个项目分组更新它们而 SDK 的测试会拒绝不匹配的 pin 或锁定的多个 SDK 版本triage evals 还会覆盖 Promptfoo 传递依赖中的 Codex SDK 为直接依赖使其跟随同一更新。每个 pnpm 项目对**新解析出的依赖含传递依赖**同样执行 7 天年龄策略已提交的 lockfile 必须保持可安装状态原有的 Socket release checks 依旧生效。四、0.x 阶段的版本号策略patch 与 minor 的语义边界包目前处于0.x当前 sdk/typescript/package.json 版本为0.1.29版本策略如下普通变更含新功能→ patch 版本例如0.1.23之后的普通变更提议0.1.24破坏性变更 → minor 版本并将 patch 归零例如任何包含破坏性变更的提议版本为0.2.0分类与 bump 解耦feat的分类永远是Features但分类本身不意味着 minor bump。该策略在 sdk/typescript/scripts/release-pr.mjs 的nextReleaseVersion中落地当版本为0.x时若变更列表中任一变更判定为 breaking则返回0.(minor1).0否则返回0.minor.(patch1)若版本已进入1.x该函数会直接抛错提示「Review the release PR version policy before enabling it for 1.x」。4.1 破坏性变更的三种识别信号发布 PR 更新器updater从以下三种信号中识别破坏性变更见 sdk/typescript/scripts/release-pr.mjs 的isBreakingChangeConventional Commit 标题中的!如feat(sdk)!: ...提交信息或 PR body 中的BREAKING CHANGE:或BREAKING-CHANGE:footerbreaking-change标签。4.2 需要注意的边界skip-release-notes只影响可见性不影响版本影响发布边界之后的所有 merge 和直接提交都计入下一版本包括文档和内部变更在为1.x启用自动化之前必须先评审这套策略。五、滚动发布 PR让 main 上的每次合并自动推进发布提案这是整个发布体系中最具特色的机制。node-release-pr工作流定义见 .github/workflows/node-release-pr.yml在main分支每次 push 后运行也可手动调度默认是只读预览模式——它不会 merge、打 tag、发布也不会改动既有的发布门禁。5.1 核心工作方式当某个变更在当前包版本之后首次到达main更新器会在release/next-base-version分支上打开一个 ready-for-review 的提案 PR之后每次更新都会基于该包版本首次到达 main 以来的全部变更重新计算版本仓库要求以squash-merge合入发布 PR这样整个提案作为一个发布边界提交release boundary commit落地生成的 PR 标题与提交主题均为chore(release): X.Y.Z与提案版本一致合入时需确认 squash 提交主题使用的是当前 PR 标题后续若出现破坏性变更会在同一个 PR上更新版本与标题每次更新都会并入最新的main并追加一个提交更新器从不 force-push遇到并发提交会重新读取并重试提案文件变更时会请求 Codex review仅并入main的更新只保持 CI 最新不会重复发起提案评审新的「人工备注」建议仍会以评论形式出现。5.2 空周期与中断恢复当发布版本合入后更新器会等待下一个变更到达 main才打开新提案空发布周期返回action: unchanged不创建分支或 PR。但上一个版本的发布必须完成并通过后续章节的验证步骤如果已存在另一个面向main的chore(release):或遗留release:PR包括人工准备的发布更新器不会动它也不会开重复 PR——需要先完成或关闭那个 PR 再启用新流程关闭自动化提案会暂停其周期重新打开即恢复把提案 base 从main改走同样会暂停更新恢复main后继续更新器在推进分支前会重新检查暂停条件。release 分支上的其他文件改动、或除 version 之外的 package 字段改动也会暂停更新器防止这些编辑丢失。这类有意暂停返回action: held且工作流保持成功——先把额外改动保留或合并再重跑更新器即可恢复。5.3 编辑发布说明release notes的所有权模型已提交的 .github/release-notes.md 是权威发布说明。更新器用合并标题起草 Highlights并列出标记的破坏性变更供迁移评审——它不根据源码推断迁移指引。发布前需人工评审并打磨这些建议。所有权机制细节在发布 PR 分支上编辑 highlights 或升级说明时保留周围的release-section注释可维持分区边界机器人只在分区内容与上次生成的草稿完全一致时刷新该分区。一旦被编辑或删除该分区就成为human-owned人工所有后续更新会原样保留分区外的自定义文案也始终保留后续新建议会出现在同一 PR 的新机器人评论中不会覆盖人工备注机器人会更新版本头与 PR 标题但永不重写 PR 描述提案版本变化时需人工复核文案中与版本相关的链接.github/release-pr-state.json 记录周期与分区所有权当前内容显示0.1.28周期下highlights与upgrades两个分区均为自动生成状态humanOwned: false。若要显式重新生成某分区给该分区状态加reset: true下一次运行会消费该 reset 并恢复自动更新不要删除 state 文件来重置所有权。缺失所有权元数据的分区会被保留直到显式 reset——缺失 state 不等于授权覆盖人工备注删除 notes 文件同样会被保留处理。合入前必须恢复评审过的 notes 或显式 reset 分区因为发布要求存在带版本号的 notes 文件。5.4 预览与启用含本地 dry run本地预览在已认证ghCLI 的前提下在仓库本地检出可执行RELEASE_PR_DRY_RUNtrue node sdk/typescript/scripts/release-pr.mjs预览可能会在本地抓取缺失的 Git 对象但不做任何 GitHub 写入其 JSON 输出包含拟修改的文件以及更新器可能暂停的原因。托管预览工作流在main上之后用其Run workflow表单勾选dry_run来测试托管只读路径。启用写入分两步在仓库Settings → Actions → General → Workflow permissions中开启Allow GitHub Actions to create and approve pull requests然后手动调度工作流并取消勾选 dry_run。这会允许一次写入运行而自动更新仍保持禁用。工作流默认使用仓库的GITHUB_TOKEN权限为Contents: write和Pull requests: write无需单独的 App 凭证预览运行使用独立的只读权限 job。评审生成的 PR并在其 merge 框中选择 Approve workflows to run以启动托管 CIGitHub 要求对用GITHUB_TOKEN创建/更新的 PR 进行此批准。同时检查当前 head 上的 Codex review若自动请求未启动评审则手动请求。可选若想免去上述批准步骤可配置一个安装在本仓库的 GitHub AppContents: writePull requests: write并设置RELEASE_APP_CLIENT_ID仓库变量与RELEASE_APP_PRIVATE_KEYsecret。配置了 Client ID 后写入运行会请求限定于本仓库的 App token私钥缺失或无效会导致运行失败。预览始终使用GITHUB_TOKEN。正式启用手动写入运行验证通过后把RELEASE_PR_ENABLED仓库变量设为true允许mainpush 后自动更新删除该变量或设为false则回到仅预览。手动运行始终遵循其 dry_run 输入默认预览关闭自动更新不会阻止显式的手动写入运行。生成的 PR 会把 disclosure attestations 留空待维护者评审。六、手动准备一个发布从版本号到评审过的发布说明当滚动发布 PR 机制尚未启用或需要人工控制节奏时可按下述 5 步准备发布确定版本并更新sdk/typescript/package.json 的version字段若 lockfile 记录了包版本需保持同步更新器只更新顶层 version 字段的实现见 sdk/typescript/scripts/release-pr.mjs 的updatePackageVersion。更新.github/release-notes.md其第一行必须是!-- release-version: X.Y.Z --且版本号与包版本完全一致。该约束由parseReviewedReleaseNotessdk/typescript/scripts/release-automation.mjs强制执行——notes 必须以此精确头开始且包含评审过的摘要文本。当前仓库的 .github/release-notes.md 即为!-- release-version: 0.1.29 --的样板。撰写用户可见变更摘要说明用户会感知的变化点明必需的迁移或兼容工作链接相关公开文档而把 PR 清单交给生成分区。打开 PR使用严格的 Conventional Commit 标题例如chore(release): 0.2.0。运行变更文件所需的检查并把结果记录在 PR 中当前 commit 上必需 CI、评审与公开披露检查全部通过之前不得合并。评审摘要的标准与产品文档相同保持具体、描述行为而非实现、不包含私有仓库、系统、人名、发现、链接或 issue 标识符。七、发布执行三个受保护工作流的接力版本 bump 合入main且node-ci在该精确 commit 上成功后发布开始7.1node-release-cut验证并打 tag工作流定义见 .github/workflows/node-release-cut.yml核心动作通过node sdk/typescript/scripts/release-automation.mjs的子命令完成校验version解析稳定版本、validate-release-notes校验 notes 头与摘要、require-increase/require-published-increase确保版本大于上一个/所有已发布版本、release-mode区分 publish 与 recover 模式只在main且是main上可达的 commit 上允许打 tagRelease tags can only be cut from main.若npm-vX.Y.Ztag 已存在验证其指向的 commit 是否为当前RELEASE_SHA不一致则失败——绝不重打指向其他 commit 的 tag校验通过后创建精确 tag并派发node-release工作流。7.2node-release验证、打包、发布 npm工作流定义见 .github/workflows/node-release.yml由npm-v*tag push 触发包含原生构件先运行nativejob复用 .github/workflows/native-artifacts.yml准备 native runtime并通过 .github/actions/download-native/action.yml 下载Socket Firewall 与锁定安装所有 registry 指向openai.firewall.socket.devpnpm install --frozen-lockfile安装 SDK 与 MCP app评审过的 notes 校验mode publish时再次执行validate-release-notes测试与打包pnpm run types、test、test:mcp、formatnpm pkg set gitHead$GITHUB_SHA后pnpm pack再check:package检查 tarball用CODEX_SECURITY_EXPECTED_GIT_HEAD校验冒烟测试在临时 consumer 中安装 tarballimport SDK、运行codex-security --version与--help发布publish job 使用受保护的npmenvironmentid-token: write权限下执行npm publish ./dist/*.tgz --provenance --access public --tag latest首个版本npm-v0.1.0使用NPM_FIRST_PUBLISH_TOKEN之后走 trusted publishing并验证 npm 版本支持 Sigstore attestationnpm plugin 载荷node-release在prepack阶段从权威源 plugins/codex-security/ 生成 npm plugin 载荷。生成的sdk/typescript/_bundled_plugin/目录不是提交的发布输入——不要通过编辑或提交那里的文件来准备发布发布成功后派发node-github-release附 tag 与本次 run id。7.3node-github-release核验后发布 GitHub Release工作流定义见 .github/workflows/node-github-release.yml在main上运行接受tag必填与run_id用于回填输入解析 tag 指向的 commit并通过gh run list找到该 commit 上成功完成的node-release运行run id 未提供时自动查找最多轮询 30 次下载已验证的 npm 归档artifact 过期时从公开 npm registrynpm pack回退然后重新核验公开 npm 包与签名 provenancenpm view取元数据、npm audit signatures --include-attestations生成签名报告再调用release-automation.mjs的verify-provenance/verify-recovered-provenance/verify-github-publication逐字段比对版本、gitHead、SHA-512、Fulcio 签名证书的 workflow 身份、run 身份与 npm environment完整实现见 sdk/typescript/scripts/release-automation.mjs通过 GitHub APIgenerate-notes生成分类 notes配置来自 .github/release.yml再经compose-release-notes把评审过的摘要来自 tagged 的 .github/release-notes.md 或既有 release body前置到生成 notes 之前最后校验 tag 仍指向已验证 commit然后gh release create标题Codex Security X.Y.Z、--verify-tag、--latest由release-history计算结果决定。发布期间应监控全部三个工作流版本 bump 不等于发布完成直到 npm 包与 GitHub Release 都存在且与 tag 匹配。八、发布后验证清单向外界宣布发布前逐项核对tag 指向合并后的发布 commitnpm view openai/codex-securityX.Y.Z报告预期的版本与 commit且node-release中的 provenance 检查已通过GitHub Release 是稳定版、标题正确且恰好包含一个经过验证的包归档最新版本标记为Latest历史回填版本不标记为 Latest本流程创建的发布其评审摘要、分类标题、文档链接与完整对比链接均正确历史发布可以只有生成 notes每个已合并的 PR 都已包含在内或被有意打上skip-release-notes标签。九、发布失败后的恢复与修复核心原则不要重定向retarget发布 tag也不要在同一版本下发布第二个 npm 包。工作流设计为在保留原始 tag 与包身份的前提下从部分发布中恢复。9.1 重试 GitHub 发布从main上以既有npm-vX.Y.Ztag 运行node-github-release并在自动查找不足时提供成功的node-releaserun ID。工作流会先再次核验 npm 构件与 provenance然后创建或更新 release。9.2 修复既有 release 的分类先修正已合并 PR 的标题或 release 标签再为该 tag 重跑node-github-release。9.3 历史 release 补摘要标记对早于 .github/release-notes.md 的 release在既有 release body 开头放置以下标记块结束标记与生成 notes 之间保留一个空行!-- codex-security-release-summary:start -- Reviewed summary !-- codex-security-release-summary:end -- Generated notes工作流会保留被标记的摘要并替换生成分区对应实现见 sdk/typescript/scripts/release-automation.mjs 的extractHistoricalReleaseSummary与composeReleaseNotes。任何恢复或修复之后重复执行上一节的全部验证步骤并复核最终公开的 release body。十、总结一次发布的生命周期把整套机制串起来一次典型发布的生命周期是开发者按 Conventional Commit 规范提交 PR.github/workflows/validate-pr-title.yml 强制校验→ 合入mainnode-release-pr.github/workflows/node-release-pr.yml在release/next-base上维护滚动发布 PR按 sdk/typescript/scripts/release-pr.mjs 的nextReleaseVersion计算0.x版本、起草 notes、请求 Codex review人工评审 notes 与 PRsquash-merge 后版本 bump 落地mainnode-ci通过 →node-release-cut校验并创建npm-vX.Y.Ztagtag push 触发node-release锁定安装、测试、打包、--provenance发布 npmnode-github-release再次核验后发布 GitHub Release评审摘要 自动分类 notes按验证清单确认 npm 包与 GitHub Release 均已就绪方可对外宣布。这套流水线把「标题规范 → 版本计算 → notes 起草 → 双通道发布 → 事后校验与修复」全部制度化既保证了 0.x 阶段版本策略的一致性也通过 dry-run 预览、人工所有权分区与受保护工作流把自动化与人工评审的边界划分得清晰可控。【免费下载链接】codex-securityOpenAIs Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/openai/codex-security项目地址: https://gitcode.com/gh_mirrors/co/codex-security创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考