发布者账户设置

本操作手册配置发布表面的发布者一侧。分发形态只有一个注册表：npmjs.com 上的作用域 npm 包 @ahmed-g-gad/apothem，由 publish-npm.yml 工作流发布。该工作流在 v*.*.* 标签推送时与 release.yml 并行运行，并且不等待它（带 tag 输入的手动调度是后备方式）。release 环境批准是把关点：操作者在 GitHub Release、Pages、CI、合规工作流和工具工作流都变绿之后批准它。其余每个产物都直接在 GitHub Release 页面上发布，无需外部发布者账户。

身份映射Copy Anchor Link

GitHub 所有者将来允许变动。在平台允许动态解析的场合，工作流与安装器逻辑会读取 github.repository、github.repository_owner 或 APOTHEM_GITHUB_REPO。注册表包标识符保持稳定，因为用户安装的是包名，而不是维护者的账户名。

npm (npmjs.com)Copy Anchor Link

1. 以 ahmed-g-gad 身份登录 https://www.npmjs.com/。

2. 在该账户上启用双因素认证。

3. 确认作用域包名：

   Copy Text

   npm view @ahmed-g-gad/apothem name

   返回 404 表示该作用域包尚未发布。任何其他包响应都必须在发布之前与本仓库和账户相匹配。

4. 如果界面要求首条包记录，则在 npm 上创建该包。保持名称为作用域形式：@ahmed-g-gad/apothem。

5. 从 GitHub Actions 为 @ahmed-g-gad/apothem 配置受信任发布：

   • GitHub 所有者：ahmed-g-gad
   • 仓库：apothem
   • 工作流文件名：publish-npm.yml
   • 环境：release（publish-npm.yml 中发布作业的 environment:；两者必须一致）
   • 允许的操作：npm publish。

6. 在 GitHub 中，验证 ahmed-g-gad/apothem 上存在 release 环境，并且其部署需要手动批准。

7. 将 npm 表面保持为一个公开注册表包：npmjs.com 上的 @ahmed-g-gad/apothem。

8. 批准标签推送所启动的 release.yml 运行中的 publish GitHub Release 作业。该作业等待 release 环境的批准，下方的就绪检查需要该运行为绿色；发布周期操作手册 的 §2.3 说明了具体操作。然后确认发布就绪：

   Copy Text

   bash scripts/release/check-release-ready.sh <release-tag>

   该检查需要设置 GH_TOKEN，并需要 dist/release-assets/ 中已发布的 sbom.cdx.json。发布周期操作手册 的 §2.4 给出了令牌范围与下载命令。

9. 为标签推送所启动的 Publish npm（publish-npm.yml）运行批准 release 环境部署。如果该运行没有启动，请从 GitHub Actions 标签页调度该工作流，并带上 tag=<release-tag>。

10. 验证已上线的包：

    Copy Text

    npm view @ahmed-g-gad/apothem version
    npx @ahmed-g-gad/apothem@<version> --version

不需要 NPM_TOKEN、用户名或密码机密。该工作流通过 npm 受信任发布（OIDC）进行发布，Node 版本和 npm CLI 的 OIDC 下限固定在 .github/workflows/publish-npm.yml 中。它针对 npmjs.com 运行 npm publish --provenance --access public，因此 Sigstore 出处溯源声明是显式的；对于从公开 GitHub Actions 工作流发布的公开包，npm 默认也会生成出处溯源。PUT 期间出现注册表 404 意味着 npm 侧的受信任发布者、包作用域或账户授权尚未对齐；在重试工作流之前先修正 npm 包设置。

一旦有一次受信任发布成功，就永久关闭令牌路径：在 npmjs.com 上该包的 Settings → Publishing access 中，选择 Require two-factor authentication and disallow tokens，并删除仓库中残留的任何 npm 令牌机密。该工作流已不再读取令牌。

参考资料：npm 受信任发布者、npm 出处溯源以及 npm 作用域。

GitHub 侧的发布前置条件Copy Anchor Link

其余发布表面是 GitHub 原生的，使用仓库作用域的 GITHUB_TOKEN 进行认证；不涉及任何外部账户。

1. GitHub Release。 .github/workflows/release.yml 在版本标签上运行，只需要其作业本地的 contents: write 权限。在打标签之前确认该工作流文件存在于 main 上。

2. Pages 自定义域名。 文档站点通过 publish-static-site.yml 部署到自定义域名 apothem.ahmedgad.com。该域名、DNS 和 HTTPS 强制由 Pages 启用操作手册建立；验证：

   Copy Text

   gh api repos/ahmed-g-gad/apothem/pages --jq '.cname, .https_enforced'
   curl -sSI https://apothem.ahmedgad.com/ | head -n 1

3. 脚本安装器。 install.sh 和 install.ps1 由 Pages 站点提供（https://apothem.ahmedgad.com/install.sh 和 https://apothem.ahmedgad.com/install.ps1）。它们由同一次 Pages 部署发布；不需要单独的账户或令牌。

验证矩阵Copy Anchor Link

设置完成后，每个发布者表面都会回答其规范检查：