• 变更。 在 列出应用安装可访问的仓库、List Branches、List Check Run Annotations、List Check Runs For Commit、List Check Runs For Suite、List Check Suites For Commit、List Commit Files、List Comparison Files、List Namespace Grants、List Namespaces、List Pull Request Files、List Pull Requests、List Repos 和 List Repository Grants 中，与 pageToken 一同传入的 pageSize 现在会应用于该页；后续请求未传入 pageSize 时，沿用之前的每页大小。后续请求的 pageSize 与首次请求不同时，List Commit Files 和 List Comparison Files 不再返回 InvalidArgument (HTTP 400)，其他端点也不再忽略该参数。页面 token 绑定的其他内容，例如代码仓库、筛选条件和 PR 版本，仍须保持一致。

• 变更。 如果 PR 的 head 分支已超前于最新 version 记录的 head，例如某次推送已生效，但 Origin 尚未将其记录为新版本，Merge Pull Request 现在会返回 Aborted (HTTP 409 Conflict)，而非 InvalidArgument (HTTP 400)。这与 expectedHeadSha 过期时的响应相同。两种情况下都不会合并任何内容；请等待 Get Pull Request 在 version.headSha 中返回新的 head 后再重试。

• 破坏性变更。 评论线程和评审的版本引用不再包含 createdAt，仅保留该版本的 number、headSha 和 baseSha。涉及范围包括：List Pull Request Comments、Get Pull Request Comment、Create Pull Request Comment 和 Update Pull Request Comment 中的 thread.version，Update Pull Request Thread 中的 version，List Pull Request Reviews、Create Pull Request Review、Update Pull Request Review 和 Dismiss Pull Request Review 中的 pullRequestVersion，以及 pull_request.comment.created 和 pull_request.review.* 负载中的相同字段。迁移方式：如果你的集成此前从线程或评审版本中读取 createdAt，请改为按 number 匹配，从 Get Pull Request 或记录该版本的 pull_request.* 生命周期负载中的 version 读取。
• 新增。 PR 版本新增 potentialMergeCommit 字段，表示 Origin 对该版本执行的试合并：state 取值为 prepared、merge_conflict 或 unknown；状态为 prepared 时，还会附带合并提交的 sha，以及该合并所基于的基础分支末端提交 baseSha。该字段会出现在 List Pull Requests、Get Pull Request、Create Pull Request、Update Pull Request 和 Merge Pull Request 返回的 version 中，也包含在 pull_request.* 生命周期负载中，因此 webhook 接收方无需调用 Get Git Ref 即可获知合并预览。事件携带的是发出时的值，因此遇到 unknown 时应视为尚未确定，并重新读取该 PR。
• 新增。 Create Installation User Token 可签发安装用户 token，用于代表符合条件的命名空间成员执行操作：POST /v1/origin/app/installations/{installationId}/user_access_tokens。需要应用 JWT，且该安装须已获授 namespace:user_tokens:write。通过 userId 或 userEmail 指定用户；可选的 scopes 和 repositoryIds 用于缩小访问范围。该 token 最长 15 分钟后过期，且不会晚于应用 JWT 失效。
• 新增。 当应用代表用户执行操作时，用户 actor 可包含 performedVia.app，其中带有应用的 id 和可选的 displayName。用户直接执行的操作不含该字段；委托数据不可用时，该字段也可能缺失。参见代表用户执行操作。
• 新增。 List Commits 支持 authorEmails 和 committerEmails 筛选条件，每项最多包含 100 个不重复的电子邮件地址。匹配时忽略大小写和首尾空白；若同时设置两个列表，提交必须同时满足两者。经过筛选的页面可能为空但仍带有 nextPageToken，因此请持续翻页，直到 token 为空。
• 变更。 已取消的检查运行不再覆盖已通过的结果。如果某个运行已处于 completed 状态且结论为 success、neutral 或 skipped，此时再提交结论为 cancelled 的 completed 请求，无论其 externalUpdatedAt 为何值，都会被视为过期而忽略：Post Check Run 和 Batch Upsert Check Runs 会返回 200，并附带已存储的运行及 outcome 值 ignored_stale。如果取消以新的运行尝试或 suite 尝试的形式提交，其优先级会低于已通过的尝试，因此 List Check Runs For Commit、List Check Suites For Commit、List Check Runs For Suite 和 Get Pull Request Mergeability 仍会报告通过。较新的失败结果仍会取代通过结果，取消也仍会覆盖失败或待处理的运行；完整规则请参阅 Attempts and the current attempt。

• 新增。 List Namespaces 列出你可在其中列出仓库的命名空间，按 slug 排序：GET /v1/origin/namespaces。候选范围包括你所在团队的命名空间、你的个人命名空间，以及包含你已获授权仓库的命名空间；其中仅返回你拥有 namespace:repositories:read 权限的命名空间，因此每个 namespace.slug 都可用作 List Repos 的有效 ownerSlug。每个条目的 viewerCanCreateRepositories 表示你在该命名空间中调用 Create Repo 时，能否通过授权校验以及所有者的套餐和设置检查。每页默认返回 30 个命名空间，最多 100 个。需使用 Cherri Code 用户凭据，无需任何作用域，消耗 1 点；使用应用 token、安装令牌或服务账户调用时，将返回 PermissionDenied (HTTP 403) 。

• 变更。 通过 Update Pull Request 重新打开 PR 时，如果 head 在 PR 关闭期间发生了变动，则会记录一个新的 version，并发送 pull_request.head_ref.pushed。此前，PR 会一直保留关闭时的 head，直到该分支再次被推送。新记录的版本带有各自的 headSha、baseSha 和 diff 统计信息，结构与推送时记录的版本相同。已合并的 PR 不受影响。
• 变更。 发送到 Get Commit 或 List Commit Files 的缩写提交 SHA，现在的解析方式与 Get Git Commit 相同：仅在提交对象中匹配。因此，只要某个前缀恰好对应一个提交，即使代码仓库中有 blob 或 tree 使用相同前缀，也能成功解析。9 月 22 日的条目仅提及了 Get Git Commit。Get Blob 和 Get Tag 保持不变。

应用与安装实例

• 变更。 创建安装访问令牌现已明确：token 的有效期最长为 15 分钟，且不会晚于请求该 token 的应用 JWT 的过期时间。请读取响应中的 expiresAt，到期后签发新 token，不要自行假定有效时长。

拉取请求

• 破坏性变更。 Create Pull Request 不再接受 parentPullNumber。携带该字段的请求不会创建 PR，而是返回 InvalidArgument (HTTP 400) 并指明 parent_pull_number。这样，仍在发送该字段的客户端会明确报错，而不会悄无声息地丢失分支栈父级。迁移方式：在集成中所有原先发送 parentPullNumber 的位置，改为发送带有 number 成员的 parentPullRequest。
• 新增。 Delete Pull Request Comment 可按 Origin id 删除 PR 评论：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/pulls/comments/{commentId}。评论作者始终可以删除该评论；其他调用方必须通过 repository:contents:write 拥有代码仓库的写入权限，否则会收到 PermissionDenied (HTTP 403) 。删除线程中的最后一条评论会移除该线程，删除其他评论则保留线程；评论的表情回应和编辑历史会一并删除。id 未知或已被删除时返回 404。需要 repository:pull_requests:reviews:write，消耗 5 点。
• 新增。 PR 响应中新增 stack 对象，包含分支栈的 id 以及该 PR 所基于的父级 parentPullRequest。PR 不属于任何分支栈时不返回该对象；根 PR 的该对象中不含 parentPullRequest。List Pull Requests、获取 PR、Create Pull Request、Update Pull Request 和 合并 PR 均会返回该对象，每个 pull_request.* 负载中也会包含它。推送的 stack 反映的是对应事件发生时的拓扑结构。
• 新增。 Create Pull Request 和 Update Pull Request 支持 parentPullRequest 选择器，可通过 number 或 id 指定分支栈父级，更新时也可通过 clear 将其移除。必须且只能设置一个成员；空选择器、clear: false、设置多个成员以及在创建时使用 clear，均会返回 InvalidArgument (HTTP 400) 。该编辑仅建立关联：不会重写任何分支，且仅在同时发送 base 时才会重新指定 base。更新时会在 base 之后应用该选择器，因此显式指定的父级优先于根据 base 变更推导出的父级。
• 新增。 List Pull Requests 支持 stackId 参数，取值为 stack.id 中返回的分支栈 id。结果按请求的排序方式返回该分支栈的成员，而非按分支栈顺序，因此需根据每个成员的 stack.parentPullRequest 重建分支栈。state 默认仍为 open，如需获取整个分支栈，请传入 state=all。若 id 格式正确但代码仓库中没有对应的分支栈，则返回空列表；其他任何值都会返回 InvalidArgument (HTTP 400) 。
• 新增。 List Pull Requests 支持 headSha 参数，取值为 PR head 的完整 40 或 64 位十六进制 SHA。只要 PR 的任一已记录版本 (无论是当前版本还是已被取代的版本) 的 head 提交与之匹配，该 PR 就会被选中，因此请比较每个结果的 head.sha 以区分这两种情况。格式错误、缩写或未知的 SHA 不会匹配任何结果。

检查运行

• 已弃用。 Batch Upsert Check Runs 响应中的 checkRuns 已弃用，请改用 results[].checkRun。该字段将在未来的版本中移除，目前仍会按相同顺序填充相同的检查运行。迁移方式：读取 results[].checkRun，其中每个已存储的检查运行都与其写入的 outcome 配对。
• 新增。 Post Check Run 返回 outcome，Batch Upsert Check Runs 返回 results[]，按请求顺序为每个提交的检查运行返回一项，每项都将 checkRun 与其对应的 outcome 配对。取值为 created、updated、unchanged 或 ignored_stale。如果提交的 externalUpdatedAt 早于已存储的时间戳，该提交会被忽略；如果提交的值与已存储的值相同，则不会产生任何更改。这两种情况都会返回 200 和已存储的检查运行，且 updatedAt 保持不变，因此只能通过 outcome 区分。
• 变更。 检查运行注释的 message 现可包含 Markdown，Origin 会在 PR 页面的 Checks 标签页以及 Changes 中的内联卡片里渲染这些内容。Post Check Run 和 Batch Upsert Check Runs 均接受此格式，Get Check Run 也会按此格式返回。rawDetails 仍为纯文本。

