pinact run 完全指南8 个核心参数深度解析玩转 Actions 版本固定【免费下载链接】pinactpinact is a CLI to edit GitHub Workflow and Composite action files and pin versions of Actions and Reusable Workflows. pinact can also update their versions and verify version annotations.项目地址: https://gitcode.com/gh_mirrors/pi/pinactGitHub Actions 的安全性始终是 CI/CD 实践中的头等大事而pinact正是为此而生的一款开源 CLI 工具它专门负责把 GitHub Actions 与 Reusable Workflows 的版本固定pin到完整的 commit SHA并附上对应的版本注释从根源上杜绝标签tag被篡改带来的供应链风险。想要彻底玩转Actions 版本固定最关键的一步就是吃透pinact run这条核心命令。本文将以最简单易懂的方式带你逐项拆解pinact run的 8 个核心参数什么时候用、怎么用、有哪些坑一文讲透新手也能快速上手。小提示所有参数的完整定义都可以在源码pkg/cli/run/command.go与pkg/di/flag.go中找到权威文档见USAGE.md。为什么必须把 Actions 固定到 commit SHA先花 30 秒理解为什么。GitHub 官方明确建议将 Action 固定到完整长度的 commit SHA是目前唯一能让 Action 作为不可变发布版本使用的方式。因为标签是可变的一旦维护者仓库被攻破或标签被移动你 CI 里拉到的可能就是恶意代码。对比一下# ❌ 不安全标签可能被篡改 uses: actions/cachev3 # ✅ 安全固定到完整 SHA并保留版本注释 uses: actions/cache88522ab9f39a2ea568f7027eddc7d8d8bc9d59c8 # v3.3.1pinact run帮你自动完成这个转换而且参数灵活覆盖检查、更新、验证、离线等全部场景。核心参数总览一张表看懂 8 大参数参数别名作用一句话总结-check—只检查不修改CI 校验神器-no-api—离线检查不调用 GitHub API-update-u一键升级 Actions 到最新版本-min-age-m设置冷却期跳过过新的版本-verify-comment-verify/-v验证版本注释与 SHA 是否匹配-include/-exclude-i/-e用正则精确圈定处理范围-branch-to-tag—把分支引用转成最新稳定标签-format sarif—输出 SARIF 报告接入安全扫描下面逐一深度解析。1.-check只检查不修改CI 里的第一道防线pinact run默认会直接改写文件。如果你只想检查而不想动文件就用-check它等价于-fixfalsepinact run -check在 CI 中这个参数配合退出码能实现发现未固定就失败的效果——pinact 发现需要固定的内容时返回退出码 1完全固定则返回 0非常适合作为 Pull Request 的门禁检查。相关实现逻辑见pkg/di/run.go中的resolveFix函数。2.-no-api完全离线的语法级检查有些环境无法访问 GitHub API此时-no-api就派上用场了。它只做语法层面的检查判断引用是否已是 40 位完整 SHA不联网、不解析版本pinact run -fixfalse -no-api注意三个限制-no-api不能与-update、-verify-comment、-verify-min-age组合使用而且必须配合-fixfalse或-format sarif否则直接报错。这些组合校验逻辑见pkg/di/run.go的validateNoAPI。3.-update把 Actions 一键升级到最新版固定版本不等于锁死版本。想升级时-update别名-u会调用 GitHub API 获取每个 Action 的最新版本并把 SHA 与版本注释一并更新pinact run -update升级时它会自动优先选择符合-min-age冷却期要求的版本避免一升级就踩到刚发布、可能有问题的版本。4.-min-age与-verify-min-age给版本加一道冷却期这是 pinact v4 最具供应链安全价值的能力之一。-min-age别名-m设定最低发布年龄天数防止使用/升级到太新的版本# 只使用/升级到发布超过 7 天的版本 pinact run -min-age 7它有两种工作模式校验新版本升级时自动过滤掉不足 7 天的版本无需额外参数校验当前版本主动审计现有固定是否满足冷却期需显式加-verify-min-age或在配置文件的min_age.always: true中开启。在 CLI 上设置-min-age会自动隐式开启-verify-min-age见pkg/cli/run/command.go中的处理逻辑。审计不通过时pinact 返回退出码 2让 CI 能明确感知风险。5.-verify-comment揪出版本注释造假这是 pinact 的招牌功能。想象一下某行写着actions/checkoutee0669... # v3.5.1看起来版本注释是 v3.5.1但那个 SHA 实际指向的是 v2.7.0——攻击者完全可以用安全标签做注释、背后挂着恶意 SHA。-verify-comment别名-verify/-v会调用 GitHub API核对 SHA 与注释是否一致pinact run -verify-comment在 v4 中发现不匹配时 pinact 会自动把注释纠正为真实版本同时给出 WARN 日志。在 PR 场景下这一参数能有效拦截注释与 SHA 不符的隐藏风险。详细说明见文档docs/codes/001.md。6.-include/-exclude正则精确圈定处理范围大型仓库里往往有上百个 Action有时只想处理其中一部分。-include别名-i只处理匹配的 Action-exclude别名-e则跳过匹配的 Action两者都支持正则、可重复指定# 只固定 actions 官方库 pinact run -i actions/.* # 排除 aqua 安装器 pinact run -e ^aquaproj/aqua-installer$正则按部分匹配规则求值如需精确匹配记得用^...$锚定。注意当用命令行参数显式传入文件时配置文件中的files列表会被忽略。7.-branch-to-tag把分支引用也固定下来默认情况下pinact 故意不固定main、master这类分支引用因为分支天然是流动的。但如果你就是想固定某个分支对应的版本可以用-branch-to-tag指定一个匹配分支名的正则把它转成该 Action 的最新稳定标签并固定# 把 main 分支固定到最新稳定标签 pinact run --branch-to-tag ^main$这里务必使用^main$精确锚定避免误伤mainline之类的分支。该参数可多次指定且同样受-min-age冷却期约束。8.-format sarif输出标准安全报告-format sarif把检查结果输出为 SARIF 格式目前唯一支持的格式方便接入 reviewdog、GitHub Code Scanning 等工具pinact run --format sarif sarif.json注意指定-format sarif会隐式等同于-fixfalse不写文件如需同时修复要显式加-fixpinact run --format sarif -fixSARIF 输出实现见pkg/controller/run/sarif.go配合 GitHub Actions 的upload-sarif即可实现自动安全扫描。彩蛋-diff-file只固定 PR 改动的行最后分享一个实用技巧-diff-file参数只处理统一 diff 中号新增的行非常适合在 PR CI 中渐进式引入 pinact——历史遗留的未固定 Action 先不管只保证新增代码是安全的pinact run -diff-file diff.txt # 或从标准输入读取 cat diff.txt | pinact run -diff-file -配合pr-unified-diff-action等工具生成 PR diff即可无缝嵌入现有 CI 流程。退出码速查CI 里如何判断结果退出码含义0全部已固定或已自动修复1-fixfalse且有内容需要固定2存在无法自动修复的问题分支引用、注释不匹配、冷却期违规等3GitHub API 错误或参数组合非法常见参数组合实战模板把以上参数组合起来就是一套完整的 CI 安全策略# 本地修复固定版本并保留注释 pinact run # CI 门禁只检查不修改 pinact run -check # PR 检查验证注释真实性 只检查新增行 pinact run -verify-comment -diff-file diff.txt -check # 安全升级只升到发布超过 7 天的版本 pinact run -update -min-age 7总结pinact run的 8 个核心参数覆盖了 Actions 版本固定的完整生命周期-check负责把关、-no-api负责离线、-update负责升级、-min-age负责防新、-verify-comment负责验真、-include/-exclude负责圈定、-branch-to-tag负责兜底、-format sarif负责上报。掌握它们你就能在 GitHub Actions 供应链安全上做到既固定得住、又升级得动、还验证得准。赶紧在自己的仓库里跑一次pinact run体验 SHA 固定带来的安全感吧【免费下载链接】pinactpinact is a CLI to edit GitHub Workflow and Composite action files and pin versions of Actions and Reusable Workflows. pinact can also update their versions and verify version annotations.项目地址: https://gitcode.com/gh_mirrors/pi/pinact创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考