tj-actions/changed-files项目中"Please run actions/checkout before this action"错误分析与解决方案

在使用tj-actions/changed-files这个GitHub Action时，许多开发者会遇到一个看似简单但令人困惑的错误提示："Please run actions/checkout before this action"。这个错误表面上看是因为没有正确执行checkout操作，但实际上可能隐藏着更深层次的原因。

问题现象

当开发者按照官方文档配置工作流时，即使已经添加了actions/checkout步骤，仍然会遇到这个错误提示。典型的错误配置如下：

- name: Checkout
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
- name: Get changed files
  id: changed-files
  uses: tj-actions/changed-files@v45

根本原因分析

经过深入调查，发现这个问题通常与Git的配置和权限相关，特别是在GitHub Actions的容器环境中。主要涉及以下几个关键因素：

1. Git用户配置缺失：在容器环境中，Git需要基本的用户信息才能正常操作
2. 安全目录设置：Git 2.35.2及以上版本引入了安全目录限制，需要显式配置
3. 工作区清理：残留的Git配置可能干扰正常操作

完整解决方案

要彻底解决这个问题，需要以下几个步骤：

- name: Checkout
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
    clean: true  # 确保工作区干净
- name: Config git
  run: |
    # 设置基本的Git用户信息
    git config --global user.email "[e-mail]"
    git config --global user.name "your-username"
    # 添加当前工作目录为安全目录
    git config --global --add safe.directory /__w/workspace/your-repo
- name: Get changed files
  id: changed-files
  uses: tj-actions/changed-files@v45

技术细节解析

1. clean参数：这个参数确保在检出代码前清理工作区，避免残留文件干扰

2. Git用户配置：虽然GitHub Actions中的操作不需要真实的用户信息，但Git命令执行需要这些配置存在

3. safe.directory设置：这是Git 2.35.2引入的安全特性，防止在不受信任的目录中执行Git操作。在容器环境中，工作目录被视为"不受信任"，需要显式添加

最佳实践建议

1. 始终在使用tj-actions/changed-files前添加完整的Git配置步骤
2. 考虑将这些配置封装为一个可重用的复合Action
3. 对于企业环境，可以在自托管Runner的镜像中预配置这些设置
4. 定期更新actions/checkout和tj-actions/changed-files到最新版本

通过理解这些底层原理和采取正确的配置方法，开发者可以避免这个常见的陷阱，确保工作流稳定运行。