Git 数据

• 变更。 Get Git Commit 现在仅在缩写 sha 至少包含 5 个十六进制字符时才会解析，且只在提交对象中查找；若没有提交或有多个提交与该缩写匹配，请求将失败。完整 SHA、分支、标签和 HEAD 的解析方式不变。

SSH 证书颁发机构

• 新增。 List SSH Certificate Authorities 按从新到旧的顺序列出所有者在 Git over SSH 中信任的 SSH 证书颁发机构，同时返回 requireCertificates，表示该所有者是否要求使用证书：GET /v1/origin/owners/{ownerSlug}/ssh-certificate-authorities。响应不分页，每个 certificateAuthorities[] 条目包含 id、name、keyType、fingerprint、publicKey 和 createdAt。需要 namespace:settings:read。
• 新增。 Add SSH Certificate Authority 为所有者添加一个受信任的颁发机构并返回该机构：POST /v1/origin/owners/{ownerSlug}/ssh-certificate-authorities。请求体包含必填的 publicKey 和必填的 name。publicKey 为一行 OpenSSH authorized_keys 内容，密钥类型须为 ssh-ed25519、ecdsa-sha2-nistp256、ecdsa-sha2-nistp384、ecdsa-sha2-nistp521，或模数不少于 2048 位的 ssh-rsa；name 最多 255 个字符。传入证书、不受支持的密钥类型或位数不足的 RSA 密钥时，返回 InvalidArgument (HTTP 400) ；传入该所有者已有的密钥时，返回 AlreadyExists (HTTP 409 Conflict) ，此检查仅在该所有者范围内进行，而非针对整个 Origin；所有者不属于团队时，返回 FailedPrecondition (HTTP 400) 。需要持有 namespace:settings:write 的 Cherri Code 用户凭据。
• 新增。 Delete SSH Certificate Authority 从所有者中移除一个颁发机构，并返回 204 No Content：DELETE /v1/origin/owners/{ownerSlug}/ssh-certificate-authorities/{certificateAuthorityId}。该颁发机构签发的所有证书都将失效。所有者要求使用证书时，无法移除其最后一个颁发机构，否则返回 FailedPrecondition (HTTP 400) 。需要持有 namespace:settings:write 的 Cherri Code 用户凭据。
• 新增。 Set SSH Certificate Requirement 设置所有者是否要求使用 SSH 证书：POST /v1/origin/owners/{ownerSlug}/ssh-certificate-authorities:setRequirement。请求体包含必填的布尔值 requireCertificates，响应中返回该所有者的 requireCertificates 设置。启用后，该所有者仓库的 Git over SSH 操作仅接受由其颁发机构签发的证书，用户注册的 SSH 密钥以及通过 HTTPS 使用的用户 API 密钥均会被拒绝。在没有任何颁发机构时启用证书要求，将返回 FailedPrecondition (HTTP 400) ；设置为当前值时请求成功，但不会做任何更改。需要持有 namespace:settings:write 的 Cherri Code 用户凭据。

Webhook

• 新增。 pull_request.comment.reaction.added 和 pull_request.comment.reaction.removed 现为可订阅的 webhook 事件，在 PR 评论上添加或移除回应时投递。二者共用的负载包含 pullRequest 引用、comment 引用 (含其 thread) ，以及 reaction (含其 content 和 reactor) 。添加事件至少投递一次：若回应者重新添加其已有的回应，系统会针对相同的评论、回应者和内容再次投递该事件，因此请按这三者合并去重。移除回应者并未添加的回应时，不会投递任何事件。
• 变更。 pull_request.label.removed 的负载会在已知时包含 actor，即移除该标签的 principal。9 月 19 日的条目曾说明 actor 仅在 pull_request.label.added 中设置；实际上，只要 principal 已知，这两个事件都会设置该字段。

• 新增。 Delete Git Ref 用于删除分支引用：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/git/refs/{ref}。路径以 refs/heads/<branch> 或 heads/<branch> 的形式指定分支，且仅可删除分支引用。分支不存在时返回 404；删除代码仓库的默认分支、受删除规则保护的分支，或内容镜像自其他主机的代码仓库时，均返回 FailedPrecondition (HTTP 400) ；若删除过程中分支的最新提交发生变化，则返回 FailedPrecondition (HTTP 400) 或 Aborted (HTTP 409 Conflict) ，此时请重试，以删除新的最新提交。以被删除分支为 head 的 PR 将被关闭，与通过推送删除分支的效果相同。需要 repository:contents:write 作用域，消耗 5 点。
• 新增。 pull_request.label.added 和 pull_request.label.removed 现为可订阅的 webhook 事件，在为 PR 添加或移除标签时发送。两者共用的负载包含 pullRequest 引用和 label 快照；仅 pull_request.label.added 额外包含 actor，用于标识添加该标签的 principal。删除某个标签定义时，会为每个带有该标签的 PR 分别发送一次 pull_request.label.removed。

• 破坏性变更。 创建应用 现在会强制校验命名空间所有者是否有权向 Origin 写入，这与 创建代码仓库 一贯的前置条件一致。如果目标命名空间的用户所有者未订阅 Pro、Pro Student、Pro+、Ultra 或 Start 方案，或其团队所有者没有有效的付费团队方案、处于隐私模式 (旧版) ，或团队管理员已为其关闭 Origin，请求将返回 FailedPrecondition (HTTP 400) ，而不再像以前那样直接创建应用。该校验针对的是命名空间所有者的资格，而非调用方用户的资格。迁移方式：仅在所有者有权向 Origin 写入的命名空间下创建应用，并在集成中所有默认应用已创建成功的地方处理 FailedPrecondition。
• 变更。 Origin 留给 webhook 接收方响应单次投递的时间由 5 秒延长至 10 秒。该时限涵盖 DNS 解析、建立连接、TLS 握手以及等待响应的时间，且适用于每次尝试；超时的尝试将视为传输错误，并按照 重试 中所述的计划进行重试。

• 破坏性变更。 Get Repo Tarball 生成的归档现在会将仓库目录树包裹在一个名为 {ownerSlug}-{repoName}-{shortSha}/ 的顶层目录中，其中 shortSha 为解析后提交的前 7 位十六进制字符，与 GitHub tarball 端点的目录结构一致。此前，归档条目直接位于 tar 包根目录下，没有外层包裹目录。迁移方式：凡是你的集成从 tar 根目录读取条目的地方，解压时均需去掉一层前导路径组件，例如使用 tar --strip-components=1。
• 破坏性变更。 Get App 现要求在应用所属命名空间上具备 namespace:apps:read 作用域，以取代 app:settings:read (即 9 月 12 日条目中随该端点一同公布的作用域) 。app:settings:read 不再授予任何权限，并已从作用域目录中移除；app:settings:write 保持不变，仍适用于 Update App、Add App Signing Key 和 Revoke App Signing Key。迁移方式：凡是你的集成原先持有 app:settings:read 的地方，改为在应用所属命名空间上持有 namespace:apps:read。
• 新增。 列出应用安装可访问的仓库现支持 filter 参数，可对仓库名称和所有者命名空间进行不区分大小写的子字符串匹配。若值为仅含一个斜杠的 owner/repo 形式，则斜杠两侧会分别与对应字段匹配；首尾空白会被忽略；值为空时不进行筛选。分页令牌会记录其生成时所用的筛选条件，因此请求后续页面时请传入相同的筛选值。
• 变更。 OpenAPI 规范不再为 string 枚举 schema 标注 format: enum。该键并非已注册的 OpenAPI 或 JSON Schema 格式，且与旁边的 enum 列表重复；此外，将其映射为具名类型的代码生成器会生成无法编译的代码。Schema 名称、枚举值以及实际传输的 JSON 均保持不变；请重新生成所有基于该规范构建的客户端，以获得修正后的类型。

• 破坏性变更。 repository.check_run.created 和 repository.check_run.completed 的负载不再包含负载级别的 actor。该字段与所属 check suite 的 principal 重复，而同一负载已通过 checkSuite.actor 和 checkRun.actor 提供了该信息。迁移方式：如果你的集成读取了负载顶层的 actor，请改为读取 checkRun.actor，其值始终与所属 suite 的 actor 相同。
• 破坏性变更。 Grep Contents 的 caseInsensitive 和 wholeWord 仅在 literal 为 true 时生效。正则表达式搜索此前会遵循这两个布尔值，现在则会忽略它们；且仅包含 (?i) 的 query 会返回 InvalidArgument (HTTP 400) 。迁移方式：设置 literal 以继续使用这两个布尔值；如需使用正则表达式搜索，请改为在 query 开头写入 (?i)，并使用 \b 标记单词边界。
• 破坏性变更。 OpenAPI 规范将 Thread 组件 schema 重命名为 CommentThread。该 schema 是 Update Pull Request Thread 的响应 schema，也是 PR 评论中 thread 对象的类型。字段名、路径、operation ID 以及实际传输的 JSON 均保持不变，因此直接读取响应的集成无需修改。迁移方式：重新生成基于该规范构建的客户端，并在生成代码中将所有名为 Thread 的类型重命名。
• 新增。 Add App Installation Repositories 可将仓库添加到现有安装的已选仓库中，并返回更新后的安装：POST /v1/origin/namespaces/{namespaceSlug}/installations/{installationId}/repos。请求体须包含 repoIds 数组，该数组会与当前已选仓库合并；此写入操作不会更改安装的作用域，如果请求中的仓库均已授权，请求会成功返回，但不做任何更改。以下情况均会返回 FailedPrecondition (HTTP 400) ，且不授予任何权限：仓库不在该命名空间内、安装已覆盖命名空间内的全部仓库、安装已被暂停，或安装创建于按安装划分作用域的功能推出之前。需要持有 namespace:installations:write 的 Cherri Code 用户凭据，每次调用消耗 5 点。首次安装仍需命名空间管理员在浏览器中确认同意。
• 新增。 计费的 Git over HTTPS 响应会包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Used 标头，且 X-RateLimit-Resource 为 git。Git 单独计量预算，与速率限制中记为 core 的 REST 预算互不影响。超出预算的 Git 请求会返回 429，并附带 Retry-After 和 X-RateLimit-Reset；不计量的请求则不包含速率限制标头。
• 变更。 Upsert Repository Grant 和 Upsert Namespace Grant 除已支持的组织群组外，现在还接受资源所有者所在团队自有的 group principal。即使团队未关联到组织，也可以向该团队自己的群组授权；而属于其他团队的群组仍会返回 FailedPrecondition (HTTP 400) 。各类 principal 详见 Grants 页面。

