GitHub主仓库子模块自动更新Workflow问题求助

数据老陈

2026-7-4

问题背景

我有一个包含多个子模块的主仓库，每次子模块的main分支有推送变更时，都需要手动在主仓库提交PR来更新子模块到最新版本，想通过GitHub Workflow实现自动化。找到一个能在子模块中运行的Workflow，可以自动把变更推送到主仓库的main分支，但添加「检查是否存在已打开的PR：存在则推送更新到该PR，不存在则新建PR」的逻辑后，总是因为远程或本地分支问题失败，提示需要变基或快进合并。

以下是可用的自动推送Workflow代码：

name: Send submodule updates to parent repo

on:
  push:
    branches:
      - main

jobs:
  update:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
        with:
          repository: test/Test-Repo
          token: ${{ secrets.PAT_TOKEN }}
          ref: main
          submodules: true

      - name: Pull & update submodules recursively
        run: |
          git submodule update --init --recursive
          git submodule update --recursive --remote

      - name: Commit
        run: |
          git config user.email "actions@github.com"
          git config user.name "GitHub Actions - update submodules"
          git add --all
          git commit -m "Update submodules" || echo "No changes to commit"
          git push

以及失败的草稿Workflow代码：

name: Send submodule updates to parent repo

on:
  push:
    branches:
      - main

jobs:
  update:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
        with:
          repository: test/Test-Repo
          token: ${{ secrets.PAT_TOKEN }}
          ref: main
          submodules: true

      - name: Pull & update submodules recursively
        run: |
          git submodule update --init --recursive
          git submodule update --recursive --remote

      - name: Set up Git identity
        run: |
          git config user.email "actions@github.com"
          git config user.name "GitHub Actions - update submodules"

      - name: Determine if PR already exists
        id: check_pr
        run: |
          PR_EXISTING=$(curl -s -H "Authorization: Bearer ${{ secrets.PAT_TOKEN }}" \
            "https://api.github.com/repos/test/Test-Repo/pulls?state=open" | \
            jq '.[] | select(.head.ref == "update-submodules") | .number')

          if [ "$PR_EXISTING" != "null" ]; then
            echo "::set-output name=pr_number::$PR_EXISTING"
          fi

      - name: Checkout branch in main repo
        run: |
          BRANCH_NAME="update-submodules"
          git checkout -b $BRANCH_NAME

      - name: Commit and push changes in main repo
        run: |
          git add .
          git commit -m "Update submodule references to the latest main commits"
          if [ -z "${{ steps.check_pr.outputs.pr_number }}" ]; then
            # If no existing PR, open a new one
            git push origin $BRANCH_NAME
            curl -X POST \
              -H "Accept: application/vnd.github.v3+json" \
              -H "Authorization: Bearer ${{ secrets.PAT_TOKEN }}" \
              https://api.github.com/repos/test/Test-Repo/pulls \
              -d "{\"title\":\"Update submodules\",\"head\":\"$BRANCH_NAME\",\"base\":\"main\"}"
          else
            # If existing PR, push to it
            PR_NUMBER="${{ steps.check_pr.outputs.pr_number }}"
            git push origin $BRANCH_NAME
            curl -X PATCH \
              -H "Accept: application/vnd.github.v3+json" \
              -H "Authorization: Bearer ${{ secrets.PAT_TOKEN }}" \
              https://api.github.com/repos/test/Test-Repo/pulls/$PR_NUMBER \
              -d "{\"title\":\"Update submodules\",\"head\":\"$BRANCH_NAME\"}"
          fi

作为GitHub Workflow新手，想请教三个问题：

如何处理合并冲突？
该自动化逻辑应放在submodule还是主仓库中？
当前的逻辑是否接近可行方案？

解答

1. 如何处理合并冲突？

子模块更新引发的合并冲突，本质是主仓库里子模块的提交哈希不一致导致的，分两种场景处理：

自动处理（仅哈希冲突）：如果只是子模块哈希冲突，无主仓库其他文件改动冲突，可在Workflow中添加变基逻辑，确保更新分支基于最新main分支提交：
```
git fetch origin main
git rebase origin/main
```
若变基失败（存在真实文件冲突），Workflow直接终止，触发人工介入。
人工介入：当变基失败时，说明主仓库存在非子模块的文件冲突，Workflow可配置通知（如邮件、团队聊天工具），让开发人员手动解决冲突后重新运行Workflow。

2. 自动化逻辑应放在submodule还是主仓库中？

建议放在子模块仓库，原因如下：

触发逻辑更合理：子模块main分支推送时直接触发更新，贴合“变更源驱动动作”的逻辑，无需在主仓库轮询子模块状态。
权限配置更清晰：子模块的Workflow仅需拥有主仓库的PR/推送权限（通过PAT），无需主仓库额外配置。
扩展性更强：多子模块场景下，每个子模块可独立配置更新Workflow，互不干扰。

