go-tokenless

go-tokenless

删除你的 NPM_TOKEN。 只需一条命令，即可将 GitHub Actions 中的 npm 发布切换为可信发布（OIDC）。无需在任何地方存储长期有效的令牌，每次发布都会获得来源证明徽章。

npm 正在逐步淘汰令牌发布：自 2027 年 1 月 起，令牌将无法单独用于发布（npm 文档）。

目录

• 快速开始
• 更改内容
• 支持的发布设置
• 私有包
• 在 CI 中保持无令牌
• 与 AI Agent 搭配使用
• 选项
• 访问内容
• 仅你能执行的操作
• 故障排除
• 贡献
• 许可证

快速开始

在发布到 npm 的仓库根目录中运行：

npx go-tokenless          # 1. preview: lists every change and shows a diff, writes nothing
npx go-tokenless apply    # 2. edit the workflow and package.json files

然后按照它显示的后续步骤操作：提交更改、在 npm 上将包关联到工作流，并删除旧密钥。需要 Node 22.14+。

变更内容

只修改需要变更的行：保留工作流中的注释、引号和布局；在 package.json 中只编辑 repository 字段。写入前，go-tokenless 会重新读取两个版本，如果发现除了迁移之外还有其他变更，就会拒绝操作。

需要人工决策时，工具会以退出代码 1 停止且不写入任何内容：

• 外部用户可触发发布： 工作流由 pull_request_target、issue_comment、workflow_run 等类似触发器启动，且其中包含发布作业。授予该作业 OIDC 权限会让 fork 能够发布。
• 自托管运行器，npm 不接受其用于可信发布。
• repository 指向其他仓库。
• YAML 锚点。 修改可能会影响其他作业。
• 隐藏的发布命令： 传入了 npm 令牌，但找不到发布命令。

试运行（npm publish --dry-run）不会被视为发布。发布到 GitHub Packages 的步骤以及 GITHUB_TOKEN 值都会保持不变。

$ npx go-tokenless
go-tokenless: Ready to go tokenless. (acme/widgets)

Changes:
  .github/workflows/release.yml
    - publish: remove `NODE_AUTH_TOKEN` from job env
    - publish: grant `id-token: write`
    - publish: raise setup-node from Node 20 to 24 (trusted publishing needs Node 22.14+)
  package.json
    - widgets: add repository.url git+https://github.com/acme/widgets.git

Next:
  1. Run `npx go-tokenless apply` (or apply the diff above) and commit the changes on a branch.
  2. Add a trusted publisher for each package. With npm 11.15+ logged in with 2FA, run:
       npm trust github widgets --repo acme/widgets --file release.yml --allow-publish --yes
  3. Merge, then let the release workflow publish once. Check the new version shows a provenance badge.
  4. Delete the old publish token secret (`gh secret delete NPM_TOKEN`) and revoke the token on npmjs.com.

支持的发布配置

私有包

如果安装时需要从 npm 组织获取私有包，请为安装步骤提供一个只读令牌。发布步骤仍不使用令牌：

npx go-tokenless apply --read-token NPM_READ_TOKEN

       - run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_READ_TOKEN }}
       - run: npm publish

发布工作流中的每个安装步骤都会使用该令牌，包括单独的构建和测试作业。在 npmjs.com 上创建一个可精细配置、对你的包具有只读权限的令牌，并使用 gh secret set NPM_READ_TOKEN 保存。

在 CI 中保持无令牌

将此 Action 添加到 CI。如果令牌重新出现在发布工作流中，它会使作业失败；作业摘要会列出确切的修复项：

# .github/workflows/ci.yml
jobs:
  tokenless:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
      - uses: continuous-actions/go-tokenless@v1
        # with:
        #   mode: report               # annotate only, never fail
        #   read-token: NPM_READ_TOKEN # if installs use a read-only token

它会以只读方式运行 go-tokenless --json，且不需要令牌。其 status 输出为 already-tokenless、ready、blocked 或 no-publish-workflow。

与 AI Agent 搭配使用

go-tokenless 专为编码 Agent 运行而构建：支持 --json 输出、清晰的退出代码、MCP 服务和 Agent Skill。向你的 Agent 提出请求：“将我们的 npm 发布迁移到可信发布。”

{ "mcpServers": { "go-tokenless": { "command": "npx", "args": ["-y", "go-tokenless", "mcp"] } } }

MCP 工具：plan_trusted_publishing（只读）和 apply_trusted_publishing（写入文件；不会写入 git 或网络）。它已列入 MCP Registry，名称为 io.github.continuous-actions/go-tokenless。另请参阅 llms.txt 和 Agent Skill。

选项

npx go-tokenless [plan | apply | mcp] [options]

退出代码：0 正常 · 1 阻止（需要人工修复） · 2 用法错误 · 3 意外错误。

访问内容

• **文件：**会读取你指定的仓库中的 .github/workflows/*.yml、package.json 文件及相关脚本。apply 和 apply_trusted_publishing MCP 工具只会写入该仓库内的工作流和 package.json 文件，绝不会跟随链接跳出仓库。
• **网络：**仅向 https://registry.npmjs.org/<package> 发送只读 GET 请求，以检查每个软件包是否已存在（使用 --offline 或将 MCP 的 offline 设为 true 可关闭此检查）。不会获取或发送任何其他内容，也没有遥测。
• **绝不会：**运行仓库代码、读取机密或环境令牌、运行任何会造成更改的 git 命令，或代你联系 npm 或 GitHub。
• **运行方式：**Claude Code 插件和 Gemini 扩展会通过 npx -y go-tokenless@<pinned version> mcp 启动 MCP 服务。

只有你能完成的操作

go-tokenless 绝不会接触你的 npm 账户、机密或 git 历史记录。执行 apply 后：

1. **将每个软件包关联到工作流：**运行打印出的 npm trust github … 命令（npm 11.15+，需要进行 2FA 验证），或前往 npmjs.com → 软件包 → Settings → Trusted publishing。
2. 新软件包必须先手动发布一次；npm 只能关联已存在的软件包。计划会标记这些软件包。
3. 删除旧机密，并在首次无令牌发布后撤销该令牌。

故障排查

每种错误都有单独的页面介绍其原因和修复方法：ENEEDAUTH、PUT 返回 404、E422 repository.url、仍在使用令牌以及绕过 2FA 的通知。

参与贡献

欢迎提交问题和拉取请求。运行 corepack enable && yarn install && yarn check（类型检查、构建和端到端测试）。请参阅 AGENTS.md 了解代码的组织方式，并参阅 SECURITY.md 报告漏洞。

许可证

MIT © continuous-actions