• 破坏性变更。 Create Repo 现在需要 namespace:repositories:create，以取代 namespace:new_repository:write；后者不再授予任何权限，并已从作用域目录中移除。迁移方法：在集成原先请求 namespace:new_repository:write 的所有位置，改为在 Cherri Code 用户凭据上请求 namespace:repositories:create。
• 新增。 Get Pull Request Mergeability 返回 PR 是否可以合并；若不可合并，则返回阻止合并的类型化条件：GET /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/mergeability。verdict 为 mergeable 或 blocked，blockers 中的每个条目都包含 kind、便于阅读的 message，以及该条目在 evaluatedPullRequests 中所属的 PR，因此分支栈中某个 PR 的决定涵盖从分支栈根部到该 PR 的所有 PR。可选的 expectedHeadSha 校验会在 head 已移动时返回 Aborted (HTTP 409 Conflict) ；对于镜像代码仓库或包含超过 200 个 PR 的分支栈，则返回 FailedPrecondition (HTTP 400) 。该操作以预览版发布，在 OpenAPI 规范中标记为 x-cursor-visibility: PREVIEW，因此解码其响应时应容忍未知字段和未知枚举值，并将无法识别的 verdict 视为 blocked。需要 repository:pull_requests:read，消耗 10 点。
• 新增。 Grep Contents 在指定引用处搜索代码仓库文件的文本，并返回匹配的行：POST /v1/origin/repos/{ownerSlug}/{repoName}:grep。请求体包含必填的 query (除非设置了 literal，否则按正则表达式解析) ，以及 ref、caseInsensitive、wholeWord、contextBefore 和 contextAfter (大于 10 的值按 10 处理) 、filterPath、includes 和 excludes glob 列表 (各最多 20 个条目) ，以及 maxResults (默认值和最大值均为 1000) 。每个返回条目对应一行，仅当 limitHit 为 false 时响应才完整；不支持分页。需要 repository:contents:read，消耗 5 点。
• 新增。 检查运行的 status 新增第四个值 rerequested，List Check Runs For Commit 也支持将其用作 status 筛选条件。该值表示某个已完成的运行已被请求重新运行，但所属应用尚未响应，因此应将其视为待处理，并按 queued 的方式显示。该值会出现在 Get Check Run、List Check Runs For Suite、List Check Runs For Commit 和 Rerequest Check Run 中。该值只能由 Origin 设置：携带该值的 Post Check Run 或 Batch Upsert Check Runs 请求会返回 InvalidArgument (HTTP 400) 。
• 新增。 List Pull Requests 支持 sortBy，取值为 created (按创建顺序，默认值) 或 updated (按最后更新时间) 。direction 决定按 sortBy 排序的方向，默认值仍为 desc；分页 token 会记录其生成时所用的排序方式，因此在另一种排序方式下重用该 token 会被拒绝。
• 新增。 List Pull Requests 支持 state=merged，仅列出已合并的 PR。closed 仍涵盖所有非打开状态的 PR (包括已合并的 PR) ，因此现有调用方获得的结果不变。
• 变更。 Rerequest Check Run 会将该 run 的 status 设为 rerequested，取代 9 月 11 日说明中“该调用从不更改 run 自身的 status 或 conclusion”的描述。该 run 的 conclusion 和计时信息仍对应已被取代的那次尝试，因此请仅在 status 为 completed 时读取 conclusion。在所属应用作出响应之前，该 run 在 List Check Runs For Suite 和 List Check Runs For Commit 中仍显示为待处理；应用响应后，还会清除 rerequestedAt 并存储所提交的状态。
• 变更。 repository.check_run.rerequested 负载中的 checkRun.status 为 rerequested，而非 completed；checkRun.conclusion 和计时信息仍对应已被取代的那次尝试。迁移方式与该端点相同：根据 checkRun.status 分支处理，仅在其为 completed 时读取 checkRun.conclusion。

拉取请求

• 破坏性变更。 Create Pull Request 和 Update Pull Request 现在会拒绝未指向现有分支的 base。如果传入提交 SHA、标签名或不存在的分支，将返回 InvalidArgument (HTTP 400) ，并在错误中给出源站所查找的完全限定引用；此前，同样的请求会直接创建 PR 或更改其目标分支。但这类 PR 始终无法生成合并引用，导致 CI 一直收不到该引用，PR 也无法合并。迁移方法：传入分支名称，可使用简写形式 main 或完全限定形式 refs/heads/main；对于 base 为提交 SHA 或标签的现有 PR，请重新设置其目标分支。

应用

• 新增。 创建应用 用于注册归属于某个命名空间的应用：POST /v1/origin/namespaces/{namespaceSlug}/apps。请求体须包含必填的 displayName 和 publicKey (即应用为其 JWT 签名所用的 PEM SPKI Ed25519 公钥) ，另可选填 webhookUrl、events、description、websiteUrl、installationRedirectUris 和 defaultScopes。新创建的应用默认为私有；若 webhook URL、事件类型、重定向 URI 或作用域无效，将返回 InvalidArgument (HTTP 400) 。需使用具备 namespace:apps:create 的 Cherri Code 用户凭据，消耗 10 点。
• 新增。 List Namespace Apps 按从新到旧的顺序列出命名空间拥有的应用：GET /v1/origin/namespaces/{namespaceSlug}/apps。条目仅包含展示用元数据，即 id、displayName 和 description；如需读取某个应用的 webhook 配置，请使用 Get App。需要 namespace:apps:read，消耗 1 点。
• 新增。 Get App 按 id 返回单个应用的完整配置：GET /v1/origin/apps/{appId}。该操作供发布者进行管理性读取；Get Authenticated App 仍用于应用凭自身 JWT 读取自身信息。需要 app:settings:read，消耗 1 点。
• 新增。 Update App 用于修改应用设置：PATCH /v1/origin/apps/{appId}。displayName、webhookUrl、description 和 websiteUrl 为普通字段；events、installationRedirectUris 和 defaultScopes 则为整体替换包装器，会替换整个列表。省略的字段保持不变；未设置任何字段的请求将返回 InvalidArgument (HTTP 400) ；将 webhookUrl 设为空字符串会禁用投递，并永久取消该应用所有待处理的投递。需要 app:settings:write，消耗 5 点。
• 新增。 Add App Signing Key 为应用额外注册一个 Ed25519 公钥：POST /v1/origin/apps/{appId}/signing_keys。响应中包含用作 JWT 密钥 ID 的 kid，其值为该密钥 SPKI DER 编码的 SHA-256 摘要，采用 base64url 编码。若密钥已注册，将返回 AlreadyExists (HTTP 409 Conflict) ；若超出应用的活跃密钥数量上限，将返回 FailedPrecondition (HTTP 400) 。需要 app:settings:write，消耗 5 点。
• 新增。 Revoke App Signing Key 用于停用签名密钥，成功时返回 204 No Content：DELETE /v1/origin/apps/{appId}/signing_keys/{kid}。使用已撤销密钥签名的应用 JWT 将无法再通过认证；撤销最后一个活跃密钥将返回 FailedPrecondition (HTTP 400) 。需要 app:settings:write，消耗 5 点。
• 新增。 应用响应现包含 namespaceSlug (拥有该应用的命名空间的 slug) ，以及 description、websiteUrl 和 defaultScopes。以下操作会返回这些字段：Get Authenticated App、Get App、创建应用 和 Update App。

授权

• 新增。 List Repository Grants 列出在代码仓库上被直接授予权限的用户、群组和所属团队群组：GET /v1/origin/repos/{ownerSlug}/{repoName}/grants。结果不包含从代码仓库所有者继承的权限，且无法解析的 principal 会被略去，因此单页返回的授权数可能少于 pageSize。需要 repository:settings:read，消耗 1 点。
• 新增。 Upsert Repository Grant 设置某个 principal 在代码仓库上被直接授予的权限：POST /v1/origin/repos/{ownerSlug}/{repoName}/grants。请求体须指定 user、group 或 teamGroup 中的恰好一项，并提供 permission，取值为 read、write 或 admin；传入 custom 会返回 InvalidArgument (HTTP 400) ，若 principal 不属于所有者所在的团队或组织，则返回 FailedPrecondition (HTTP 400) 。重复授予该 principal 已持有的权限会直接成功，不做任何更改。需要 repository:settings:write，消耗 5 点。
• 新增。 Delete Repository Grant 移除某个 principal 在代码仓库上被直接授予的权限，并返回 204 No Content：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/grants。从所有者继承的权限不受影响，因此所属团队群组会回退到其在所有者级别的默认权限；移除该 principal 未被直接授予的权限会直接成功，不做任何更改。需要 repository:settings:write，消耗 5 点。
• 新增。 List Namespace Grants 列出已获得某个所有者访问权限的对象：GET /v1/origin/owners/{ownerSlug}/grants。每条授权都注明其对该所有者下所有仓库赋予的权限，admin 授权排在最前，针对单个仓库的授权不包含在内。需要 namespace:settings:read，消耗 1 点。
• 新增。 Upsert Namespace Grant 设置某个 principal 在所有者上被直接授予的权限：POST /v1/origin/owners/{ownerSlug}/grants。permission 可取 PERMISSION_READ、PERMISSION_CONTRIBUTOR、PERMISSION_WRITE 或 PERMISSION_ADMIN，传入 PERMISSION_CUSTOM 会返回 InvalidArgument (HTTP 400) 。若 principal 不属于所属团队或其组织，或写入后所有者将不再有任何 admin，则返回 FailedPrecondition (HTTP 400) 。需要 namespace:settings:write，消耗 5 点。
• 新增。 Delete Namespace Grant 移除某个 principal 在所有者上被直接授予的权限，并返回 204 No Content：DELETE /v1/origin/owners/{ownerSlug}/grants。针对单个仓库的授权不受影响；若移除后所有者将不再有任何 admin，则返回 FailedPrecondition (HTTP 400) 。需要 namespace:settings:write，消耗 5 点。

