pnpm 的 GitHub Actions 依赖检查改为 Opt-in：`--include-github-actions` 与 `update.githubActions` 配置全解析

pnpm 的 GitHub Actions 依赖检查改为 Opt-in--include-github-actions与update.githubActions配置全解析【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm本文基于 pnpm 仓库中的变更说明 .changeset/interactive-update-github-actions-opt-in.md详解 pnpm 将「检查 GitHub Actions 依赖更新」从默认行为改为显式选择加入opt-in的机制。读者将掌握pnpm outdated/pnpm update检查工作流文件中第三方 Action 的开关方式、pnpm-workspace.yaml中的持久化配置写法以及该能力背后的实现原理与适用前提。变更背景为什么不再默认检查 GitHub Actions在引入 opt-in 之前pnpm outdated与pnpm update在检查 npm 依赖的同时会顺带读取项目.github/workflows目录下的 workflow 文件解析其中uses:引用的第三方 GitHub Actions 并检查其版本更新。问题在于检查 GitHub Actions 意味着对每一个被引用的仓库执行git ls-remote对应源码 pnpm11/deps/github-actions/src/index.ts 中的getRepoRefs调用。这在 GitHub 无法按 pnpm 预期方式访问的环境中会直接失败典型场景包括使用 GitHub Enterprise Server 作为代码托管平台企业内网使用自定义证书颁发机构custom CA签发证书完全离线的网络环境。因此本次变更由 issue #13254 驱动见变更说明原稿将该能力调整为默认关闭、显式开启pnpm outdated和pnpm update默认完全不读取 workflow 文件只有当用户显式传入--include-github-actions参数或在pnpm-workspace.yaml中配置update.githubActions: true时才会执行检查。默认行为所有命令一律不检查变更后的默认行为如下pnpm outdated默认只检查 package.json 中的 npm 依赖不读取任何 workflow / action 文件pnpm update默认只更新 npm 依赖不触碰.github/workflows无论是否处于 workspace 环境、是否使用-r递归模式默认行为均一致。这一点由测试用例直接锁定pnpm11/deps/inspection/commands/test/outdated/githubActions.ts 中的outdated does not look at GitHub Actions by default断言 mock 后的findOutdatedGitHubActions在默认参数下不会被调用pnpm11/installing/commands/test/update/githubActions.ts 同样验证了update --interactive默认不查找 GitHub Actions 更新。两种开启方式方式一命令行参数--include-github-actions两个命令都新增了布尔选项--include-github-actions# 检查并列出 workflow 中引用的过时 GitHub Actions pnpm outdated --include-github-actions # 交互式选择要更新的依赖含 GitHub Actions pnpm update --interactive --include-github-actions # 直接更新到最新版本--latest 对 GitHub Actions 同样生效 pnpm update --include-github-actions --latest命令注册位置pnpm outdated在 pnpm11/deps/inspection/commands/src/outdated/outdated.ts 的cliOptionsTypes中声明include-github-actions: Boolean帮助文本明确说明「Also check GitHub Actions dependencies in workflow and action files」pnpm update在 pnpm11/installing/commands/src/update/index.ts 的cliOptionsTypes中声明同样的选项其commandNames同时注册了update、up、upgrade三个别名因此pnpm up --include-github-actions、pnpm upgrade --include-github-actions同样可用。Rust 原生实现侧CLI 参数定义位于 pnpm/crates/cli/src/cli_args/update.rs其中include_github_actions: bool字段被传递到交互式更新的选项中。方式二pnpm-workspace.yaml中的update.githubActions如果希望在一个仓库内持久化开启该行为无需每次敲参数可以在pnpm-workspace.yaml的update段配置update: githubActions: true等价于每次命令都携带--include-github-actions。变更说明原文明确update.githubActions被设置为true时pnpm outdated与pnpm update都会读取 workflow 文件。配置解析链路TypeScript 实现位于 pnpm11/config/reader/src/getOptionsFromRootManifest.ts 的translateUpdateSettings函数update.githubActions经类型断言assertBoolean后写入内部updateConfig.githubActions字段Rust 侧对应的字段定义在 pnpm/crates/config/src/workspace_yaml/sections.rsgithub_actions: Optionbool。Opt-in 判断的实现原理无论走哪条路径最终都收敛到同一个判断函数。TypeScript 实现pnpm11/deps/github-actions/src/index.ts 中的核心判定export interface GitHubActionsOptInOptions { includeGithubActions?: boolean updateConfig?: { githubActions?: boolean } } export function shouldCheckGitHubActions (opts: GitHubActionsOptInOptions): boolean { return opts.includeGithubActions true || opts.updateConfig?.githubActions true }即「CLI 参数为 true」与「配置为 true」任一成立即执行检查两个开关都是白名单式的不存在模糊的默认值。Rust 实现原生版本在 pnpm/crates/cli/src/github_actions.rs 中提供了语义完全一致的opted_inpub(crate) fn opted_in(include_github_actions: bool, config: Config) - bool { include_github_actions || config.update_config.github_actions Some(true) }两处实现相互印证注释也一致地说明了「Reading them means runninggit ls-remoteagainst every referenced repository」这一设计动机。调用侧的附加约束pnpm update并非只在开关注册后就直接更新 workflow 文件pnpm11/installing/commands/src/update/index.ts 中的shouldUpdateGitHubActions还叠加了三重条件function shouldUpdateGitHubActions (opts: UpdateCommandOptions, include: IncludedDependencies): boolean { return include.devDependencies opts.save ! false !opts.lockfileOnly shouldCheckGitHubActions(opts) }include.devDependenciesGitHub Actions 被归类为开发期依赖在outdated输出中标记为(github action)belongsTo为devDependencies因此--prod模式下不会检查opts.save ! false--no-save时不写回文件!opts.lockfileOnly纯 lockfile 操作模式不涉及。检查与更新的工作流程开启开关后检查流程由 pnpm11/deps/github-actions/src/index.ts 中的createUpdatePlan驱动整体分为四步发现 Action 引用discoverActions扫描项目根目录.github/workflows下所有.yml/.yaml文件解析出每个uses:标量支持jobs级uses、steps列表中的uses以及runs.steps跳过docker://引用和指向仓库自身的本地引用./与$/形式读取远端引用对每个被引用的owner/repo执行git ls-remote默认经getRepoRefs并发受pLimit(8)限制收集全部 tag 与 commit 映射若某个仓库读取失败仅globalWarn告警并跳过不中断整体流程版本解析parseRepoVersions/findCurrentVersion从refs/tags/vX.Y.Z形式的 tag 中解析 semver 版本并按当前引用形式匹配——支持完整 SHA40 位十六进制、vX.Y.Z精确版本、vN大版本号以及通过行尾注释# vX.Y.Z标注版本号的 SHA 引用计算 wanted 与 latestwanted为满足^当前版本约束的最高版本latest为最高稳定版本当前版本本身为预发布版本时不受此限--compatible/--latest分别对应以wanted或latest作为升级目标。pnpm outdated --include-github-actions的输出会与 npm 依赖合并渲染表格 / 列表 / JSON--format三种格式均支持Action 条目名称带灰色(github action)标注pnpm update --include-github-actions则会把 workflow 文件中的引用改写为最新 commit并在原引用后补写或更新# vX.Y.Z注释以记录对应 tag。写入前会校验源文件在解析期间未被外部改动GITHUB_ACTIONS_WORKFLOW_CHANGED错误提示重试并通过writeFileAtomic原子写回。面向企业内网与离线环境update.githubActionsServer对于使用 GitHub Enterprise Server 的团队源码还提供了配套配置项update.githubActionsServerRust 侧对应github_actions_server见 pnpm/crates/config/src/workspace_yaml/sections.rs用于指定承载 Action 仓库的 GitHub 服务基地址update: githubActions: true githubActionsServer: https://github.example.com其解析同样位于 getOptionsFromRootManifest.ts 的translateUpdateSettings并最终通过outdated/update命令中的serverUrl: opts.updateConfig?.githubActionsServer传入检查逻辑。该值默认取GITHUB_SERVER_URL环境变量再回退到https://github.comresolveServerUrl强制要求 HTTPS 协议仅允许本机 loopback 地址使用 HTTP非法协议会抛出GITHUB_ACTIONS_SERVER_PROTOCOL错误。相关测试与验证仓库中为本次 opt-in 变更提供了成对的测试证据pnpm11/deps/inspection/commands/test/outdated/githubActions.ts覆盖outdated默认不检查、--include-github-actions开启检查、update.githubActions: true开启检查、以及-r递归模式下同样遵守 opt-inpnpm11/installing/commands/test/update/githubActions.ts覆盖update --interactive默认不查找、两种开启方式均可触发查找。测试均在临时目录中写入包含uses: actions/checkoutv4.1.0的.github/workflows/ci.yml通过 mockfindOutdatedGitHubActions断言其是否被调用直观验证「默认关闭、显式开启」的契约。升级适配建议如果你的 CI 或团队工作流此前依赖pnpm outdated/pnpm update自动检查 GitHub Actions升级到包含本次变更的版本后需要做以下适配本地一次性检查命令后追加--include-github-actions仓库级持久化在pnpm-workspace.yaml中写入update.githubActions: true注意该段为仓库级配置会随仓库提交而共享企业内网环境务必同时设置update.githubActionsServer否则检查仍会指向默认的github.com离线环境保持默认关闭即可这恰恰是本变更的初衷——避免不可达的git ls-remote拖垮整个 outdated / update 流程。总结本次变更的核心契约可以概括为一句话GitHub Actions 依赖的检查与更新从「隐式执行」变为「显式选择」。无论通过--include-github-actions参数还是update.githubActions配置开启其背后的代价——对每个被引用仓库执行git ls-remote——都由用户显式知情并接受从而让 pnpm 在 GitHub Enterprise Server、自定义 CA 或离线等受限网络环境中保持开箱即用不会因为无法访问默认的 GitHub 而报错。相关实现TypeScript 与 Rust 双实现、配置解析与测试用例均可在上文给出的源码路径中进一步查阅。【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考