forked from actions/checkout
Checkout V4
此操作将您的仓库检出到 $GITHUB_WORKSPACE 下，以便您的工作流可以访问它。
默认情况下，仅获取触发工作流的 ref/SHA 的单个提交。设置 fetch-depth: 0 可以获取所有分支和标签的所有历史记录。请参考 这里 了解不同事件中 $GITHUB_SHA 指向的提交。
认证令牌会持久化到本地 git 配置中。这使得您的脚本可以运行经过身份验证的 git 命令。该令牌会在作业后清理步骤中被移除。设置 persist-credentials: false 可以选择不保留。
当 Git 2.18 或更高版本不在您的 PATH 中时，将回退到 REST API 来下载文件。
新特性
请参考 发布页面 获取最新的发布说明。
使用方法
• uses: actions/checkout@v4
with:
# 仓库名称及所有者。例如，actions/checkout
# 默认值: ${{ github.repository }}
repository: ''
# 要检出的分支、标签或 SHA。当检出触发工作流的仓库时，默认为该事件的引用或 SHA。
# 否则，使用默认分支。
ref: ''
# 用于获取仓库的个人访问令牌 (PAT)。该 PAT 会配置到本地 git 配置中，使您的脚本可以运行经过身份验证的 git 命令。
# 作业后步骤会移除该 PAT。
#
# 我们建议使用具有最低必要权限的服务账户。此外，在生成新的 PAT 时，请选择最低必要的范围。
#
# [了解有关创建和使用加密机密的更多信息](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
#
# 默认值: ${{ github.token }}
token: ''
# 用于获取仓库的 SSH 密钥。该 SSH 密钥会配置到本地 git 配置中，使您的脚本可以运行经过身份验证的 git 命令。
# 作业后步骤会移除该 SSH 密钥。
#
# 我们建议使用具有最低必要权限的服务账户。
#
# [了解有关创建和使用加密机密的更多信息](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
ssh-key: ''
# 除用户和全局主机密钥数据库之外的已知主机。可以使用 `ssh-keyscan` 工具获取主机的公共 SSH 密钥。例如，`ssh-keyscan github.com`。
# github.com 的公钥始终会隐式添加。
ssh-known-hosts: ''
# 是否执行严格的主机密钥检查。当为 true 时，会在 SSH 命令行中添加 `StrictHostKeyChecking=yes` 和 `CheckHostIP=no` 选项。
# 使用 `ssh-known-hosts` 输入来配置其他主机。
# 默认值: true
ssh-strict: ''
# 连接到远程 SSH 主机时使用的用户。默认值为 'git'。
# 默认值: git
ssh-user: ''
# 是否将令牌或 SSH 密钥配置到本地 git 配置中
# 默认值: true
persist-credentials: ''
# 在 $GITHUB_WORKSPACE 下放置仓库的相对路径
path: ''
# 是否在获取前执行 `git clean -ffdx && git reset --hard HEAD`
# 默认值: true
clean: ''
# 针对给定过滤器进行部分克隆。如果设置了此选项，则会覆盖 sparse-checkout。
# 默认值: null
filter: ''
# 对给定模式进行稀疏检出。每个模式应以换行符分隔。
# 默认值: null
sparse-checkout: ''
# 指定在执行稀疏检出时是否使用 cone 模式。
# 默认值: true
sparse-checkout-cone-mode: ''
# 要获取的提交数量。0 表示所有分支和标签的所有历史记录。
# 默认值: 1
fetch-depth: ''
# 是否获取标签，即使 fetch-depth > 0。
# 默认值: false
fetch-tags: ''
# 获取时是否显示进度状态输出。
# 默认值: true
show-progress: ''
# 是否下载 Git-LFS 文件
# 默认值: false
lfs: ''
# 是否检出子模块：`true` 表示检出子模块，`recursive` 表示递归检出子模块。
#
# 当未提供 `ssh-key` 输入时，以 `git@github.com:` 开头的 SSH URL 会被转换为 HTTPS。
#
# 默认值: false
submodules: ''
# 通过运行 `git config --global --add safe.directory <path>` 将仓库路径添加为 Git 全局配置的安全目录。
# 默认值: true
set-safe-directory: ''
# 尝试克隆的 GitHub 实例的基本 URL，将使用环境默认值从工作流运行的同一实例获取，除非指定。示例 URL 包括 https://github.com 或 https://my-ghes-server.example.com
github-server-url: ''
场景
- 仅获取根文件
- 仅获取根文件和
.github及src文件夹 - 仅获取单个文件
- 获取所有标签和分支的所有历史记录
- 检出不同分支
- 检出 HEAD^
- 并行检出多个仓库
- 嵌套检出多个仓库
- 检出多个私有仓库
- 检出拉取请求的 HEAD 提交而不是合并提交
- 在关闭事件上检出拉取请求
- 使用内置令牌推送提交
- 使用内置令牌向拉取请求推送提交
仅获取根文件
• uses: actions/checkout@v4
with:
sparse-checkout: .
仅获取根文件和 .github 及 src 文件夹
• uses: actions/checkout@v4
with:
sparse-checkout: |
.github
src
仅获取单个文件
• uses: actions/checkout@v4
with:
sparse-checkout: |
README.md
sparse-checkout-cone-mode: false
获取所有标签和分支的所有历史记录
• uses: actions/checkout@v4
with:
fetch-depth: 0
检出不同分支
• uses: actions/checkout@v4
with:
ref: my-branch
检出 HEAD^
• uses: actions/checkout@v4
with:
fetch-depth: 2
• run: git checkout HEAD^
并行检出多个仓库
• name: Checkout
uses: actions/checkout@v4
with:
path: main
• name: Checkout tools repo
uses: actions/checkout@v4
with:
repository: my-org/my-tools
path: my-tools
- 如果您的次要仓库是私有或内部的，您需要添加 Checkout multiple repos (private) 中提到的选项
嵌套检出多个仓库
• name: Checkout
uses: actions/checkout@v4
• name: Checkout tools repo
uses: actions/checkout@v4
with:
repository: my-org/my-tools
path: my-tools
- 如果您的次要仓库是私有或内部的，您需要添加 Checkout multiple repos (private) 中提到的选项
检出多个私有仓库
• name: Checkout
uses: actions/checkout@v4
with:
path: main
• name: Checkout private tools
uses: actions/checkout@v4
with:
repository: my-org/my-private-tools
token: ${{ secrets.GH_PAT }} # `GH_PAT` 是包含您 PAT 的机密
path: my-tools
${{ github.token }}的范围限定在当前仓库，因此如果您想检出其他私有仓库，则需要提供您自己的 PAT。
检出拉取请求的 HEAD 提交而不是合并提交
• uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
在关闭事件上检出拉取请求
on:
pull_request:
branches: [main]
types: [opened, synchronize, closed]
jobs:
build:
runs-on: ubuntu-latest
steps:
◦ uses: actions/checkout@v4
使用内置令牌推送提交
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
◦ uses: actions/checkout@v4
◦ run: |
date > generated.txt
# 注意：以下账户信息在 GHES 上不起作用
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add .
git commit -m "generated"
git push
注意: 用户邮箱为 {user.id}+{user.login}@users.noreply.github.com。请参阅用户 API: https://api.github.com/users/github-actions%5Bbot%5D
使用内置令牌向拉取请求推送提交
在拉取请求触发器中，需要指定 ref，因为 GitHub Actions 默认以分离的 HEAD 模式检出，这意味着它不会默认检出您的分支。
on: pull_request
jobs:
build:
runs-on: ubuntu-latest
steps:
◦ uses: actions/checkout@v4
with:
ref: ${{ github.head_ref }}
◦ run: |
date > generated.txt
# 注意：以下账户信息在 GHES 上不起作用
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add .
git commit -m "generated"
git push
注意: 用户邮箱为 {user.id}+{user.login}@users.noreply.github.com。请参阅用户 API: https://api.github.com/users/github-actions%5Bbot%5D
推荐权限
在 GitHub Actions 工作流中使用 checkout 操作时，建议设置以下 GITHUB_TOKEN 权限以确保正常功能，除非通过 token 或 ssh-key 输入提供了替代身份验证：
permissions:
contents: read
许可证
此项目中的脚本和文档均根据 MIT 许可证 发布