安装

• 新增。 安装对象新增 suspendedAt 和 deletedAt 字段：suspendedAt 在安装被暂停时设置，处于活跃状态时省略；deletedAt 仅出现在 installation.deleted webhook 快照中。Get App Installation 和 List App Installations 均会返回这些字段。
• 新增。 五种 installation.* 负载均包含 installation.appId，其值与负载自身的 app.id 相同；installation.created 和 installation.updated 还包含 installation.updatedAt。Get App Installation 返回的安装对象中的每个字段，均以相同的名称和类型出现在快照中，因此同一个解码器即可解析两者。

检查运行

• 破坏性变更。 repository.check_run.rerequested 负载不再包含顶层的 rerequestedBy。请求重新运行的 principal 改为放在嵌入的检查运行中，字段为 checkRun.rerequestedBy。此变更取代了 9 月 10 日的说明 (即负载会在代码仓库、suite 和 run 之外附带请求者) 。迁移方式：凡是 receiver 读取负载自身 rerequestedBy 的地方，均改为读取 checkRun.rerequestedBy。
• 新增。 Rerequest Check Run 用于请求上报某个检查运行的应用重新运行该检查：POST /v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}/rerequest，请求体为空。该 run 必须处于 completed 状态，必须带有 isRerequestable，必须是其 key 的当前尝试，且必须位于某个开放 PR 的当前 head 上；不满足任一条件均返回 FailedPrecondition (HTTP 400) 。若已有未完成的请求，再次请求将返回 AlreadyExists (HTTP 409 Conflict) 。该调用不会更改 run 自身的 status 或 conclusion。任何持有 repository:contents:write 的 principal 都可以重新请求任何可重新请求的 run，无论其由哪个应用上报。每次调用消耗 5 点。
• 新增。 检查运行新增 rerequestedBy 字段，表示请求重新运行的 principal。只要设置了 rerequestedAt，该字段就会存在，并随其一同清除。以下接口会返回该字段：获取检查运行、List Check Runs For Suite、List Check Runs For Commit、Post Check Run、Batch Upsert Check Runs 和 Rerequest Check Run。
• 变更。 rerequestedAt 现在表示一个尚未处理的重新请求，而不再是一次性时间戳。当所属应用针对同一 head SHA 和 key 提交新的 run 作为响应时，Origin 会清除该字段。应用既可以使用新的 externalId 创建新的 run，也可以在相同的 externalId 下更新被重新请求的 run。清除后，该 run 可再次被重新请求。此变更取代了 9 月 10 日关于检查运行最多只能被重新请求一次的说明。因此，receiver 可能会针对同一个 run 收到多个 repository.check_run.rerequested 事件；请继续按事件 id 对重新投递进行去重。
• 变更。 被重新请求的检查运行会保留在 List Check Runs For Suite 和 List Check Runs For Commit 中，并显示为待处理：rerequestedAt 已设置，已被取代的 status 和 conclusion 保持不变。而此前，它会在应用响应之前从这两个列表中消失。必需检查现在会以待处理检查 (而非缺失检查) 的身份阻止合并。此变更取代了 9 月 10 日关于该 run 在新尝试到达前会从列表中消失的说明。

仓库

• 新增。 Update Repo 用于写入代码仓库设置：PATCH /v1/origin/repos/{ownerSlug}/{repoName}。请求体接受可选的 defaultBranch、allowMergeCommit、allowSquashMerge、deleteBranchOnMerge 和 visibility 字段，省略的字段保持不变。allowMergeCommit 和 allowSquashMerge 必须同时发送，且至少有一个为 true；对于从上游源拉取内容的代码仓库，设置 defaultBranch 和 deleteBranchOnMerge 会返回 FailedPrecondition (HTTP 400) ；未设置任何内容的请求会返回 InvalidArgument (HTTP 400) 。各字段组按固定顺序应用，而非以原子方式应用，因此某一组被拒绝时，排在它之前的组仍会生效。需要 repository:settings:write，消耗 5 点。
• 新增。 转换代码仓库镜像 用于发起镜像方向变更，并返回跟踪该变更的作业：POST /v1/origin/repos/{ownerSlug}/{repoName}/mirror:transition。请求体须包含必填的 transition，取值为 initial_to_inbound、inbound_to_outbound 或 outbound_to_inbound；作业运行期间，代码仓库的镜像状态为转换中。如果代码仓库不处于该转换要求的起始状态，或已有活跃作业，则返回 FailedPrecondition (HTTP 400) 。需要 Cherri Code 用户凭据具备 repository:mirror:write，且该用户还须在镜像的上游源上拥有该代码仓库的管理权限，消耗 10 点。
• 新增。 强制代码仓库镜像切换 用于将代码仓库切换到其上游源，且不回推分叉的状态：POST /v1/origin/repos/{ownerSlug}/{repoName}/mirror:forceCutover，请求体为空。上游源将按当前状态直接作为唯一可信来源，仅存在于 Origin 上的 ref 会先生成快照再被丢弃。仅适用于处于 outbound 状态的代码仓库，或卡在出站到入站转换中、且活跃作业报告 requires_attention 的代码仓库，此时强制切换会取代该作业。需要 repository:mirror:write，消耗 10 点。
• 新增。 分离代码仓库镜像 用于将镜像代码仓库与其上游源永久断开，并返回 204 No Content：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/mirror。代码仓库会保留原有内容并转为原生代码仓库，双向同步随即停止，镜像的部署凭据也会被删除。对已分离的代码仓库再次执行分离会直接成功，不产生任何影响；从未配置过镜像的代码仓库则返回 FailedPrecondition (HTTP 400) 。需要 repository:mirror:delete，消耗 5 点。
• 新增。 Get Mirror Transition Job 按 id 返回单个转换作业：GET /v1/origin/repos/{ownerSlug}/{repoName}/mirror/transition-jobs/{jobId}。作业会报告其 transition、status (取值为 queued、running、succeeded、failed_rolled_back、requires_attention 或 superseded) 、attemptCount，失败后还会报告 lastErrorCode 和 lastErrorMessage。phase 字符串仅用于展示，其取值会随转换流程的演进而增加，因此请轮询 status 来判断是否完成，而不要依据 phase 进行匹配。需要 repository:metadata:read，消耗 1 点。
• 新增。 获取活跃的镜像转换作业 返回代码仓库正在进行的转换作业及最近一个已结束的作业：GET /v1/origin/repos/{ownerSlug}/{repoName}/mirror/transition-jobs:active。activeJob 和 lastJob 均为可选，因此从未进行过转换的代码仓库会返回空对象；要区分已完成的转换与从未运行的转换，需轮询至 activeJob 消失，再读取 lastJob。需要 repository:metadata:read，消耗 1 点。
• 变更。 镜像状态端点参考文档已迁移至 Origin 迁移 API。其 HTTP 合约保持不变，原有的源站 API 锚点会跳转至新的参考文档。

• 新增。 合并 PR 支持可选参数 mergeMethod，取值为 merge 或 squash，用于指定 PR 以合并提交还是单个 squash 提交的方式合入。若代码仓库不允许所选方法，请求会被拒绝并返回 FailedPrecondition (HTTP 400) ；其他任何值 (包括 rebase) 会被拒绝并返回 InvalidArgument (HTTP 400) 。省略该参数则沿用原有行为：代码仓库允许时使用合并提交，否则使用 squash；若基础分支要求线性历史，则使用 squash。
• 新增。 代码仓库负载新增 visibility (取值为 internal 或 private) ，以及布尔字段 allowMergeCommit、allowSquashMerge 和 deleteBranchOnMerge。这四个字段均为只读，由 Get Repo、创建代码仓库、List Repos 和 列出应用安装可访问的仓库 返回。
• 新增。 检查运行新增 isRerequestable (表示上报应用声明该运行可重新运行) 和 rerequestedAt (重新请求的时间戳) 。可在 Post Check Run 和 Batch Upsert Check Runs 中传入 isRerequestable；这两个字段会在上述接口以及 获取检查运行、List Check Runs For Suite 和 List Check Runs For Commit 中返回。一旦将运行声明为可重新请求，你的应用就必须响应每次重新请求，针对相同的 head SHA 和 key 提交新的运行。
• 新增。 已完成的检查运行被重新请求时，会投递 repository.check_run.rerequested 事件，且仅发送给拥有该运行的应用，而不会发送给代码仓库的所有订阅者。其负载包含代码仓库、check suite、已标记的检查运行以及 rerequestedBy，但不含 PR 上下文，因此请通过 checkRun.sha 查找对应的 PR。订阅该事件需要 repository:checks:read 权限。每个检查运行最多只会被重新请求一次，因此请根据事件 id 对重复投递进行去重。
• 新增。 OpenAPI 规范中的每个 webhook 负载 schema 都带有 x-origin-webhook-events 扩展，列出投递该负载的事件，并附带一个精选示例负载作为该 schema 的 example。新增的事件负载参考文档基于这些 schema 生成，介绍每个负载的字段和示例负载，布局与端点参考一致。
• 变更。 被重新请求的检查运行会从 List Check Runs For Suite 和 List Check Runs For Commit 的结果中移除，直到拥有它的应用提交新的尝试，或以更新的 externalUpdatedAt 刷新现有运行。因此，在重新请求尚未处理期间，必需检查会显示为缺失，并阻止合并。如需读取被排除的运行，可通过其 id 调用 获取检查运行。

