gitleaks-action是一款基于 GitHub Actions 的密钥检测工具（SAST），能在 push、pull request、定时任务等事件中自动扫描 git 仓库里的密码、API Key、Token 等硬编码密钥。由于 GitHub 正在弃用 Node 20 运行时，v2 版本即将停止工作——而本次gitleaks-action v2到v3迁移的核心只有 2 个步骤：把 Action 版本改为v3，把actions/checkout升到v6（Node 24 发行版）。无需改动任何输入、输出或行为配置，几分钟即可完成升级。

为什么现在必须迁移：Node 20 弃用时间表

v3 把 GitHub Actions 运行时从Node 20 迁移到了 Node 24。这不是"可选优化"，而是有明确截止日期的强制要求：

⚠️ 也就是说，如果你还在用 v2，最迟要在 2026 年 9 月 16 日之前完成迁移，否则定时扫描和 PR 检查会直接失败。

最快迁移方法：两步配置法

整个升级只涉及工作流文件中的两行改动，下面逐一说明。

步骤一：将 Action 版本号从 v2 改为 v3

打开你的工作流文件，把uses行的版本标签改掉即可。输入、输出、行为在 v3 中完全不变：

- - uses: gitleaks/gitleaks-action@v2 + - uses: gitleaks/gitleaks-action@v3

v3 的运行时声明可以直接在 action.yml 中确认，using: "node24"表明它已运行在 Node 24 之上，入口文件为dist/index.js。

步骤二：将 actions/checkout 升级到 v6

actions/checkout是 v3 的配套依赖，需要同步升级到 Node 24 发行版（v6）：

- - uses: actions/checkout@v3 # 或 @v4 + - uses: actions/checkout@v6

迁移后的完整工作流长什么样

两步改完后，你的工作流大致如下（完整示例见 README.md）：

name: gitleaks on: pull_request: push: workflow_dispatch: jobs: scan: name: gitleaks runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - uses: gitleaks/gitleaks-action@v3 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

迁移完成后的变化确认：哪些地方没有变

为了让你放心迁移，这里明确列出 v3 中保持不变的部分：

• ✅所有输入（inputs）、输出（outputs）和行为逻辑均无变化
• ✅ 环境变量配置方式完全相同，无需重新设置 Secrets
• ✅ 检测结果、PR 行内评论、SARIF 报告上传、Job Summary 功能照常工作
• ✅ 组织账户（Organization）仍需GITLEAKS_LICENSE，个人账户则不需要

底层实现方面，核心扫描逻辑仍位于 src/gitleaks.js，入口编排逻辑在 src/index.js，报告摘要由 src/summary.js 生成，依赖版本记录在 package.json。发布时通过npm ci && npx ncc build重新构建dist/产物并校验，流程详见 RELEASING.md。

环境变量速查表

迁移后如果顺手想调整行为，以下是全部可选环境变量：

自托管 Runner 用户必读

📌 v3 要求 GitHub Actions runner 版本v2.327.1 或更高：

• GitHub 托管 runner：所有当前托管 runner 均已满足要求，无需任何操作
• 自托管 runner：请务必先升级 runner 版本，再把工作流切到 v3，否则任务会启动失败

迁移常见问题 FAQ

问：迁移需要改业务代码吗？不需要。v3 只升级运行时，输入、输出、行为零变化，改动仅限工作流文件的 2 行。

问：能不能不改？技术上可以在 2026 年 6 月 2 日后通过ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true临时维持，但 2026 年 9 月 16 日 Node 20 被彻底移除后，v2 将彻底无法运行，届时仍会被迫迁移。

问：如何验证 v3 是否正常工作？推一个包含测试密钥的分支或手动触发workflow_dispatch，若能在 PR 中看到行内评论、在 Job 页面看到 Summary，即代表迁移成功。

总结

gitleaks-action v2到v3迁移本质上就是一次Node 24 运行时升级，记住两行改动即可：

1. gitleaks/gitleaks-action@v2→gitleaks/gitleaks-action@v3
2. actions/checkout→actions/checkout@v6

在 2026 年 9 月 16 日之前完成，你的密钥检测流水线将平稳过渡到 Node 24，扫描功能不受任何影响。🚀