如何配置 Scalar SDK 发布到 npm 仓库并注册 OIDC trusted publisher【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalarScalar 的 SDK 发布功能替你完成npm publish你不需要在本地或 CI 里手工发布Scalar 会把 GitHub Actions 工作流写进你的 SDK 仓库由你的 SDK 配置驱动发布。本文的任务是把一个 TypeScript target 配置为发布到 npm并在 npm 侧注册 OIDC trusted publisher可信发布者使合并 release pull request 后包自动发布全程无需创建、存储或轮换 token。前提条件已创建 Scalar 账号并登录已在 dashboard 中创建了 SDK从 OpenAPI 文档生成 TypeScript targettarget 已关联link一个 GitHub 仓库——没有destinations.production的 target 不会生成任何发布工作流仓库的分支保护scalar-next分支和默认分支必须允许 Scalar app 与github-actionsbot 推送或不做保护。第一步关联 GitHub 仓库发布建立在你已有的 GitHub 同步之上所以先确认仓库已关联。打开 target进入Git settings首次连接时 GitHub 会要求你安装 Scalar app 并授权其读写仓库内容、创建 pull request。选择Organization和Repository点击Connect repository。也可以通过配置直接设置destinations{ targets: { typescript: { destinations: { production: { repo: acme/acme-typescript, branch: main } } } } }repo是owner/name形式的 GitHub 仓库branch是发布提升到的默认分支缺省为main生成产物本身始终推送到固定的scalar-generated分支。关联后仓库遵循 Scalar 管理的三分支流程scalar-generated纯生成输出只由 Scalar 推送、scalar-next生成输出与你的自定义代码合并处、默认分支只接收已发布状态Scalar 会持续保留一个从scalar-next发起的 release pull request。第二步为 target 开启 npm 发布发布是opt-in、默认关闭的需要显式打开。两种方式设置的是同一项dashboard打开 target在 Git settings 下打开Publish to npm on merge开关配置给 target 加publish块。{ targets: { typescript: { packageName: acme/api, publish: { npm: true } } } }npm: true时默认使用 OIDC 认证。发布的包名即 target 的packageName如acme/api。开启后有一个自动检查Scalar 会用该包名查询 npm告诉你名字看起来可用还是已被占用。已占用只是警告、从不阻断——npm 无法判断名字是否本来就属于你以自己的名字重复发布是正常情况。第三步在 npm 注册 OIDC trusted publisherOIDC trusted publishing 下publish作业在发布时用一个短命的 GitHub identity token 换取一次性的 registry 凭证仓库里不存任何 token。npm 侧的注册是一次性操作确认包已存在。Trusted publishing 挂靠在已有包上。如果是首次发布要么先手工发布一次1.0.0要么在 npm 上先预留reserve这个名字。添加 trusted publisher。在 npm 网站上打开该包进入Settings → Trusted Publisher → GitHub Actions填写Organization or user你关联仓库的 ownerRepository仓库名Workflow filenamerelease-please.ymlEnvironment留空除非你设置了releaseEnvironment。自动发布运行在release-please.yml内部的publish作业里所以 npm 看到的 workflow 文件名就是它。这是文档明确强调的一点注册release-please.yml不要注册sdk-release.yml。sdk-release.yml是手动重发布已有 tag 的路径只有当你确实会 dispatch 它时才把它作为第二个 trusted publisher 添加。保持默认配置。OIDC 路径下配置就是前面那个npm: true无需 secret。版本要求trusted publishing 需要 npm 11.5.1 或更新。生成的工作流会在发布前自动升级 npm无需你处理。第四步触发发布并核对结果配置完成后发布链路是点击Build或改完配置后Save and Build每个 target 显示pending/generated/failed状态。构建把生成物推送到scalar-generated合并进scalar-next并更新针对默认分支的 release pull request标题形如release: X.Y.Z。该 PR 的 diff 就是完整待发布内容生成变更、自定义代码、changelog 与版本提升。合并该 release pull request触发release-please.yml切出vX.Y.Ztag、更新CHANGELOG.md、创建 GitHub Release同一运行内 release 同步回scalar-next内联的publish作业检出刚切出的 tag 并执行 npm 发布。可核对的点发布是幂等的该版本已在 npm 上时直接跳过重跑不会失败或重复发布所以 re-merge 不会导致发布报错。权限最小化release-please.yml的publish作业权限收敛为contents: read、id-token: write、packages: write其中id-token: write就是 OIDC 发布所依赖的项。版本追溯target 页面会为每个 SDK 版本列出对应 pull request 和 commit可把已发布版本追溯到具体构建。指定精确版本版本号默认由 release-please 按 Conventional Commits 从提交历史计算。若要发精确版本直接编辑 release pull request 标题如release: 1.0.0标题与已提交版本不一致时Release PR versioncheck 会变红Scalar 按你的版本重渲染 PRcheck 变绿后再合并。可选分支改用 npm access token文档给这条路径的场景是无法启用 trusted publishing 时。步骤在 npm 网站上创建Granular Access Token或 ClassicAutomationtoken授予发布该包的权限在 SDK 仓库Settings → Secrets and variables → Actions → New repository secret中添加名称恰好为NPM_TOKEN的 secret——生成的工作流按精确名称读取名字不对就读不到把 target 切到 token 认证{ targets: { typescript: { publish: { npm: { authMethod: access-token } } } } }工作流会把NPM_TOKEN作为NODE_AUTH_TOKEN使用。若设置了releaseEnvironmentnpm 侧 trusted publisher 的 Environment 字段要填同一个值。限制与注意事项发布要求已关联仓库只关联不发布时合并 release PR 只会切 tag 和 Release不会发 npm。scoped 包如acme/api以--access public发布。npm 的包名可用性检查只对 npm 与 PyPI 生效且是警告不是阻断。CLI target 同样走 npm OIDC 发布但它的 publish 作业在启用binaries或homebrew时才会保留contents: write用于上传 Release 资产纯 npm 发布的 CLI 仍是只读权限。配置完成后下一次构建 合并 release pull request 时包就会出现在 npm 上如果该版本已在 npm 上publish 步骤会静默跳过而不是报错。参考文档Publishing 总览、Package Registries、TypeScript (npm)、GitHub Repositories、TypeScript 配置项。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考