pre-commit-terraform 项目在 GitHub Actions 中的 Docker 容器使用指南

在 pre-commit-terraform 项目中，开发者经常会遇到在 GitHub Actions 中使用 Docker 容器运行 pre-commit 检查时出现的 git 权限问题。本文将深入分析问题原因并提供完整的解决方案。

问题现象分析

当在 GitHub Actions 工作流中使用 pre-commit-terraform 的 Docker 镜像时，用户会遇到以下错误提示：

An error has occurred: FatalError: git failed. Is it installed, and are you in a Git repository directory?

这个错误看似是 git 命令执行失败，但实际上是由于 Git 2.35.2 版本引入的安全机制导致的。Git 会检查仓库目录的所有权，如果检测到可疑的所有权关系，就会拒绝操作。

根本原因

Git 的安全机制会检查以下条件：

1. 工作目录的所有者与当前用户是否匹配
2. 工作目录是否在用户的主目录下
3. 工作目录是否被明确标记为安全目录

在 GitHub Actions 的容器环境中，工作目录 /__w/repo-name/repo-name 的所有权与容器内用户不匹配，因此触发了 Git 的安全机制。

解决方案

完整的工作流配置

以下是经过验证的可靠解决方案，可以直接用于生产环境：

name: pre-commit

on:
  pull_request:
  push:
    branches: [main]

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/antonbabenko/pre-commit-terraform:latest
    steps:
    - uses: actions/checkout@v4
    - name: 安装必要依赖
      shell: bash
      run: |
        apk --no-cache add tar
    - uses: actions/cache@v4
      with:
        path: ~/.cache/pre-commit
        key: pre-commit-3|${{ hashFiles('.pre-commit-config.yaml') }}
    - shell: bash
      run: |
        git config --global --add safe.directory $GITHUB_WORKSPACE
        pre-commit run --show-diff-on-failure --color=always

关键步骤解析

1. 设置安全目录：通过 git config --global --add safe.directory $GITHUB_WORKSPACE 命令将工作目录标记为安全目录，这是解决问题的核心步骤。

2. 依赖管理：由于 pre-commit-terraform 镜像基于 Alpine Linux，需要额外安装 tar 等基础工具。

3. 缓存优化：使用 actions/cache 缓存 pre-commit 的缓存目录，可以显著提高后续运行的效率。

进阶建议

1. 镜像版本固定：建议使用具体的镜像版本标签而非 latest，以确保构建的可重复性。

2. 多阶段检查：可以考虑将检查分为多个阶段，先检查格式问题，再运行更耗时的静态分析。

3. 自动修复推送：配置 SSH 密钥，允许工作流自动推送修复后的代码变更。

总结

在容器化环境中使用 pre-commit 工具链时，理解 Git 的安全机制至关重要。通过正确配置安全目录和优化工作流，可以充分发挥 pre-commit-terraform 在 CI/CD 流程中的价值。本文提供的解决方案已经在多个实际项目中得到验证，能够稳定可靠地运行各种 Terraform 相关的预提交检查。