• 破坏性变更。 在 Create Pull Request Comment 和 Create Pull Request Review 中，若 inline 锚点的行范围超出文件末尾，请求将被拒绝并返回 InvalidArgument (HTTP 400) 。该范围仍不限于 diff 的 hunk 之内，校验时以锚定一侧的文件为准：left 读取 base 提交中的文件，right 读取 head 提交中的文件；错误信息会注明该文件的行数。对于评审，只要有一个锚点超出范围，整个请求即告失败，且不会发布任何内容。迁移：写入前，将 inline.startLine 和 inline.endLine 限制在锚定一侧文件的行数以内；若锚点位于 diff 的 hunk 之外，可通过 Get Contents 获取该行数。

• 新增。 Create Git Ref 用于在现有提交上创建分支：POST /v1/origin/repos/{ownerSlug}/{repoName}/git/refs。参数 ref 的格式为 refs/heads/<branch> 或 heads/<branch>，sha 为代码仓库中某个提交的完整十六进制 SHA；标签及其他引用命名空间会返回 InvalidArgument (HTTP 400) 。如果要创建的分支已指向 sha，则返回现有引用；如果该分支已存在但指向其他提交，则返回 AlreadyExists (HTTP 409 Conflict) 。需要 repository:contents:write 作用域，消耗 5 点。
• 新增。 Create Commit From Files 用于将内联文件更改提交到分支，并将分支推进到新提交：POST /v1/origin/repos/{ownerSlug}/{repoName}/git/commits:createFromFiles。每个 files[] 条目必须在 content (需同时指定 encoding 为 utf-8 或 base64，mode 为 file、executable 或 symlink) 和 delete 中设置且仅设置一项；expectedHeadSha 必须与分支末端提交一致，该提交将作为新提交的父提交。响应返回 sha、treeSha 和 previousHeadSha。单个请求最多包含 1,000 个文件更改，单个文件不超过 8 MiB，内容总大小不超过 32 MiB。需要 repository:contents:write 作用域，消耗 10 点。
• 变更。 Webhook 投递失败后的重试次数由六次增加到七次，首次重试时间由失败后 30 秒提前至 5 秒。完整的重试间隔依次为 5 秒、30 秒、1 分钟、2 分钟、4 分钟和 8 分钟，因此如果接收端全程不可用，将在大致相同的 16 分钟窗口内多收到一次 POST。请像对其他投递一样，基于 webhook-id 对这次额外尝试进行去重。

• 破坏性变更。 应用元数据不再包含 slug。该字段已从以下位置移除：Get Authenticated App 响应；check、PR、评审和评论操作返回的所有应用 actor (actor.app、author.app 和 dismissal.dismissedBy.app) ；五个 installation.* webhook 负载中的 app 对象；以及 Ping Webhook 负载。此变更取代了 9 月 2 日说明中“应用 actor 除 id 和 slug 外还包含 displayName”的描述。此前，应用 actor 必定包含 slug；现在仅包含 id 和可选的 displayName。迁移方法：凡是集成中读取 slug 的地方，改为通过 id 引用应用，并使用 displayName 作为其显示名称。
• 新增。 List Pull Request Comments 支持可选的 threadIds 查询参数，可将结果限定为指定线程中的评论。借此即可读取单个线程，而无需分页遍历 PR 的全部评论历史。重复项会被忽略，因此 20 个的上限按去重后的 ID 计算；列表超出上限或包含空 ID 时返回 InvalidArgument (HTTP 400) 。页面 token 会嵌入其生成时对应的集合，因此筛选条件变化后需重新开始分页。
• 变更。 List Pull Requests 的 author 筛选器除原有的 user_…、app_… 和 sa_… actor ID 外，现在还支持用户的完整电子邮件地址，匹配时不区分大小写。若电子邮件无法对应到唯一用户，将返回空列表而非错误；此前传入电子邮件会返回 InvalidArgument (HTTP 400) 。应用和服务账户没有电子邮件身份，因此只能通过这种方式筛选用户作者，且这些响应返回的身份标识仍为 actor ID。

• 新增。 List Check Runs For Commit 支持可选的 checkName 和 status 查询参数。checkName 按检查运行的 name 精确匹配；status 可取 queued、in_progress 或 completed，传入其他值将返回 InvalidArgument (HTTP 400) 。两个筛选条件均在按最新尝试合并之后生效，因此 run 以其最新尝试的状态参与匹配，筛选也不会让已被取代的尝试重新出现。页面 token 会嵌入签发时所用的筛选条件，因此更改筛选条件后请重新开始分页。
• 新增。 List Pull Request Comments 支持可选的 since 和 until 查询参数，用于限定评论创建时间的范围 (含边界) ，格式为 RFC 3339 时间戳，例如 2026-08-01T00:00:00Z。时间戳格式错误时返回 InvalidArgument (HTTP 400) 。页面 token 会嵌入签发时所用的边界，因此更改边界后请重新开始分页。可使用 since 跟踪新评论，无需重新分页遍历 PR 的全部评论历史。
• 变更。 在已发布的 OpenAPI 规范中，若某个操作所需的作用域由凭据本身提供，而非来自安装授权，则其 x-origin-scopes 扩展会标记为 ambient: true。共有九个操作带有此标记，包括 Get Authenticated App、Create Installation Access Token 和 List App Installation Repositories。作用域字符串仍保留在扩展中，因此 403 响应中依然会列出它们，请求处理方式也保持不变。读取该标记即可区分两类操作：只需完成认证即可调用的操作，以及需要在安装时获批作用域的操作。

• 破坏性变更。 List Check Suites For Commit、List Check Runs For Commit 和 List Check Runs For Suite 现在仅返回每项检查的最新一次尝试，不再返回已被取代的尝试，与合并门禁及产品 CI 视图此前的显示保持一致。suite 按上报 actor 和 suite key 折叠为最新一次尝试，run 则在 suite 内按 run key 折叠为最新一次尝试，因此失败的 run 与其重试成功的 run 不会再同时出现。totalSize 和分页 token 均基于折叠后的集合计数。迁移方式：通过 Get Check Run 或 Get Check Suite 按 id 读取已被取代的尝试，这两个接口仍可访问所有已存储的尝试。
• 新增。 Create Pull Request Comment 支持 file 锚点，可在 PR 版本的 diff 中针对整个文件发起评论线程。该锚点仅包含 file.path：Origin 会根据文件的变更类型推断 side (已删除文件使用 base 版本，其他情况使用 head 版本) ，并通过 thread.side 返回。对于删除，请传入被删除的路径；对于其他变更，请传入 head 路径。若路径不在 diff 中，或传入重命名文件在重命名前的源路径，将返回 InvalidArgument (HTTP 400) 。file、inline 和 threadId 三者互斥。Create Pull Request Review 也支持相同的锚点，字段为 comments[].file。
• 新增。 公开的用户 actor 现在除 id 和 email 外，还包含 displayName 和 handle。displayName 由账户的名字和姓氏以空格连接而成，与产品中显示的名称一致；若账户未设置姓名，则省略该字段。handle 是已认领的配置文件账号名，不含 @ 前缀，仅在该配置文件公开可见时提供。凡是出现用户 actor 的位置都会包含这两个字段，包括 PR 和评论的作者、检查运行和 suite 的 actor、评审驳回、请求的评审者、安装的 installedBy，以及相应的 webhook 负载。安装回执包含 displayName，但始终不包含 handle。
• 新增。 公开的应用 actor 现在除 id 和 slug 外，还包含应用注册时的 displayName；五种 installation.* webhook 负载中的 app 对象也包含该字段。若无法解析应用，或该 actor 为 Cherri Code 的第一方托管 actor，则省略该字段。
• 变更。 请求 :write 作用域时会同时授予对应的 :read 作用域，例如请求 repository:labels:write 的安装也会获得 repository:labels:read。该规则适用于安装应用、预览安装以及安装访问令牌缩减作用域的场景；现有的仅写凭据现在也可执行对应的读取操作。读取作用域仍不会授予写入权限。

• 新增。 删除代码仓库时会投递 repository.deleted，无论是在产品中删除原生或出站代码仓库，还是停止入站镜像的同步。负载中携带的是 repository 引用和 deletedAt，而非快照，因为已删除的代码仓库无法再通过 API 解析。订阅此事件需要 repository:metadata:read。与 repository.pushed 不同，从 GitHub 镜像的代码仓库也会投递此事件，因为停止同步只会删除 Cherri Code 端的代码仓库，GitHub 不会为此发送任何通知。对已删除的代码仓库再次执行删除不会触发任何事件。
• 新增。 代码仓库的默认分支发生变化时会投递 repository.metadata.updated，涵盖通过设置和 API 写入的变更、入站镜像跟随上游重命名，以及首次推送时的主干协调过程。负载携带写入后的完整 repository 快照，既不包含差异，也不包含执行更新的操作者，因此如需了解具体变更，请比较前后快照或重新获取代码仓库。订阅此事件需要 repository:metadata:read。
• 新增。 被请求的审阅人用户除 id 外还会携带 email。该字段出现在 List Pull Request Requested Reviewers 和 Request Pull Request Reviewers 中，以及 pull_request.reviewer.added、pull_request.reviewer.removed 和 pull_request.reviewer.rerequested webhook 的 reviewer.user 条目中。其值为账户的电子邮件地址，若账户未设置电子邮件地址则为空。此前这些位置仅通过 id 标识用户。
• 变更。 REST 响应现在会保留取默认值的字段，不再将其省略，因此值为 false 的布尔值、值为 0 的数字、空字符串和空数组都会出现在每个响应体中。通过 Get Pull Request 获取的非草稿 PR 会将 draft 返回为 false，而不是省略该字段；空列表会返回 []，而不是什么都不返回。契约中标记为可选的字段 (如 submitted_at 和 dismissal) 在未设置时仍不会出现。如果你的集成曾将缺失的键视为默认值，请改为直接读取该值。这与 webhook 负载一贯的序列化方式保持一致。
• 变更。 已发布的 OpenAPI specification 中每个操作都带有唯一的 operationId。若一个操作对应两种 URL 形式，第二种形式会添加 _2 后缀：GET …/tarball/{ref} 对应 OriginService_GetRepoTarball_2，GET …/git/matching-refs 对应 OriginService_ListMatchingGitRefs_2。两种 URL 形式及其请求处理方式均保持不变，因此请重新生成基于该规范构建的客户端，以获取重命名后的方法。
• 变更。 所有者命名空间被重命名时也会投递 installation.updated，该命名空间下仍保留的每个安装各投递一次。该事件携带新的命名空间 slug，以及该安装当前的作用域和代码仓库选择。

