发布¶
版本发布由一个已发布的 GitHub 版本驱动,其标签是一个 SemVer 值, 前缀为 v,例如 v1.2.7。
统一的 Release 工作流会先解析该标签一次,随后通过 npm 打包、Docker 构建参数以及 Docker-safe 镜像标签,传递派生的 version, version_tag 以及 Docker 安全镜像标签,并将其传递至 npm 打包、Docker 构建 参数、镜像标签、服务器元数据、README 标记和文档 标记中。
所有应用测试套件、覆盖率、包安装和依赖签名检查都在合并前运行,并由 required-ci 强制要求。Release 工作流通过 package:pack 和 docs:build:site 构建并发布已测试的代码版本,同时验证发布元数据和产物文件清单。
GitHub 仓库设置¶
请在首次发布之前配置这些设置。
| 范围 | 所需设置 |
|---|---|
| Actions | 为仓库启用 GitHub Actions。 |
| Actions 令牌 | 允许工作流请求各自声明的权限。 |
| 分支保护 | 合并到 main 前,要求 Actionlint、CI、CodeQL 和 Dependency Review 通过。 |
| Pages | 将 Build and deployment -> Source 设置为 GitHub Actions。 |
| Packages | 允许 GitHub Actions 将包发布到 GitHub Packages。 |
| 环境 | 创建 npm-production、docker-production、github-pages 和 mcp-registry-production。 |
| 代码扫描 | 启用代码扫描,以查看 CodeQL、Scorecard 和 Trivy 的 SARIF 结果。 |
将必要的审阅者添加到 npm-production、docker-production 以及 mcp-registry-production,以便在 发布 GitHub Release 后,发布版本需要人工审批。 github-pages 环境由 原生 GitHub Pages 部署任务使用。
npm 发布¶
该 npm 发布工作流通过 npm Trusted Publishing 结合 GitHub Actions OIDC 进行发布。它不使用 NPM_TOKEN 进行发布。
请使用以下确切值在 npmjs.com 上配置可信发布者:
| npm Trusted Publisher 字段 | 值 |
|---|---|
| 提供方 | GitHub Actions |
| 仓库 | swimmwatch/cloakbrowser-mcp |
| 工作流文件名 | release.yml |
| 环境 | npm-production |
| 允许的操作 | npm publish |
npm 任务在 GitHub 托管的运行器上运行,使用 Node.js 24,并保留 id-token: write,以便 npm 能够将 GitHub Actions OIDC 令牌兑换为 短效发布凭证。npm 可信发布需要 npm CLI >=11.5.1 以及 Node.js >=22.14.0。
出版用途:
通过 Trusted Publishing 发布时,npm 会自动为来自公共仓库的公共包生成 包来源信息。请勿将长期有效的 npm 发布令牌添加回此工作流中。
该软件包版本源自 GitHub 发布标签中 npm pack 和 npm publish 之间,若 package.json 与 解析后的发布版本不匹配,则任务将失败。
Docker 发布¶
Docker 镜像发布到:
docker 作业使用存储库 GITHUB_TOKEN,其中 packages: write 作为 GHCR 的仓库。 Docker Hub 发布需要 DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN 必须包含在 docker-production 环境或仓库密钥中。
该工作流会在镜像成功 推送后更新 Docker Hub 仓库概览。对于此 GitHub Actions 发布流程,Docker Hub 不会自动拉取根镜像 README.md; Docker Hub 专用的概览由 docs/dockerhub-readme.md 维护。
在合并 release PR 之前,CI 会验证:
- 运行 TypeScript、代码检查、格式化、构建、测试及代码覆盖率检查;
- 验证 npm 包元数据和包内容;
- 为
linux/amd64和linux/arm64构建 Docker 镜像; - 运行 Docker
--help烟雾检查; - 使用桥接一致性脚本将
linux/amd64镜像与上游 Playwright MCP 进行比对; - 使用 Trivy 扫描 Docker 镜像,以检测操作系统和库中的高危及关键漏洞。
在发布版本期间,Docker 工作流会:
- 应用发布版本;
- 在 Docker 构建过程中,在已固定的 Playwright MCP 基础镜像上应用可用的 Debian 安全更新;
- 从运行时镜像中移除未使用的全局 npm 有效载荷;
- 发布多平台镜像;
- 在镜像推送成功后更新 Docker Hub 概览。
Docker 构建接收了 RELEASE_VERSION、RELEASE_VERSION_TAG 以及 VCS_REF 这三个构建参数。 该工作流还会解析上游 Playwright MCP 基础镜像的摘要,并将其作为 PLAYWRIGHT_MCP_IMAGE_DIGEST 传递。
最终镜像存储的值与 OCI 标签和运行时元数据 环境变量中的值相同。已发布的镜像包含以下标签:标题、描述、 来源、文档、版本、修订版、许可证、作者、供应商、基础镜像 名称、基础镜像摘要以及 MCP 服务器名称。
Trivy 是免费的开源软件,进行公共 图像扫描时无需外部令牌。当代码 扫描功能启用时,SARIF 结果会上传至 GitHub 代码扫描服务。
首次发布后,请确认 GHCR 软件包已设为公开并链接到此 仓库,同时确认 Docker Hub 仓库已设为公开。
Docker 发布了针对 linux/amd64 的多平台清单,以及 linux/arm64 的多平台清单。PR CI 会在合并前对两个平台进行烟雾检查, 并保持 linux/amd64 上的浏览器工具一致性对比。
MCP 注册表发布¶
mcp-registry 作业将 server.json 至官方 注册表,地址为:
服务器发布使用本地 MCP Registry Publish 复合 GitHub Action、 官方的 mcp-publisher CLI 以及 GitHub Actions OIDC。 请勿针对 modelcontextprotocol/registry 提交拉取 请求以列出该服务器;该存储库 明确要求包作者使用 mcp-publisher 进行发布。
该工作流无需 Glama、计费、GitHub PAT、DNS 凭据或 长期有效的注册表密钥。它使用:
id-token: write,用于 GitHub OIDC 身份验证;mcp-publisher login github-oidc;- 现有的 GitHub 命名空间
io.github.swimmwatch/cloakbrowser-mcp; - npm 包
mcpName的值,用于证明 npm 包的所有权; - Docker 镜像标签
io.modelcontextprotocol.server.name,用于证明 OCI 镜像的所有权。
MCP 注册表任务与 npm、Docker 以及文档发布使用相同的 GitHub 发布事件触发。该任务声明了 needs: [npm, docker],因此 npm 和 Docker 的发布会在注册表发布开始之前完成。文档部署声明了 needs: [docs-build, npm, docker, mcp-registry],因此 GitHub Pages 只会在 npm、Docker 和官方 MCP Registry 成功发布后更新。该复合 操作有意侧重于注册表:它会在本地验证 server.json, 并使用 mcp-publisher进行验证,检查该注册表的精确版本是否 已可见,使用mcp-publisher login github-oidc 进行身份验证,发布 服务器元数据,并验证最终的注册表条目。
如果注册表发生暂时性故障,请在 npm 和 Docker 作业成功后,在原始发布运行中重新运行失败的 mcp-registry 作业。Release 的手动 workflow_dispatch 触发器用于使用明确指定的标签运行完整发布流水线。
使用以下命令验证已发布的注册表项:
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.swimmwatch/cloakbrowser-mcp"
npm run registry:check
GitHub 的 https://github.com/mcp 注册表是一个独立的、经过筛选的 发现平台。 虽然必须向官方 MCP 注册表发布,但这并不能 保证在 GitHub 的 /mcp 页面上立即可见。 请将 npm run registry:check 视为针对官方注册表、npm、 GHCR、Docker Hub 以及 GitHub MCP 可见性(尽最大努力检测)的发布验证工具。 仅在 GitHub MCP 可见性应成为硬性 门槛后,才使用 npm run registry:check:strict。
Glama 目录检查清单¶
Glama 目录评分与 GitHub 发布以及官方 MCP 注册表发布是分开的。该代码库包含 glama.json,因此 swimmwatch 的维护者账户可在 Glama 中申领或确认所有权。
在发布稳定版之前,请完成免费的 Glama 检查清单:
- 在
glama.json合并到main之后; - 启动
https://glama.ai/mcp/servers/swimmwatch/cloakbrowser-mcp/admin/dockerfile; - 配置 Glama 以构建该仓库的 Dockerfile,并启动现有的 stdio 入口点,无需额外密钥;
- 保持运行时与 CloakBrowser 默认设置兼容:
cloak浏览器 引擎、无头模式、标准输出(stdout)以及/data构建产物存储; - 点击“部署”并等待构建测试通过;
- 创建并发布一个与 GitHub 发布版本相同的 Glama 发布版本,例如
1.2.7; - 发布后使用一次 Glama 的“在浏览器中试用”功能,以引导初始 使用;
- 手动添加相关服务器,至少包括官方的 Playwright MCP 服务器, 并可选添加密切相关的浏览器自动化替代方案。
请勿仅为了提高目录 评分而添加计费方式或付费的 Glama 托管服务。如果 Glama 要求针对必选检查清单项进行计费,请将其视为 发布阻碍,需要维护者做出明确决定。
安全工作流¶
该代码库使用免费的安全工具:
| 工作流 | 工具 | 触发条件 | 用户设置 |
|---|---|---|---|
CodeQL | GitHub CodeQL | push, pull request, 每周, 手动 | 启用代码扫描以查看 SARIF 结果。 |
Dependency Review | GitHub Dependency Review | pull request | 无需外部账户或令牌。 |
OpenSSF Scorecard | OpenSSF Scorecard | push, 每周, 手动 | 启用代码扫描以查看 SARIF 结果。 |
Zizmor | zizmor | 工作流变更, 手动 | 无需外部账户或令牌。 |
CI | Trivy | PR Docker 构建 | 启用代码扫描以查看 SARIF 结果。 |
CI | npm audit --omit=dev --audit-level=high | PR CI | 无需外部账户或令牌。 |
外部 GitHub Actions 固定到完整的提交 SHA,并附有可读的版本注释。更新工作流时请保留这些固定引用。
文档发布¶
docs-build 和 docs-deploy 任务使用原生的 GitHub Pages Actions 部署流程来部署 MkDocs。 仓库的 Pages 设置必须使用 GitHub Actions 作为 源。
该工作流以严格模式生成文档,将生成的 site/ 目录中,并将其与actions/upload-pages-artifact一起部署,最后通过 actions/deploy-pages 仅在 npm、Docker 和 MCP Registry 成功发布后部署到 github-pages 环境中。
文档发布过程还会在 MkDocs 构建完成后运行 SEO 验证工具。 可选的网站管理员验证令牌使用官方免费的网站管理员工具,并可 作为仓库变量或密钥提供:
GOOGLE_SITE_VERIFICATIONBING_SITE_VERIFICATIONYANDEX_SITE_VERIFICATIONBAIDU_SITE_VERIFICATIONNAVER_SITE_VERIFICATION
可选的 IndexNow 通知需要一个名为 INDEXNOW_KEY 的存储库密钥。设置该密钥后,工作流会在 GitHub Pages 部署完成后发布所需的密钥文件,并 提交生成的站点地图 URL。
未经单独明确 决定,请勿将付费索引服务、广告产品或第三方 分析工具添加到文档发布流程中。
上游监测¶
上游监控工作流每天运行一次,也可以通过 GitHub Actions 手动启动。它会检查上游的两个 Playwright MCP 分发渠道:
- npm 包:
@playwright/mcp; - Docker 镜像:
mcr.microsoft.com/playwright/mcp。
当检测到上游有新版本时,该工作流会创建一个 GitHub 问题 并将其分配给 swimmwatch。该问题包含当前版本和最新版本的 npm/Docker 版本、来自 microsoft/playwright-mcp 的简短发布说明摘要,以及上游完整变更日志、npm 包和 Docker 标签的链接。
在本地运行相同的检查,命令如下:
发布标签¶
| 发布类型 | GitHub Release 设置 | npm dist-tag | Docker 标签 |
|---|---|---|---|
| 稳定版 | 非预发布版 | latest | vX.Y.Z, X.Y.Z, X.Y, latest |
| 预发布版 | 预发布版 | next | vX.Y.Z-prerelease, X.Y.Z-prerelease |
检查清单¶
发布新闻稿之前:
- 仅在
Actionlint和CI显示为绿色后才进行合并。 - 基于
v1.2.7这样的标签创建 GitHub 发布版本。 - 发布
nextnpm 版本时,将其标记为预发布版本。 - 确认已为
release.yml和npm-production已配置 npm 受信任发布者。 - 确认
npm-production、docker-production、github-pages以及mcp-registry-production环境是否存在。 - 若需上传 SARIF 报告,请确认已启用 GitHub 代码扫描功能。
- 首次发布 Docker 镜像后,请确认 GHCR 包的可见性设置为公开。
- 请确认 Glama 服务器已完成同步,并通过 Dockerfile 管理 页面进行测试,且已发布为相同的稳定版本。
SUPPORT.md 已刻意推迟,直到该项目拥有超越 GitHub 问题跟踪和安全公告的稳定支持 政策为止。