Github Actions Workflow开启lfs:true时执行失败求助

问题分析 #

你在自托管Runner上本地已安装Git和Git LFS且路径在系统PATH中，但Actions流水线执行actions/checkout@v4并开启lfs: true时提示找不到git-lfs，重复安装可解决但希望避免重复操作。核心矛盾是本地用户环境能找到Git LFS，但Runner运行环境无法定位。

解决方案 #

1. 先排查Runner运行环境的实际状态 #

在Workflow中添加Debug步骤，确认Runner的运行用户、文件路径和环境变量：

jobs:
  build:
    runs-on: {self_hosted_runner_name}
    steps:
      - name: Debug Runner Environment
        run: |
          # 查看当前运行用户
          whoami
          # 检查Git LFS文件是否存在
          ls -l /usr/bin/git-lfs || ls -l ~/.local/bin/git-lfs
          # 打印当前PATH
          echo $PATH
      - uses: actions/checkout@v4
        with:
          lfs: true

执行后根据输出判断：

• 如果whoami显示的用户不是你本地登录的username，说明Runner用独立用户运行，该用户环境下可能未安装Git LFS
• 如果ls命令在/usr/bin找不到，但在~/.local/bin找到，说明Git LFS是用户级安装，未全局生效

2. 针对性解决 #

情况A：Git LFS为用户级安装（仅当前用户可访问）

直接在checkout动作中指定Git LFS的绝对路径：

- uses: actions/checkout@v4
  with:
    lfs: true
    # 替换为Debug步骤中找到的Git LFS实际路径
    git-lfs-path: /home/username/.local/bin/git-lfs

情况B：Runner用独立用户运行（如github-runner）

登录Runner服务器，切换到Runner运行用户，安装Git LFS或复制已有文件到全局路径：

# 切换到Runner用户
sudo su - github-runner
# 安装Git LFS（仅需一次）
git lfs install --system
# 或者复制已安装的文件到全局目录
sudo cp /home/username/.local/bin/git-lfs /usr/bin/
sudo chmod +x /usr/bin/git-lfs

情况C：PATH环境变量未包含Git LFS路径

在自托管Runner的配置文件中添加PATH：

1. 找到Runner安装目录下的.env文件（通常在/home/github-runner/actions-runner/.env）
2. 添加一行：

PATH="$PATH:/home/username/.local/bin"

3. 重启Runner服务：

sudo systemctl restart actions.runner.<your-repo>.service

3. 验证 #

修改Workflow后重新执行，确认checkout步骤可正常拉取LFS文件。

内容的提问来源于stack exchange，提问作者Ajay