• 变更。 已发布的 OpenAPI 规范中，每个操作都带有 x-origin-scopes 扩展，用于指明该操作所需的作用域及其接受的凭据。scopes 存放所需的作用域，tokenTypes 存放可接受的凭据类型：app 表示应用 JWT，installation 表示安装访问令牌，user 表示用户凭据。操作不接受的凭据类型不会出现在 tokenTypes 中；获取速率限制是唯一无需作用域的操作。此前 Create Label、Update Label 和 Delete Label 在描述中注明的作用域说明，现也已由该扩展取代。授权机制未作变动；该扩展只是公开了 Origin 原本就在强制执行的作用域。

• 新增。 List Pull Request Requested Reviewers 返回某个 PR 上尚未完成评审的用户和群组：GET /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/requested_reviewers。直接请求会在该用户提交评审后清除；群组请求会在该群组的任一当前成员提交评审后清除；未提交的草稿评审不会清除请求，请求仍处于待处理状态。审阅人以 id 形式返回，读取需要 repository:pull_requests:reviews:read。
• 新增。 Request Pull Request Reviewers 向用户和群组发起评审请求，并返回已请求的审阅人：POST /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/requested_reviewers。可通过 public user_… id、邮箱、grp_… id 或群组 slug 指定每位审阅人；不支持按显示名称解析。标识符未知或有歧义时返回 InvalidArgument (HTTP 400) ，审阅人不在该代码仓库的候选范围内时返回 PermissionDenied (HTTP 403) 。对已请求的审阅人再次发起请求会刷新该请求，因此已提交评审的审阅人会重新显示为待处理。需要 repository:pull_requests:reviews:write。
• 新增。 Remove Pull Request Requested Reviewers 移除未完成的评审请求，返回 204 及空响应体：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/requested_reviewers。移除当前未被请求的审阅人不会产生任何效果；审阅人离开代码仓库的候选列表后，其稳定的 public id 仍可解析，因此仍可清除过期的请求。需要 repository:pull_requests:reviews:write。
• 新增。 Update Pull Request Thread 将 PR 评论线程标记为已解决或重新打开，并返回其更新后的状态：PATCH /v1/origin/repos/{ownerSlug}/{repoName}/pulls/threads/{threadId}。将 resolved 设为 true 表示解决，设为 false 表示重新打开。两种操作均为幂等；回复已解决的线程不会将其重新打开；线程属于其他代码仓库时返回 404。需要 repository:pull_requests:reviews:write。
• 新增。 PR 评论现在包含完整的线程信息，而不再仅有线程 id。thread 新增了所针对的 version 及其 head 和 base SHA、线程 diff 锚点的 path、side、startLine 和 endLine、resolvedAt，以及线程自身的 createdAt 和 updatedAt。由 List Pull Request Comments、Get Pull Request Comment 和 Update Pull Request Comment 返回。thread.id 保持不变，因此按其对评论分组的做法仍然有效。
• 新增。 Create Pull Request Comment 支持 inline 锚点 (由 path、side、startLine 和可选的 endLine 组成) ，用于在某个 PR 版本的 diff 上创建锚定到行的线程；还支持 versionNumber，用于指定所针对的版本，默认为调用时的最新版本。path 必须属于该版本的 diff，且位于该文件有内容的一侧；修改的文件中任意一行均可作为锚点，而不仅限于 diff hunk 内的行。锚点无效时返回 InvalidArgument (HTTP 400) ，而不会回退为普通讨论评论。inline 与 threadId 互斥，threadId 与 versionNumber 也互斥。
• 新增。 Create Pull Request Review 现支持 comments 数组 (每个请求最多 50 条) ，可在一次原子调用中同时发布评审及其评论。每个条目包含 body，以及与 Create Pull Request Comment 相同的目标：针对所审核版本 diff 的 inline 锚点、用于回复的 threadId，或两者均不提供，以新建一个常规讨论线程。所有锚点都会在写入任何内容之前完成校验，因此只要有一个锚点无效，整个请求就会以 InvalidArgument (HTTP 400) 失败，且不会发布任何内容。该操作不支持幂等键，因此如遇结果不明确的失败，请先调用 List Pull Request Reviews 确认，再决定是否重试。未包含 comments 的请求，行为与之前保持一致。
• 新增。 pull_request.comment.created 现在会在开启线程的首条评论中附带该线程的 diff 锚点，接收方无需额外读取即可还原该线程。comment.thread 包含评论所针对的 version、path、side、startLine 和 endLine；回复仅携带 comment.thread.id，且该事件不包含解决状态。通过 Create Pull Request Review 随评审提交的评论，在评审提交前不会触发任何事件；评审提交后，每条评论会各自触发一个事件。

• 新增。 Get Repo Tarball 用于下载仓库树的 gzip 压缩 tar 包：GET /v1/origin/repos/{ownerSlug}/{repoName}/tarball/{ref}。对某个已解析提交的首次请求会以 application/gzip 流式返回响应体；之后对同一提交的请求会返回 302，并在 Location 中提供签名下载 URL，有效期 15 分钟。归档条目直接位于 tar 包根目录，没有外层包装目录；空仓库会返回 ABORTED (HTTP 409 Conflict) ；下载归档需要 repository:contents:read。
• 新增。 List Comparison Files 列出比较中发生变更的文件，即 head 相对于 base 与 head 合并基准的差异：GET /v1/origin/repos/{ownerSlug}/{repoName}/compare/{basehead}/files。结果分页返回，默认每页 30 个文件，最多 100 个，每个文件的结构与 List Commit Files 的返回结果一致。identical 或 behind 比较返回空列表，历史无关联时返回 404；若比较涉及的提交在分页过程中发生变动，页面令牌会被拒绝并返回 InvalidArgument (HTTP 400) ，需从第一页重新列出。读取比较文件需要 repository:contents:read。
• 新增。 签名密钥端点会发送 Cache-Control: public, max-age=600, stale-if-error=600。缓存的 JWKS 可复用 10 分钟，之后需刷新；刷新失败时，上一次有效的密钥最多可再保留 10 分钟，超时后验证将失败。若遇到任何活跃密钥都无法验证的签名，应立即刷新，以便移除已停用的密钥 ID。
• 变更。 若检查运行在 deadlineAt 到期时仍处于 in_progress，将以 timed_out 结论完成并投递 repository.check_run.completed，此变更取代 8 月 27 日“截止时间不会改变运行状态”的说明。过期处理通过周期性扫描执行，而非为每个运行单独计时，因此运行可能在截止时间过后短暂保持原状态。queued 状态的运行永不过期，未设置 deadlineAt 的运行同样不会过期；Origin 会保留运行的 externalUpdatedAt，以便你的提供方之后提交的完成结果能够覆盖 timed_out 结论。
• 变更。 对于 Origin 从 GitHub 镜像的仓库，不再投递 repository.pushed。这些推送归 GitHub 管理，GitHub 会自行发送推送 webhook，Origin 的投递因此是重复的。推送到原生 Origin 仓库和出站镜像的事件照常投递，镜像状态也不影响其他任何事件。
• 变更。 当 head 与 base 没有共同历史时，Create Pull Request 会返回 InvalidArgument (HTTP 400) 并拒绝请求，不创建任何内容，不再返回此前由底层比较产生的 404。
• 变更。 如果某次推送导致开放 PR 的 head 与其 base 不再有共同历史，该 PR 将被关闭并投递 pull_request.closed。之后即使出现相关推送，该 PR 也不会重新打开。
• 变更。 OpenAPI 规范中的每个操作现在会列出该操作实际可能返回的响应码，不再为所有操作统一列出 400、401、403 和 429：所有带参数的路径均包含 404，处理程序可能报告冲突的操作包含 409，Batch Redeliver Webhook Deliveries 和 Sync Mirror 包含 202，Get Rate Limit 和 Get Authenticated App 的响应码则更少。Status schema 描述了 Origin 返回的错误结构，并说明 404 不会区分资源不存在与资源不可访问；此外，每个操作都附带请求和响应示例。请求处理逻辑保持不变；如有基于该规范生成的客户端，请重新生成以获取新的响应模型。

• 新增。 检查运行现在接受并返回可选的 deadlineAt 时间戳。可在 Post Check Run 或 Batch Upsert Check Runs 的 run 请求体中传入该字段，并通过 获取检查运行、List Check Runs For Suite 和 List Check Runs For Commit 读取。run 进入 completed 状态后，Origin 会清除该截止时间。如果更新请求中省略该字段，已存储的值将保持不变。如果截止时间比当前时间晚 24 小时以上，Origin 不会将其截断，而是直接以 InvalidArgument (HTTP 400) 拒绝请求。截止时间过后，run 的状态也不会随之改变。
• 变更。 已发布的 OpenAPI 规范现将 https://api.cursor.com 声明为服务器地址，并声明 bearerAuth HTTP bearer 安全方案。基于该文档生成的客户端会自动获取 base URL 和 Authorization: Bearer 要求。
• 变更。 OpenAPI 路径参数现与 URL 中的现有名称保持一致。在全部 55 个仓库级操作中，生成的 identifier.ownerSlug 和 identifier.name 绑定已改为 ownerSlug 和 repoName，标准 OpenAPI 生成器因此可以直接使用该文档。请求 URL 和请求行为均保持不变。如有基于该规范构建的客户端，请重新生成，以获取新的参数名称。
• 变更。 已发布的枚举不再列出 *_UNSPECIFIED 零值项，例如 Create Ruleset 中的 RULESET_ENFORCEMENT_UNSPECIFIED 和 Create Pull Request Review 中的 PULL_REQUEST_REVIEW_VERDICT_UNSPECIFIED。Origin 从未接受或返回过这些值，因此请求和响应均无变化。
• 变更。 规范中的每个操作现在都会记录 400、401、403 和 429 响应，这些响应均携带 google.rpc.Status 响应体，不再只提供兜底的 default 响应。有关响应体及完整状态列表，请参阅 Errors。

