ci: automate Chrome Web Store publishing via the Publish API / 用 Chrome Web Store Publish API 实现扩展发布全自动化

[BB-fat]

English

Problem

The current release workflow (release-extension.yml, triggered by ext-v* tags) stops at packaging: it builds browser-skill-extension-v<version>-chrome.zip, uploads it as a workflow artifact, and attaches it to a GitHub Release. Publishing to the Chrome Web Store is still fully manual — a developer must download the zip, open the CWS dashboard, upload it, and click publish. This is slow, error-prone, and a single-person bottleneck.

Proposal

Automate the last mile with the Chrome Web Store Publish API (v2). Add a publish-cws job to release-extension.yml:

1. Upload: POST https://chromewebstore.googleapis.com/upload/v2/publishers/{PUBLISHER_ID}/items/{EXTENSION_ID}:upload (zip as binary body). Or use the CLI wrapper chrome-webstore-upload-cli: chrome-webstore-upload upload --source <zip>.
2. Publish: POST .../v2/publishers/{PUBLISHER_ID}/items/{EXTENSION_ID}:publish; CLI: chrome-webstore-upload publish --extension-id <id>. publishType supports DEFAULT_PUBLISH / TRUSTED_TESTERS / STAGED_PUBLISH (CLI: --trusted-testers).
3. Optional safety gate (recommended): put the publish job behind a GitHub Environment with required reviewers — CI uploads automatically, a maintainer clicks once to publish.

One-time setup (extension owner)

1. In a Google Cloud project, enable the Chrome Web Store API, configure the OAuth consent screen, create an OAuth client, and obtain a refresh token for scope https://www.googleapis.com/auth/chromewebstore (guide).
2. Get the PUBLISHER_ID from the CWS dashboard URL.
3. Configure repository secrets: CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN, PUBLISHER_ID (matching the CLI's env var names), plus the extension ID.

Notes from the official docs

• The uploaded zip's manifest version must be incremented or the API rejects the upload — the existing tag vs package.json version guard already covers this.
• API publishing keeps the item's existing visibility settings; if visibility was changed manually in the dashboard, one manual publish is required before the API can publish again.
• fetchStatus is available for troubleshooting; cancelSubmission can retract a submission under review.

Acceptance criteria

• Pushing an ext-v* tag (or manual dispatch) results in the new version appearing in the CWS dashboard with no one touching the zip.
• Upload/publish failures fail the workflow run with readable logs.
• Secrets never appear in logs; publishing to TRUSTED_TESTERS is supported as an option.

References

• API v2 guide: https://developer.chrome.com/docs/webstore/using_webstore_api/
• API v2 reference (publishers.items): https://developer.chrome.com/docs/webstore/api/reference/rest/v2/publishers.items/publish
• CLI: https://github.com/fregante/chrome-webstore-upload-cli

---

中文

问题

目前的发布 workflow（release-extension.yml，由 ext-v* tag 触发）只做到打包为止：构建 zip、传 artifact、挂到 GitHub Release。发布到 Chrome Web Store 仍需开发者手动下载 zip、登录 CWS 后台上传并点发布——慢、易错、依赖单人。

方案

用 Chrome Web Store Publish API（v2） 自动化最后一步。在 release-extension.yml 新增 publish-cws job：

1. 上传：POST https://chromewebstore.googleapis.com/upload/v2/publishers/{PUBLISHER_ID}/items/{EXTENSION_ID}:upload（body 为 zip 二进制）。也可直接用 CLI 封装 chrome-webstore-upload-cli：chrome-webstore-upload upload --source <zip>。
2. 发布：POST .../v2/publishers/{PUBLISHER_ID}/items/{EXTENSION_ID}:publish；CLI：chrome-webstore-upload publish --extension-id <id>。publishType 支持 DEFAULT_PUBLISH（默认）/TRUSTED_TESTERS/STAGED_PUBLISH，CLI 用 --trusted-testers。
3. 安全闸（可选，推荐）：publish job 挂带 required reviewers 的 GitHub Environment——CI 自动上传，维护者一键确认发布。

前期准备（一次性，需扩展 owner）

1. Google Cloud 项目启用 Chrome Web Store API，配置 OAuth consent，创建 OAuth client，用发布者账号按 scope https://www.googleapis.com/auth/chromewebstore 换取 refresh token（指引）。
2. 从 CWS 后台 URL 取得 PUBLISHER_ID。
3. 配置仓库 secrets：CLIENT_ID、CLIENT_SECRET、REFRESH_TOKEN、PUBLISHER_ID（与 CLI 环境变量名一致），以及扩展 ID。

注意点（来自官方文档）

• 上传 zip 的 manifest version 必须递增，否则 API 拒绝——现有 tag/package.json 版本 guard 正好兜住。
• API 发布沿用 CWS 后台的可见性设置；若后台手动改过可见性，需先手动发布一次，之后才能用 API 发布。
• 失败排查可用 fetchStatus 查询状态；误提交可用 cancelSubmission 撤回审核中的提交。

验收标准

• 推 ext-v* tag（或手动触发）后新版本自动出现在 CWS 后台，全程无需人工接触 zip。
• 上传/发布失败时 workflow 明确失败且日志可读。
• secrets 不落日志；支持仅发 TRUSTED_TESTERS。

参考

• API v2 指南：https://developer.chrome.com/docs/webstore/using_webstore_api/
• API v2 参考（publishers.items）：https://developer.chrome.com/docs/webstore/api/reference/rest/v2/publishers.items/publish
• CLI：https://github.com/fregante/chrome-webstore-upload-cli

[BB-fat]

@iuyo5678 @Ljy-0827 @shnpd

[iuyo5678]

Good idea, let me get it done.