Scalar SDK 接入 GitHub 仓库：目标级仓库关联、三分支同步模型与 Secrets 配置详解

Scalar SDK 接入 GitHub 仓库：目标级仓库关联、三分支同步模型与 Secrets 配置详解

【免费下载链接】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

本文基于 Scalar 官方文档 GitHub Repositories 指南，讲清 Scalar SDK 生成平台中“把每个生成目标（target）关联到自己的 GitHub 仓库”这一核心机制：如何在仪表盘中完成关联、构建产物如何流经scalar-generated/scalar-next/ 默认分支 /scalar-merge-conflict的分支模型、自定义代码如何被保留、仓库前置条件，以及destinations配置等价物与仓库 Secrets 的添加方式。读完后你可以独立完成“生成 → 同步 → 评审 → 发布”这条链路中仓库侧的全部配置工作。

关联仓库的定位：同步、评审与历史

在 Scalar 中，每个 SDK 生成目标（target）都可以关联到自己独立的GitHub 仓库——例如 TypeScript SDK 和 Python SDK 可以分别住在两个仓库里。一旦关联完成：

• 每次成功构建都会把生成的 SDK 推送到该仓库；
• 合并 release 拉取请求（pull request）就是触发发布的动作（发布机制本身见 Publishing 概览）；
• 即便暂时不发布，关联本身也有独立价值：它给了每个生成的 SDK 一个“家”、一个评审环节和一份版本历史。

连接仓库的完整步骤

关联是按目标（per target）进行的，整体分三步。

第一步：授权 Scalar GitHub App。首次连接时，GitHub 会要求你安装 Scalar 应用并授予其访问所需仓库的权限。Scalar 只需要对仓库内容做读写（read/write repository contents）以及创建拉取请求的权限。

第二步：选择组织与仓库。打开目标（target），在Git settings面板下选择推送目标 SDK 的Organization与Repository。

第三步：点击 Connect repository。此后每次成功构建都会把生成的 SDK 推送到这个仓库。

同步机制：四分支模型

构建永远不会直接提交到你的默认分支。整个仓库遵循一个由 Scalar 与生成的 workflows 共同管理的分支流程，且全部运行在默认的GITHUB_TOKEN之上——不需要你额外配置任何 token。四个分支各司其职：

同步版本（Synced versions）：目标页面会把每个 SDK 版本与交付它的 PR 和 commit 并列展示，让你能把一个已发布的版本追溯回对应的构建。

注意：关联仓库只控制生成代码去往哪里。若要同时把包推送到包注册中心，还需打开Publish to <registry> on merge开关（或在目标配置里加publish块），详见 Publishing 概览。

从同步流程看，release 请求合并后，默认分支上会运行生成的release-please.yml：切vX.Y.Z标签、更新CHANGELOG.md、创建 GitHub Release，并把发布状态同步回scalar-next；同一 workflow 运行内的publish作业再检出该标签把包发布到注册中心。写入关联仓库的整套发布文件包括：

你的自定义代码会被保留

你可以直接在仓库的scalar-next分支上编辑生成文件。Scalar 在每次再生成时执行三方合并（three-way merge）：对比上一次生成的代码、最新生成的代码与你仓库的当前状态，然后把组合结果落到scalar-next。未被改动的生成文件会干净更新，你的编辑被保留，你新增的文件原样不动（完整机制与冲突处理见 Custom Code 指南）。

• 常规操作下只需照常评审 release PR，只有真正的冲突才需要你的介入；
• 当再生成改到了你编辑过的同一批行（例如你定制的方法签名在 API 中变了），该目标构建会被标记为有冲突，合并被搁置到scalar-merge-conflict分支，你可以在仪表盘冲突视图或 GitHub 的scalar-merge-conflictPR 中解决；
• 官方建议：尽可能把自定义代码放在独立的新文件/路径中——新文件永远不会冲突，比深入编辑生成文件更安全；且自定义代码是按仓库隔离的，每个目标在自己的仓库里维护自己的定制。

仓库前置条件

• scalar-next与默认分支上的分支保护规则必须允许 Scalar 应用和github-actionsbot 推送，或者干脆不设保护。原因是：默认分支只通过合并 release PR 前进，而scalar-next需要从 release workflow 接收每个已发布状态的回写。
• 无需改动任何 Actions 设置：生成的 workflows 自行声明所需权限，且不会创建拉取请求（release PR 由 Scalar 侧管理，workflow 只负责默认分支上的发布动作）。

配置等价物：destinations

从仪表盘关联仓库，等价于在 SDK 配置中设置目标的destinations。你也可以直接在配置里声明：

{ "targets": { "typescript": { "destinations": { "production": { "repo": "acme/acme-typescript", "branch": "main" } } } } }

destinations.production在每个目标上都可以用，而不仅是 CLI 目标（参见 CLI 目标配置 与 Go 目标配置）。一个值得注意的联动细节：Go 目标的模块路径默认就由destinations.production.repo推导——acme/acme-go对应github.com/acme/acme-go；当消费者的 import 路径与推送仓库不一致（ vanity 导入域、子目录模块）时，才需要用goModulePathOverride覆盖。

发布功能对关联仓库是硬依赖：Publishing 概览 明确说明，没有destinations.production的目标不会生成任何 workflows。

添加仓库 Secrets

OIDC trusted publishing 不需要任何 secrets。而token 方式发布（以及 Maven Central 的 GPG 签名）会把凭证作为 secrets 存在 SDK 仓库上；生成的 workflows 按精确名称读取它们，所以名称必须严格一致（例如NPM_TOKEN），每个语言页面列出了各注册中心使用的确切名称。

操作步骤：

1. 在 SDK 仓库的 GitHub 页面进入Settings → Secrets and variables → Actions；
2. 选择New repository secret；
3. 输入 workflow 期望的Name（如NPM_TOKEN）并粘贴值，点击Add secret。

注意：secrets 的作用域是单个仓库。如果从一个仓库发布多个目标，需要把每个注册中心对应的 secret 都加到同一个仓库里。

各注册中心的默认认证方式与所需 secret 速查（摘自 Package Registries 指南）：

其中 OIDC 与 token 是二选一的两种认证方式：OIDC 下publish作业用短时 GitHub 身份令牌向注册中心换取凭证，没有需要创建、存储或轮换的 token；切换为 token 方式时在配置里写authMethod: "access-token"（如"publish": { "npm": { "authMethod": "access-token" } }）。注册 trusted publisher 时注意登记的工作流文件是release-please.yml而非sdk-release.yml（后者只在你手动触发时才需要额外登记）。

解除关联（Unlink）

要停止同步，打开目标，在Danger Zone下使用Unlink。此后构建将不再向 GitHub 推送，直到你重新连接。仓库中已有的代码以及已经发布出去的内容都不会受到影响。

小结：一次完整的构建同步路径

把各环节串起来，一次构建的仓库侧路径是：构建成功 → 推送到scalar-generated→ 三方合并进scalar-next（保留你的自定义代码，冲突则落到scalar-merge-conflict）→ 更新从scalar-next指向默认分支的 release PR → 评审并合并 →release-please.yml切标签、写 changelog、建 Release 并回写scalar-next（若开启了发布，publish作业同时把包发到注册中心）。仓库关联是这条链路的起点，也是自定义代码评审与版本追溯的载体；配合 Publishing 概览、Custom Code 与 Package Registries，即可覆盖从生成到上架注册中心的完整流程。

【免费下载链接】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