• 破坏性变更。 pull_request.reviewer.added、pull_request.reviewer.removed 和 pull_request.reviewer.rerequested 的审阅人 webhook 负载不再使用 reviewer.kind 与 reviewer.id 组合，改为带类型的审阅人对象，其中 reviewer.user 和 reviewer.group 有且仅有一个存在。迁移方式：原先在 reviewer.kind 为 user 时读取 reviewer.id 的地方，改为读取 reviewer.user.id；原先 reviewer.kind 为 group 的地方，改为读取 reviewer.group.id。
• 新增。 List Labels 返回代码仓库所拥有的标签定义，按名称排序：GET /v1/origin/repos/{ownerSlug}/{repoName}/labels。读取标签需要新增的 repository:labels:read 作用域。结果分页返回，默认每页 30 个标签，最多 100 个。
• 新增。 Create Label 在代码仓库中定义标签并返回该标签：POST /v1/origin/repos/{ownerSlug}/{repoName}/labels。所有标签写入操作都需要新增的 repository:labels:write 作用域。name 最长 50 个字符，description 最长 255 个字符，color 必须为六位十六进制字符且不含前导 #；如果名称已被该代码仓库中的其他标签使用，请求将被拒绝并返回 AlreadyExists (HTTP 409 Conflict) 。
• 新增。 Get Label 按名称返回单个代码仓库标签：GET /v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}。名称不存在时返回 404。
• 新增。 Delete Label 按名称删除代码仓库标签并返回 204：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}。删除标签后，该标签也会从所有已分配它的 PR 中移除。
• 新增。 Update Label 通过当前名称引用标签，更改其名称、颜色或描述：PATCH /v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}。省略的字段保持不变；如果重命名为其他标签已使用的名称，请求将被拒绝并返回 AlreadyExists (HTTP 409 Conflict) 。
• 新增。 List Check Run Annotations 按 ID 升序 (即创建顺序) 返回检查运行的注解：GET /v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}/annotations。读取注解需要 repository:checks:read。结果分页返回，默认每页 30 条注解，最多 100 条。
• 新增。 Create Check Run Annotations 以单个原子批处理向检查运行追加 1 到 25 条注解并返回这些注解：POST /v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}/annotations。追加注解需要 repository:checks:write。每个检查运行最多包含 100 条注解，超出上限的批处理将被拒绝并返回 ResourceExhausted (HTTP 429) ，且不会写入任何内容。该操作仅支持追加且不具备幂等性，因此若在结果不明确的失败后重试，可能会追加重复的注解。
• 新增。 List Pull Requests 新增五个查询参数：author，公开的操作者 ID，须与响应中 pullRequests[].author.user.id、pullRequests[].author.app.id 或 pullRequests[].author.serviceAccount.id 返回的值完全一致；base，按目标分支精确筛选，可接受短名称或完全限定的 ref；direction，desc 表示从新到旧 (默认值) ，asc 表示从旧到新；以及 since 和 until，以 RFC 3339 格式指定创建时间范围 (含边界) 。如果某个作者没有任何 PR，则返回空列表；其他任何无效值都会返回 InvalidArgument (HTTP 400) 。
• 新增。 已提交的评审被驳回时 (无论是被显式驳回，还是被更新的决定取代) ，系统会投递 pull_request.review.dismissed 事件。该事件的负载结构与 pull_request.review.submitted 相同，并会填充 review.dismissal；订阅该事件需要 repository:pull_requests:reviews:read 作用域。
• 新增。 安装记录现在会标明安装该应用的用户。Get App Installation 和 List App Installations 会返回 installedBy 字段，其中包含该用户的公开 user_… ID 和电子邮件；该字段也会随每个 installation.* webhook 快照一同发送。在快照中，它用于标识最初的安装者；若该用户记录已无法读取，则会省略该字段。安装回执新增 installedBy 认领，用于标明执行本次安装或重新授权的用户，因此重新授权后，两者可能不一致。

• 新增。 Ping Webhook 会向你的应用所配置的 webhook URL 发送一次测试投递，并报告接收端的应答：POST /v1/origin/app/webhook/pings。该投递的签名方式与生产环境投递相同，webhook-event-type 为 ping，且不隶属于任何安装。Origin 只发送一次、不会重试，该投递也不会出现在列出 Webhook 投递记录中。未配置 webhook URL 的应用会被拒绝，并返回 FailedPrecondition (HTTP 400) 。
• 新增。 错误响应会在两处携带请求 ID：X-Request-ID 响应头，以及 details 中的 google.rpc.RequestInfo 条目。Origin 会回显你发送的 x-request-id，未发送时则自动生成；即使消息是不透明的内部错误，也会包含该条目。参见错误。
• 变更。 创建 PR 和更新 PR 会拒绝长度超过 256 个字符的 title 或超过 65,536 个字符的 body，并返回 InvalidArgument (HTTP 400) 。此前，超出上述长度的值会因内部错误而失败。两项限额均按 Unicode 码位计数，因此 emoji 等辅助平面字符只计为一个字符。
• 变更。 Sync Mirror 的响应始终包含 synced (true 或 false) ，与 HTTP 状态码一致：为 true 时返回 200，为 false 时返回 202。此前该字段为 false 时会被省略，调用方需将字段缺失视为 false。
• 变更。 /v1/origin 下未匹配的路径，以及对已知路径使用错误方法的请求，现在会返回文档所述的错误封装，而非通用的路由响应体。消息会指明方法和路径，且不会回显查询字符串。
• 变更。 合并 PR 时，会针对合并所推进的基准引用投递 repository.pushed webhook。该推送由 Origin 自行执行，因此事件中不含推送者。此前，合并导致的基准引用更新不会触发投递。

• 变更。 Create Pull Request Comment 和 Update Pull Request Comment 现在会拒绝长度超过 65,536 个字符的 body，并返回 InvalidArgument (HTTP 400) 。此前，超出该长度的正文会因内部错误而失败。该限制按 Unicode 码位计数，因此表情符号等辅助平面字符只算作一个字符。

• 新增。 Delete Ruleset 通过稳定的 Origin ID 删除代码仓库规则集，并返回 204：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}。需要 repository:rulesets:write。存储在其他代码仓库中的规则集会被视为未知规则集；rulesetId 为空时，请求会被拒绝并返回 InvalidArgument (HTTP 400) 。
• 新增。 所有代码仓库作用域的端点现在除了可以通过所有者和名称引用代码仓库，还可以通过其稳定 ID 引用：将 _ 作为所有者 slug，并将 ID 作为代码仓库名称，例如 GET /v1/origin/repos/_/REPO_ID。该 ID 可从 Get Repo 返回的 id 字段中获取。代码仓库重命名后 ID 保持不变，但 ID 本身不授予任何权限，因此你的应用仍需在解析出的代码仓库上具备相应的作用域；对于应用无权访问的 ID，返回的 404 与 ID 不存在时相同。创建代码仓库 仅接受所有者 slug，并会拒绝 _。
• 变更。 应用现在可以访问镜像代码仓库。镜像可以被选入安装，会出现在 列出应用安装可访问的仓库 的结果中以及安装 webhook 负载 的代码仓库数组中，可以在 创建安装访问令牌 的 repositoryIds 中指定，也会接收 webhook 投递。在镜像成为稳定的出站镜像之前，它始终为只读：仅 repository:metadata:read 和 repository:contents:read 生效，其他作用域在该代码仓库上一律返回 403，git push 也不例外。请参阅 镜像代码仓库。

• 破坏性变更。 Get Tree 的 recursive 查询参数为布尔值而非 string，因此只有 true 和 1 会遍历整个树；其他任何值 (包括 false、0 以及不带值的 ?recursive) 都只列出直接子项。迁移方式：如果你的集成依赖任意非空 recursive 值来启用递归，请改为发送 recursive=true。
• 破坏性变更。 PR 生命周期 webhook 负载不再包含 PR 已分配的 labels，此变更取代了 2026 年 8 月 20 日公布的该字段。REST 响应仍包含该字段。迁移方式：改为从 获取 PR 或 List Pull Requests 读取标签，而非从 webhook 快照中读取。
• 新增。 List Rulesets 返回代码仓库中配置的所有规则集，以及一个共享的 repository 引用：GET /v1/origin/repos/{ownerSlug}/{repoName}/rulesets。规则集的配置数量有上限，因此响应不分页。读取规则集需要 repository:rulesets:read。
• 新增。 Create Ruleset 存储新规则集并将其返回，返回内容包含 Origin 为每条规则和每个绕过执行者分配的 ID：POST /v1/origin/repos/{ownerSlug}/{repoName}/rulesets。两个规则集写入端点均需要 repository:rulesets:write。
• 新增。 Get Ruleset 根据稳定的 Origin ID 返回单个规则集：GET /v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}。
• 新增。 Update Ruleset 完整替换规则集的配置，包括其 rules 和 bypassActors：PUT /v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}。已存储的条目会被整体替换而非合并，因此请发送所有需要保留的规则和绕过执行者。
• 新增。 规则集包含 id、name、description、enforcement (active、evaluate 或 disabled) 、kind (merge_branch、push_branch、push_tag 或 push_repository) 、includedRefNames 和 excludedRefNames 模式 (支持通配符以及 ~ALL 和 ~DEFAULT_BRANCH 标记) 、rules 和 bypassActors。如果单个列表超过 64 个模式、规则超过 20 条或绕过执行者超过 15 个，Create Ruleset 和 Update Ruleset 会以 InvalidArgument (HTTP 400) 拒绝请求。
• 新增。 合并 PR 支持可选的 expectedHeadSha 请求字段，即 PR head 必须匹配的完整提交 SHA。如果 head 已变动，合并会以 ABORTED (HTTP 409 Conflict) 被拒绝，且不会合并任何内容；如果该值不是完整的提交 SHA，则以 InvalidArgument (HTTP 400) 拒绝。省略该字段则直接合并当前 head。
• 新增。 所有者引用包含 type string，值为 team 或 user；Origin 无法解析时会省略该字段。所有出现 owner 或安装 target 的位置都会返回该字段，包括 Get Repo、List Repos、List App Installations，以及检查和 PR 响应中的代码仓库引用。

