Checkout v7

新增功能

• 更安全的分支拉取请求处理：当工作流由 pull_request_target 或 workflow_run 触发时，checkout 现在默认拒绝检出分支拉取请求的代码。这些触发器使用基础仓库的 GITHUB_TOKEN、密钥和运行器访问权限运行，执行分支代码通常会导致“pwn request”漏洞。
  • 在审查风险后如需选择启用，请设置新的 allow-unsafe-pr-checkout: true 输入参数。
• 将 actions/checkout 迁移到 ESM，以支持新版本的 @actions/* 包。
• 更新了直接和间接依赖项，包括针对已知漏洞的安全修复。

Checkout v6

新增功能

• 增强的凭据安全性：persist-credentials 现在将凭据存储在 $RUNNER_TEMP 下的单独文件中，而不是直接存储在 .git/config 中
• 无需更改工作流 — git fetch、git push 等命令将继续自动工作
• 从Docker 容器操作运行经过身份验证的 git 命令需要 Actions Runner v2.329.0 或更高版本

Checkout v5

新增功能

• 更新到 node24 运行时
  • 这要求运行的 Actions Runner 版本至少为 v2.327.1。

Checkout v4

此操作会将您的仓库检出到 $GITHUB_WORKSPACE 下，以便您的工作流可以访问它。

默认情况下，仅获取触发工作流的 ref/SHA 的单个提交。设置 fetch-depth: 0 可获取所有分支和标签的完整历史记录。请参考此处了解不同事件中 $GITHUB_SHA 指向哪个提交。

身份验证令牌会持久化到本地 git 配置中。这使您的脚本能够运行经过身份验证的 git 命令。该令牌会在作业后清理期间被移除。设置 persist-credentials: false 可选择退出此功能。

当 PATH 中没有 Git 2.18 或更高版本时，将回退到 REST API 来下载文件。

注意事项

感谢您对本 GitHub Action 的关注，不过目前我们暂不接受贡献。

我们将继续把资源集中在那些能帮助客户取得成功并简化开发者工作的战略领域。尽管 GitHub Actions 仍是这一愿景的关键组成部分，但我们正将资源分配到 Actions 的其他领域，因此目前暂不接受对本仓库的贡献。GitHub 公开路线图是了解我们正在开发的功能及其所处阶段的最佳途径。

为了更好地引导与 GitHub Actions 相关的请求，我们将采取以下措施：

1. 我们会将问题和支持请求引导至我们的 社区讨论区。

2. 高优先级漏洞可通过社区讨论区报告，或者您也可以向我们的支持团队报告：https://support.github.com/contact/bug-report。

3. 安全问题应按照我们的 security.md 进行处理。

在此期间，我们仍将为本项目提供安全更新，并修复重大的破坏性变更。

欢迎您继续在本仓库中提交漏洞报告。

新增内容

最新发布说明请参考 发布页面。

用法

- uses: actions/checkout@v7
  with:
    # Repository name with owner. For example, actions/checkout
    # Default: ${{ github.repository }}
    repository: ''

    # The branch, tag or SHA to checkout. When checking out the repository that
    # triggered a workflow, this defaults to the reference or SHA for that event.
    # Otherwise, uses the default branch.
    ref: ''

    # Personal access token (PAT) used to fetch the repository. The PAT is configured
    # with the local git config, which enables your scripts to run authenticated git
    # commands. The post-job step removes the PAT.
    #
    # We recommend using a service account with the least permissions necessary. Also
    # when generating a new PAT, select the least scopes necessary.
    #
    # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    #
    # Default: ${{ github.token }}
    token: ''

    # SSH key used to fetch the repository. The SSH key is configured with the local
    # git config, which enables your scripts to run authenticated git commands. The
    # post-job step removes the SSH key.
    #
    # We recommend using a service account with the least permissions necessary.
    #
    # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    ssh-key: ''

    # Known hosts in addition to the user and global host key database. The public SSH
    # keys for a host may be obtained using the utility `ssh-keyscan`. For example,
    # `ssh-keyscan github.com`. The public key for github.com is always implicitly
    # added.
    ssh-known-hosts: ''

    # Whether to perform strict host key checking. When true, adds the options
    # `StrictHostKeyChecking=yes` and `CheckHostIP=no` to the SSH command line. Use
    # the input `ssh-known-hosts` to configure additional hosts.
    # Default: true
    ssh-strict: ''

    # The user to use when connecting to the remote SSH host. By default 'git' is
    # used.
    # Default: git
    ssh-user: ''

    # Whether to configure the token or SSH key with the local git config
    # Default: true
    persist-credentials: ''

    # Relative path under $GITHUB_WORKSPACE to place the repository
    path: ''

    # Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching
    # Default: true
    clean: ''

    # Partially clone against a given filter. Overrides sparse-checkout if set.
    # Default: null
    filter: ''

    # Do a sparse checkout on given patterns. Each pattern should be separated with
    # new lines.
    # Default: null
    sparse-checkout: ''

    # Specifies whether to use cone-mode when doing a sparse checkout.
    # Default: true
    sparse-checkout-cone-mode: ''

    # Number of commits to fetch. 0 indicates all history for all branches and tags.
    # Default: 1
    fetch-depth: ''

    # Whether to fetch tags, even if fetch-depth > 0.
    # Default: false
    fetch-tags: ''

    # Whether to show progress status output when fetching.
    # Default: true
    show-progress: ''

    # Whether to download Git-LFS files
    # Default: false
    lfs: ''

    # Whether to checkout submodules: `true` to checkout submodules or `recursive` to
    # recursively checkout submodules.
    #
    # When the `ssh-key` input is not provided, SSH URLs beginning with
    # `git@github.com:` are converted to HTTPS.
    #
    # Default: false
    submodules: ''

    # Add repository path as safe.directory for Git global config by running `git
    # config --global --add safe.directory <path>`
    # Default: true
    set-safe-directory: ''

    # The base URL for the GitHub instance that you are trying to clone from, will use
    # environment defaults to fetch from the same instance that the workflow is
    # running from unless specified. Example URLs are https://github.com or
    # https://my-ghes-server.example.com
    github-server-url: ''

    # Required to check out fork pull request code from a workflow triggered by
    # `pull_request_target` or `workflow_run`. These workflows run with the base
    # repository's GITHUB_TOKEN, secrets, default-branch cache scope, and runner
    # access; fetching and executing a fork's code in that trusted context commonly
    # leads to "pwn request" vulnerabilities. Set to `true` only after reviewing the
    # risks at https://gh.io/securely-using-pull_request_target.
    # Default: false
    allow-unsafe-pr-checkout: ''

场景

• Checkout V5
  • 新增功能
• Checkout V4
  • 注意事项
• 新增功能
• 使用方法
• 场景
  • 仅获取根目录文件
  • 仅获取根目录文件以及 .github 和 src 文件夹
  • 仅获取单个文件
  • 获取所有标签和分支的完整历史记录
  • 检出不同的分支
  • 检出 HEAD^
  • 检出多个仓库（并排）
  • 检出多个仓库（嵌套）
  • 检出多个仓库（私有）
  • 检出拉取请求的 HEAD 提交而非合并提交
  • 在关闭事件时检出拉取请求
  • 使用内置令牌推送提交
  • 使用内置令牌向拉取请求推送提交
• 推荐权限
• 许可证

仅获取根目录文件

- uses: actions/checkout@v7
  with:
    sparse-checkout: .

仅拉取根文件以及 .github 和 src 文件夹

- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      .github
      src

仅拉取单个文件

- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      README.md
    sparse-checkout-cone-mode: false

获取所有标签和分支的完整历史记录

- uses: actions/checkout@v7
  with:
    fetch-depth: 0

检出不同的分支

- uses: actions/checkout@v7
  with:
    ref: my-branch

检出 HEAD^

- uses: actions/checkout@v7
  with:
    fetch-depth: 2
- run: git checkout HEAD^

检出多个仓库（并排）

- name: Checkout
  uses: actions/checkout@v7
  with:
    path: main

- name: Checkout tools repo
  uses: actions/checkout@v7
  with:
    repository: my-org/my-tools
    path: my-tools

• 如果您的次要仓库是私有或内部仓库，则需要添加检出多个仓库（私有）中提到的选项

检出多个仓库（嵌套）

- name: Checkout
  uses: actions/checkout@v7

- name: Checkout tools repo
  uses: actions/checkout@v7
  with:
    repository: my-org/my-tools
    path: my-tools

• 如果您的次要仓库是私有或内部仓库，则需要添加 检出多个仓库（私有） 中提到的选项

检出多个仓库（私有）

- name: Checkout
  uses: actions/checkout@v7
  with:
    path: main

- name: Checkout private tools
  uses: actions/checkout@v7
  with:
    repository: my-org/my-private-tools
    token: ${{ secrets.GH_PAT }} # `GH_PAT` is a secret that contains your PAT
    path: my-tools

• ${{ github.token }} 的作用域限定为当前仓库，因此如果您想要检出另一个私有仓库，则需要提供您自己的 PAT。

检出拉取请求的 HEAD 提交而非合并提交

- uses: actions/checkout@v7
  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@v7

使用内置令牌推送提交

on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: |
          date > generated.txt
          # Note: the following account information will not work on 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[bot]

使用内置令牌向 PR 推送提交

在拉取请求触发器中，ref 是必需的，因为 GitHub Actions 会以分离 HEAD 模式检出，这意味着它默认不会检出您的分支。

on: pull_request
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.head_ref }}
      - run: |
          date > generated.txt
          # Note: the following account information will not work on 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[bot]

推荐权限

在 GitHub Actions 工作流中使用 checkout Action 时，建议设置以下 GITHUB_TOKEN 权限以确保功能正常，除非通过 token 或 ssh-key 输入提供了替代身份验证：

permissions:
  contents: read

许可协议

本项目中的脚本和文档均根据 MIT 许可协议 发布。