若放在主仓库，需设置定时触发或依赖子模块Webhook，配置复杂度更高，且多子模块更新时易出现冲突。

3. 当前逻辑是否接近可行方案？

当前方向正确，但存在几个关键问题导致失败，修复后即可正常运行：

分支同步缺失：创建update-submodules分支前未拉取远程已有分支，导致本地分支与远程不一致，推送失败。需改为：

BRANCH_NAME="update-submodules"
git fetch origin $BRANCH_NAME || true
git checkout -b $BRANCH_NAME origin/$BRANCH_NAME || git checkout -b $BRANCH_NAME

PR检查逻辑错误：原代码中无匹配PR时，PR_EXISTING为空而非null，导致判断失效。修改为：

PR_EXISTING=$(curl -s -H "Authorization: Bearer ${{ secrets.PAT_TOKEN }}" \
  "https://api.github.com/repos/test/Test-Repo/pulls?state=open" | \
  jq -r '.[] | select(.head.ref == "update-submodules") | .number // empty')

if [ -n "$PR_EXISTING" ]; then
  echo "pr_number=$PR_EXISTING" >> $GITHUB_OUTPUT
fi

未拉取最新主分支：更新子模块前未拉取主仓库main分支最新代码，导致基于旧状态更新，推送时出现快进失败。需在更新子模块前执行：
```
git pull origin main
```

修正后的完整Workflow代码

name: Update parent repo submodule reference

on:
  push:
    branches:
      - main

jobs:
  update-parent:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout parent repo
        uses: actions/checkout@v3
        with:
          repository: test/Test-Repo
          token: ${{ secrets.PAT_TOKEN }}
          ref: main
          submodules: true

      - name: Pull latest main branch
        run: git pull origin main

      - name: Update submodules to latest main
        run: |
          git submodule update --init --recursive
          git submodule update --recursive --remote

      - name: Set Git identity
        run: |
          git config user.email "actions@github.com"
          git config user.name "GitHub Actions"

      - name: Check for existing update branch
        run: |
          BRANCH_NAME="update-submodules"
          git fetch origin $BRANCH_NAME || true
          git checkout -b $BRANCH_NAME origin/$BRANCH_NAME || git checkout -b $BRANCH_NAME

      - name: Commit submodule changes
        run: |
          git add .
          git commit -m "Update submodule to latest main: $GITHUB_SHA" || echo "No changes to commit"
          git fetch origin main
          git rebase origin/main || (echo "Rebase failed, conflict needs manual resolution" && exit 1)

      - name: Check for existing PR
        id: check_pr
        run: |
          PR_EXISTING=$(curl -s -H "Authorization: Bearer ${{ secrets.PAT_TOKEN }}" \
            "https://api.github.com/repos/test/Test-Repo/pulls?state=open" | \
            jq -r '.[] | select(.head.ref == "update-submodules") | .number // empty')
          if [ -n "$PR_EXISTING" ]; then
            echo "pr_number=$PR_EXISTING" >> $GITHUB_OUTPUT
          fi

      - name: Push changes and manage PR
        run: |
          BRANCH_NAME="update-submodules"
          git push origin $BRANCH_NAME --force-with-lease
          
          if [ -n "${{ steps.check_pr.outputs.pr_number }}" ]; then
            # Update existing PR
            curl -X PATCH \
              -H "Accept: application/vnd.github.v3+json" \
              -H "Authorization: Bearer ${{ secrets.PAT_TOKEN }}" \
              https://api.github.com/repos/test/Test-Repo/pulls/${{ steps.check_pr.outputs.pr_number }} \
              -d '{"title":"Update submodules to latest main"}'
          else
            # Create new PR
            curl -X POST \
              -H "Accept: application/vnd.github.v3+json" \
              -H "Authorization: Bearer ${{ secrets.PAT_TOKEN }}" \
              https://api.github.com/repos/test/Test-Repo/pulls \
              -d '{"title":"Update submodules to latest main","head":"'$BRANCH_NAME'","base":"main","body":"Automatically generated PR to update submodules to latest main branch commits."}'
          fi

内容的提问来源于stack exchange，提问作者Alan B.

GitHub主仓库子模块自动更新Workflow问题求助

1. 如何处理合并冲突？ #

2. 自动化逻辑应放在submodule还是主仓库中？ #

3. 当前逻辑是否接近可行方案？ #

修正后的完整Workflow代码 #

1. 如何处理合并冲突？

2. 自动化逻辑应放在submodule还是主仓库中？

3. 当前逻辑是否接近可行方案？

修正后的完整Workflow代码