• 破坏性变更。 List Pull Request Labels 现在会在单个响应中返回所有已分配的标签，不再分页：pageSize 和 pageToken 查询参数以及 nextPageToken 响应字段均已移除。迁移方式：从请求中删除 pageSize 和 pageToken，改为从 labels 中读取完整的标签集合。
• 破坏性变更。 每个 PR 最多可包含 100 个标签。如果某次写入会导致标签数超出该上限，Add Pull Request Labels 和 Set Pull Request Labels 将以 FailedPrecondition (HTTP 400) 拒绝该请求。迁移方式：确保每个 PR 的标签数不超过 100 个；如需添加更多标签，请先移除部分现有标签。
• 新增。 PR 现在包含 labels 数组，列出已分配给该 PR 的标签，按名称排序；未分配标签时为空数组。List Pull Requests、获取 PR、Create Pull Request、Update Pull Request 和 合并 PR 均会返回该字段，PR 生命周期的 webhook 负载中也会包含该字段。

• 新增。 List Pull Request Labels 返回已分配给 PR 的标签，按名称排序：GET /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels。需要 repository:pull_requests:read。结果分页返回，默认每页 30 个标签，每页最多 100 个。
• 新增。 Add Pull Request Labels 将现有的代码仓库标签分配给 PR，同时保留 PR 上原有的标签：POST /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels。所有标签写入端点均需要 repository:pull_requests:write。
• 新增。 Set Pull Request Labels 用你发送的名称替换 PR 上的全部标签，发送空列表则清除所有标签：PUT /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels。
• 新增。 Remove Pull Request Label 按名称移除单个标签，并返回 PR 上剩余的标签：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels/{labelName}。
• 新增。 Remove All Pull Request Labels 清除 PR 上的所有标签并返回 204：DELETE /v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels。
• 新增。 标签条目包含 id、name、color (六位十六进制值，不含前导 #) 以及可选的 description。所有 PR 标签端点均返回这些字段。
• 变更。 应用 JWT 速率限制的预算从每分钟 600 点提高到 6,000 点，创建安装访问令牌的消耗也从 5 点降至 1 点，因此一个应用每秒约可生成 100 个安装令牌。
• 变更。 创建代码仓库以及通过 Git HTTPS 推送的所有者资格，现除 Pro、Pro+ 和 Ultra 外，还支持 Pro Student 和 Start 方案。团队所有者的要求保持不变。
• 变更。 代码仓库路径中的所有者 slug 和代码仓库名称现在解析时不区分大小写，响应返回的是存储时的大小写形式，而非你发送的大小写形式。创建代码仓库会拒绝与该所有者现有代码仓库名称仅大小写不同的名称，因此比较代码仓库名称时请忽略大小写。

• 破坏性变更。 当代码仓库的所有者没有写入 Origin 的资格时，Git over HTTPS 会以 403 拒绝推送。用户所有者必须订阅 Pro、Pro+ 或 Ultra 方案；团队所有者必须拥有有效的付费团队方案，不得处于隐私模式 (旧版) ，且 Origin 未被团队管理员关闭。克隆、获取和拉取不受影响。迁移：将推送返回的 403 视为所有者资格校验失败，此类错误无法通过重试解决；代表所有者推送前，请先确认其方案。
• 变更。 对于通过 创建代码仓库 创建的仓库，如果首次推送仅创建分支，且其中没有已存储的默认分支，则会重新设置 defaultBranch：Origin 会选用所创建的分支；若推送创建了多个分支且其中包含 main 或 master，则选用该分支。可通过 Get Repo 读取当前值。

• 破坏性变更。 如果请求的所有者不具备写入 Origin 的资格，创建代码仓库将拒绝该请求，并返回 FailedPrecondition (HTTP 400) 。用户所有者必须订阅 Pro、Pro+ 或 Ultra 方案；团队所有者必须拥有有效的付费团队方案，不得处于隐私模式 (旧版) ，且团队管理员未关闭 Origin。迁移：将创建代码仓库返回的 400 视为所有者资格校验失败，此类错误无法通过重试解决；代表所有者创建仓库前，请先确认其方案。

• 破坏性变更。 应用无法再访问源站从 GitHub 镜像的仓库。这些仓库不再出现在列出应用安装可访问的仓库的结果中，创建安装访问令牌会拒绝 repositoryIds 中的此类仓库，并且无论通过 REST API 还是 Git over HTTPS，指定此类仓库的请求都会返回 403。迁移：改为通过列出应用安装可访问的仓库发现仓库，不再依赖已存储的仓库列表；来源为 GitHub 的仓库请直接从 GitHub 读取，而非通过源站 API。
• 破坏性变更。 源站不再为其从 GitHub 镜像的仓库发送 Webhook，安装事件负载中的所选仓库数组和 repositoriesCount 也已不再包含这些仓库。迁移：来源为 GitHub 的仓库请从 GitHub 获取事件，并以安装负载中的仓库数组作为你的应用可访问的仓库集合。

• 变更。 修订版本参数现在除 SHA、分支或标签外，还接受符号引用 HEAD，涉及：List Commits、Get Commit、List Commit Files、Get Git Commit 和 Get Tree 的 sha；Get Contents 和 Batch Get Contents 的 ref；以及 Compare Commits 中 basehead 的任意一侧。
• 变更。 获取 Git 引用会解析符号引用 HEAD，并以 ref: "HEAD" 的形式连同末端提交一起返回。由于 HEAD 不在 refs/ 下，List Matching Git Refs 和 List Matching Git Refs by Path 只会精确匹配 HEAD。
• 变更。 移除安装或删除应用后，该安装的访问令牌会在 expiresAt 之前提前失效。REST API 和 Git over HTTPS 会以 401 拒绝已吊销的 token，因此必须重新安装应用，才能签发可用的新 token。参见安装访问令牌。

• 破坏性变更。 Get Contents 会拒绝解码后大于 1 MiB 的文件，并返回 FailedPrecondition (HTTP 400) ；在 Batch Get Contents 请求中，只要有一个文件超出大小限制，整个请求就会失败。
• 新增。 安装访问令牌现可用于 Git over HTTPS 身份验证。访问代码仓库的 cloneUrl 时，使用用户名 x-access-token，并以该 token 作为 HTTP Basic 密码。克隆、获取和拉取需要 repository:contents:read；推送需要 repository:contents:write。参见 Git HTTPS 身份验证。
• 变更。 在 List Repos、Get Repo、创建代码仓库、列出应用安装可访问的仓库 以及 repository.created webhook 负载中，cloneUrl 现改用 GitHub 风格的根路径 (https://origin.cursor.com/OWNER_SLUG/REPO_NAME.git) ，取代旧版 /git/ 路径。两种形式均可用于克隆，且 cloneUrl 本身不保证特定的路径格式，因此已存储的值仍然有效。
• 变更。 Get Contents 和 Batch Get Contents 响应中的 size 现表示解码后内容的字节数，而非 base64 content string 的长度。

• 破坏性变更。 审阅人 webhook 负载现在会在 reviewer.id 中提供稳定的外部 ID：当 kind 为 user 时，该字段为编码后的用户 ID (user_…，格式与组织 API 相同) ，取代原先按 provider 划分作用域的认证 ID；群组审阅人仍使用群组 public id (grp_…) 。受影响的事件包括 pull_request.reviewer.added、pull_request.reviewer.removed 和 pull_request.reviewer.rerequested。迁移：如果你的集成此前将 reviewer.id 与已存储的认证 ID 进行比对，请改为按编码后的 user_… ID 匹配用户审阅人。
• 新增。 应用最多可持有 10 个有效的 Ed25519 签名密钥，应用 JWT 验证时接受由任一有效密钥签名的令牌。
• 新增。 Sync Mirror 可从上游源同步镜像代码仓库的单个 ref：POST /v1/origin/repos/{ownerSlug}/{repoName}:syncMirror。需要 repository:contents:read；同步目标已满足时返回 200，同步进行中时返回 202。
• 新增。 安装后重定向会携带 installation_receipt 查询参数：这是一个由 Origin 签名、有效期五分钟的 JWT，通过 sub 认领标识该安装，并将发布者的 state 作为认领原样返回。在信任回调之前，请先使用已发布的 JWKS 对其进行验证。参见安装回执。
• 移除。 Origin actor 对象不再包含顶层的 kind 和 id 字段，至此完成 2026 年 8 月 5 日公布的弃用计划。检查、提交和 PR 响应中的所有 actor、author 和 dismissedBy 字段均受影响。迁移：请读取 actor 上所设置的 user、app 或 serviceAccount 变体。

• 新增。 获取速率限制可返回已认证 principal 共享的每分钟点数预算，且不消耗点数：GET /v1/origin/rate_limit。参见速率限制。

• 已弃用。 OriginActor.kind 和 OriginActor.id。操作者身份现为由 user、app 和 serviceAccount 变体组成的可辨识联合类型。迁移方式：改为读取所选变体的字段，不再使用顶层的 kind 和 id。