多客户端Terraform仓库+GitHub Actions部署最佳实践咨询

一、保持单仓库结构（优先推荐，适合同团队、客户端数量不多的场景） #

核心优势 #

• 代码集中管理，模块与客户端的版本一致性易保障，变更可关联追踪
• Workflow配置更简洁，无需跨仓库拉取的额外步骤
• 权限、分支规则统一维护，降低管理成本

实现步骤 #

通过git diff识别变更路径，动态决定要构建的客户端：

1. 编写触发规则，监听Modules/和ClientSection-*/路径的提交
2. 先执行前置作业，判断是模块变更（需全量构建）还是单个客户端变更（仅构建对应客户端）
3. 用矩阵作业批量执行构建逻辑

示例Workflow代码

name: Client Environment Build
on:
  push:
    paths:
      - 'Modules/**'
      - 'ClientSection-*/**'

jobs:
  # 第一步：确定要构建的客户端列表
  determine-targets:
    runs-on: ubuntu-latest
    outputs:
      clients: ${{ steps.set-targets.outputs.clients }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          fetch-depth: 2 # 必须获取最近两次提交，用于对比变更路径

      - name: Generate target client list
        id: set-targets
        run: |
          # 获取本次提交变更的所有文件路径
          CHANGED_FILES=$(git diff --name-only HEAD^ HEAD)
          
          # 检查是否涉及模块目录变更
          if echo "$CHANGED_FILES" | grep -q "^Modules/"; then
            # 模块变更：取所有ClientSection目录
            CLIENTS=$(ls -d ClientSection-* | tr '\n' ',' | sed 's/,$//')
          else
            # 仅客户端变更：提取变更对应的ClientSection目录
            CLIENTS=$(echo "$CHANGED_FILES" | grep -o "^ClientSection-[^/]*" | sort -u | tr '\n' ',' | sed 's/,$//')
          fi
          
          echo "clients=$CLIENTS" >> "$GITHUB_OUTPUT"

  # 第二步：批量构建目标客户端
  build-clients:
    needs: determine-targets
    runs-on: ubuntu-latest
    strategy:
      matrix:
        # 将字符串转为JSON数组，用于矩阵作业
        client: ${{ fromJson('["' + replace(needs.determine-targets.outputs.clients, ',', '","') + '"]') }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Build ${{ matrix.client }} environment
        working-directory: ${{ matrix.client }}
        run: |
          # 替换为你的Terraform构建命令
          terraform init
          terraform plan
          # terraform apply -auto-approve # 按需启用自动部署

注意事项 #

• fetch-depth: 2不可省略，否则无法对比变更路径
• 若客户端数量过多，可在strategy中添加max-parallel限制并行作业数

二、拆分多仓库（适合跨团队、客户端独立管理的场景） #

适用场景 #

• 客户端分属不同团队，需要独立权限、版本周期
• 客户端代码量极大，单仓库体积影响操作性能

核心优势 #

• 客户端完全隔离，各自的Workflow、权限、分支规则独立
• 模块仓库可单独打版本Tag，客户端按需指定模块版本，灵活性更高

实现步骤 #

1. 模块仓库单独维护，通过Git Tag标记稳定版本（如v1.0.0）
2. 客户端仓库配置两种触发逻辑：自身代码提交触发构建；模块仓库更新时通过repository_dispatch触发构建

模块仓库Workflow（触发所有客户端更新）

name: Notify Clients on Module Update
on:
  push:
    paths:
      - '**'
    branches:
      - main # 仅主分支更新时触发通知

jobs:
  notify-clients:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Client 1 Build
        uses: peter-evans/repository-dispatch@v2
        with:
          token: ${{ secrets.PAT_WITH_REPO_ACCESS }}
          repository: my-org/ClientSection-1
          event-type: module-update

      - name: Trigger Client 2 Build
        uses: peter-evans/repository-dispatch@v2
        with:
          token: ${{ secrets.PAT_WITH_REPO_ACCESS }}
          repository: my-org/ClientSection-2
          event-type: module-update
      # 新增客户端时需手动添加对应步骤

客户端仓库Workflow

name: Build Environment
on:
  push:
    branches:
      - main
  repository_dispatch:
    types: [module-update] # 监听模块仓库的通知事件

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout client code
        uses: actions/checkout@v3
        with:
          path: client

      - name: Checkout modules
        uses: actions/checkout@v3
        with:
          repository: my-org/modules
          path: modules
          ref: v1.0.0 # 指定模块版本，避免拉取不稳定的开发分支

      - name: Build environment
        working-directory: client
        run: |
          terraform init -from-module=../modules
          terraform plan

注意事项 #

• 需要生成带仓库访问权限的PAT（个人访问令牌），用于跨仓库触发repository_dispatch
• 模块版本建议用Tag而非分支，避免客户端意外引入未测试的变更
• 维护成本较高，新增客户端时需更新模块仓库的通知列表

三、最优方案选择 #

• 若客户端数量较少（N<10）、属于同一团队管理，优先选单仓库方案：配置简单、维护成本低，变更追踪更直观
• 若客户端跨团队、需独立权限或数量极多，再考虑拆分多仓库，可配合GitHub团队权限管理，或用Terraform Registry托管模块（替代直接拉取仓库），提升模块引用的便捷性

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