📌 项目地址：actions/checkout | ⭐ 8,123 颗星 | 🔧 TypeScript | 📜 未标注
项目是什么
actions/checkout 是 GitHub Actions 官方提供的 Action，它负责在 workflow 运行环境中将仓库代码检出到 $GITHUB_WORKSPACE 目录下，使得后续步骤可以直接访问和操作代码。它是绝大多数 GitHub Actions 工作流的第一个步骤，也是使用最广泛的 Action 之一（Star 数 8123）。
核心功能与版本演进
这个 Action 的核心逻辑很简单：根据触发 workflow 的事件（push、pull_request 等）确定的 git ref 或 SHA，执行 git fetch 和 git checkout。默认只获取单个 commit（浅克隆），以减少执行时间和存储消耗。通过设置 fetch-depth: 0 可以获取完整的 git 历史、所有分支和标签。
从 v4 到 v7，该项目持续改进：
- v4：引入了
fetch-depth和persist-credentials等基本配置，并支持在没有 Git 2.18+ 时使用 REST API 下载文件。 - v5：升级到 node24 运行时，要求 Actions Runner v2.327.1+。
- v6：改进了凭证安全性：
persist-credentials不再将 token 写入.git/config，而是存储在$RUNNER_TEMP下的独立文件中，避免在脚本中意外暴露。同时支持从 Docker 容器 action 中执行经过身份验证的 git 命令（需要 Runner v2.329.0+）。 - v7：迁移到 ESM 模块系统；新增
allow-unsafe-pr-checkout输入，默认拒绝在pull_request_target或workflow_run触发时检出 fork 的 PR 代码，防止“pwn request”安全漏洞。
实际用法（基于 README 和官方文档）
最常见的用法就是一行 uses: actions/checkout@v7，通常放在 workflow 的第一步：
steps:
- uses: actions/checkout@v7
如果需要更多控制，可添加输入参数，以下参数均在 README 中提及：
fetch-depth: 0—— 获取完整历史（默认只获取最新 commit）persist-credentials: false—— 不持久化 token（默认 true，v6 起存储到临时文件）ref: 'main'—— 指定分支或标签path: ./my-repo—— 检出到子目录allow-unsafe-pr-checkout: true—— 仅在充分了解风险后，允许在pull_request_target事件中检出 fork 的 PR 代码
示例：获取所有历史并检出到子目录
- uses: actions/checkout@v7
with:
fetch-depth: 0
path: 'my-code'
安全注意事项（专属于该项目的场景）
actions/checkout v7 引入了一个对安全至关重要的变更：当工作流由 pull_request_target 或 workflow_run 触发时，默认拒绝检出 fork 的 PR 代码。这是因为这两个触发器使用基础仓库的 GITHUB_TOKEN、secrets 和 runner 访问权限，如果允许检出并执行 fork 的代码，攻击者可以轻易窃取令牌或注入恶意脚本（即“pwn request”漏洞）。
要启用 fork PR 检出，必须：
1. 在主 workflow 文件中设置 allow-unsafe-pr-checkout: true
2. 在代码审查时仔细确认 PR 来源可信，并遵循 GitHub 官方指南
这一设计是 actions/checkout 区别于社区类似工具（如 actions/checkout 本身就是官方方案，不存在替代品）的独特之处。它不只是一个检出动作，还承担了安全防线角色。
版本兼容性
- 使用 v7 需要 GitHub Actions Runner v2.327.1 或更高版本（因为 node24 运行时）。
- 在 Docker 容器 action 中运行经过身份验证的 git 命令（如
git push），需要 Runner v2.329.0+（v6 以上版本）。 - 如果 runner 环境中不存在 Git 2.18+，则自动回退到 REST API 下载文件（v4 描述，后续版本继承此行为）。
建议始终使用最新的大版本（当前为 v7），以获取安全修复和最新特性。
许可证与贡献
本项目遵循 MIT 许可证。注意：官方声明目前不接受外部贡献，专注于策略性方向。问题反馈可前往 GitHub Community Discussions 中进行。