forked from actions/checkout
330 lines
9.9 KiB
Markdown
330 lines
9.9 KiB
Markdown
[](https://github.com/actions/checkout/actions/workflows/test.yml)
|
|
|
|
# Checkout V4
|
|
|
|
此操作将您的仓库检出到 `$GITHUB_WORKSPACE` 下，以便您的工作流可以访问它。
|
|
|
|
默认情况下，仅获取触发工作流的 ref/SHA 的单个提交。设置 `fetch-depth: 0` 可以获取所有分支和标签的所有历史记录。请参考 [这里](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows) 了解不同事件中 `$GITHUB_SHA` 指向的提交。
|
|
|
|
认证令牌会持久化到本地 git 配置中。这使得您的脚本可以运行经过身份验证的 git 命令。该令牌会在作业后清理步骤中被移除。设置 `persist-credentials: false` 可以选择不保留。
|
|
|
|
当 Git 2.18 或更高版本不在您的 PATH 中时，将回退到 REST API 来下载文件。
|
|
|
|
# 新特性
|
|
|
|
请参考 [发布页面](https://github.com/actions/checkout/releases/latest) 获取最新的发布说明。
|
|
|
|
# 使用方法
|
|
|
|
<!-- start usage -->
|
|
```yaml
|
|
• 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: ''
|
|
```
|
|
<!-- end usage -->
|
|
|
|
# 场景
|
|
|
|
- [仅获取根文件](#Fetch-only-the-root-files)
|
|
- [仅获取根文件和 `.github` 及 `src` 文件夹](#Fetch-only-the-root-files-and-github-and-src-folder)
|
|
- [仅获取单个文件](#Fetch-only-a-single-file)
|
|
- [获取所有标签和分支的所有历史记录](#Fetch-all-history-for-all-tags-and-branches)
|
|
- [检出不同分支](#Checkout-a-different-branch)
|
|
- [检出 HEAD^](#Checkout-HEAD)
|
|
- [并行检出多个仓库](#Checkout-multiple-repos-side-by-side)
|
|
- [嵌套检出多个仓库](#Checkout-multiple-repos-nested)
|
|
- [检出多个私有仓库](#Checkout-multiple-repos-private)
|
|
- [检出拉取请求的 HEAD 提交而不是合并提交](#Checkout-pull-request-HEAD-commit-instead-of-merge-commit)
|
|
- [在关闭事件上检出拉取请求](#Checkout-pull-request-on-closed-event)
|
|
- [使用内置令牌推送提交](#Push-a-commit-using-the-built-in-token)
|
|
- [使用内置令牌向拉取请求推送提交](#Push-a-commit-to-a-PR-using-the-built-in-token)
|
|
|
|
## 仅获取根文件
|
|
|
|
```yaml
|
|
• uses: actions/checkout@v4
|
|
|
|
with:
|
|
sparse-checkout: .
|
|
```
|
|
|
|
## 仅获取根文件和 `.github` 及 `src` 文件夹
|
|
|
|
```yaml
|
|
• uses: actions/checkout@v4
|
|
|
|
with:
|
|
sparse-checkout: |
|
|
.github
|
|
src
|
|
```
|
|
|
|
## 仅获取单个文件
|
|
|
|
```yaml
|
|
• uses: actions/checkout@v4
|
|
|
|
with:
|
|
sparse-checkout: |
|
|
README.md
|
|
sparse-checkout-cone-mode: false
|
|
```
|
|
|
|
## 获取所有标签和分支的所有历史记录
|
|
|
|
```yaml
|
|
• uses: actions/checkout@v4
|
|
|
|
with:
|
|
fetch-depth: 0
|
|
```
|
|
|
|
## 检出不同分支
|
|
|
|
```yaml
|
|
• uses: actions/checkout@v4
|
|
|
|
with:
|
|
ref: my-branch
|
|
```
|
|
|
|
## 检出 HEAD^
|
|
|
|
```yaml
|
|
• uses: actions/checkout@v4
|
|
|
|
with:
|
|
fetch-depth: 2
|
|
• run: git checkout HEAD^
|
|
|
|
```
|
|
|
|
## 并行检出多个仓库
|
|
|
|
```yaml
|
|
• 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)](#Checkout-multiple-repos-private) 中提到的选项
|
|
|
|
## 嵌套检出多个仓库
|
|
|
|
```yaml
|
|
• 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)](#Checkout-multiple-repos-private) 中提到的选项
|
|
|
|
## 检出多个私有仓库
|
|
|
|
```yaml
|
|
• 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](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)。
|
|
|
|
## 检出拉取请求的 HEAD 提交而不是合并提交
|
|
|
|
```yaml
|
|
• uses: actions/checkout@v4
|
|
|
|
with:
|
|
ref: ${{ github.event.pull_request.head.sha }}
|
|
```
|
|
|
|
## 在关闭事件上检出拉取请求
|
|
|
|
```yaml
|
|
on:
|
|
pull_request:
|
|
branches: [main]
|
|
types: [opened, synchronize, closed]
|
|
jobs:
|
|
build:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
◦ uses: actions/checkout@v4
|
|
|
|
```
|
|
|
|
## 使用内置令牌推送提交
|
|
|
|
```yaml
|
|
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 模式检出，这意味着它不会默认检出您的分支。
|
|
|
|
```yaml
|
|
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` 输入提供了替代身份验证：
|
|
|
|
```yaml
|
|
permissions:
|
|
contents: read
|
|
```
|
|
|
|
# 许可证
|
|
|
|
此项目中的脚本和文档均根据 [MIT 许可证](LICENSE) 发布 |