使用GitHub Actions忽略路径时，GITGUARDIAN_API_KEY提示无效API密钥

一、API密钥无效问题排查 #

• 确认仓库Secrets配置：进入仓库的Settings > Secrets and variables > Actions，检查GITGUARDIAN_API_KEY是否存在，值与本地测试的完全一致（无多余空格、拼写错误）。如果是组织级Secrets，需确认仓库有权限访问该变量。
• 检查变量作用域：确保GITGUARDIAN_API_KEY所在的env块属于执行ggshield-action的步骤，而非Job顶层或其他无关步骤，避免变量未正确传递。
• 版本兼容性验证：当前使用的GitGuardian/ggshield-action@v1.15.0可能存在已知的密钥验证问题，尝试升级到最新稳定版（如v1.17.0）测试。
• 本地与Action环境对齐：本地测试用的ggshield版本需与Action内置版本一致，版本差异可能导致密钥逻辑不兼容。

二、正确配置路径忽略 #

要跳过示例文件的扫描，需在ggshield-action的args中添加--exclude参数，使用glob模式指定忽略路径。完整的Action配置示例如下：

name: GitGuardian Secret Scan
on: [push, pull_request]

jobs:
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3.5.1
        with:
          fetch-depth: 0 # 必须配置，确保扫描完整仓库历史

      - name: Run GitGuardian scan
        uses: GitGuardian/ggshield-action@v1.15.0
        with:
          args: secret scan repo --exclude "examples/**" --exclude "docs/sample-keys/**"
        env:
          GITHUB_PUSH_BEFORE_SHA: ${{ github.event.before }}
          GITHUB_PUSH_BASE_SHA: ${{ github.event.base }}
          GITHUB_PULL_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          GITHUB_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
          GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}

• --exclude "examples/**"会忽略examples目录下所有文件及子目录，可根据实际路径调整glob规则。
• fetch-depth: 0是必填项，ggshield需要完整的仓库历史才能执行全量扫描，缺少该配置可能导致扫描异常。

三、验证步骤 #

1. 先修复API密钥问题：将Action调整为上述结构后，触发一次测试运行，确认密钥验证通过。
2. 测试路径忽略：故意在示例文件中保留测试密钥，触发扫描，检查是否不再触发告警。

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