GitHub工作流复用场景下Git Push提交丢失问题排查

问题场景 #

使用GitHub工作流实现下载数据、分析并存储到GitHub的任务，采用主工作流调用子工作流的架构，支持编排执行和手动触发子工作流。目前所有步骤正常，但Git Push环节存在异常：每次提交能推送到GitHub，但后续工作流运行时，之前的提交会消失，最终仅保留最后一次工作流的最新提交。怀疑问题与actions/checkout@main有关，但无法定位具体原因。

相关代码如下：

1. 主工作流 #

name: WORKFLOW-NAME
on:
  schedule:
    - cron:  '0 4 1 * *'
  workflow_dispatch:

jobs:
  JOB1:
    uses: ./.github/workflows/work1.yml

  JOB2:
    needs: JOB1
    uses: ./.github/workflows/work2.yml

  JOB3:
    needs: JOB2
    uses: ./.github/workflows/work3.yml
  
  JOB4:
    needs: JOB2
    uses: ./.github/workflows/work4.yml

2. 子工作流（work3.yml） #

name: JOB3
on:
  workflow_call:
  workflow_dispatch:

jobs:
  JOB3:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@main
      
      - name: Run script
        run:  |
          ./SCRIPTS/script.ps1

3. Git Push脚本（script.ps1） #

### SCRIPT
(...)
### Save to git
git config --local user.email "name@mail.com"
git config --local user.name "Username"
git add .
git commit -m "commit message"
git push origin main -f

问题原因分析 #

• actions/checkout默认行为：actions/checkout@main默认仅拉取最新一次提交，不会克隆完整仓库历史，导致本地仓库处于「分离HEAD」状态，而非在main分支上。
• 强制推送的破坏性：脚本中使用git push origin main -f强制推送，当本地仓库未同步远程最新提交时，强制推送会直接覆盖远程历史，导致之前的提交被丢弃。
• 子工作流独立环境：每个子工作流运行在独立的Runner环境中，checkout时不会拉取之前工作流提交的最新代码，本地仓库始终落后于远程，后续强制推送必然覆盖历史。

解决方案 #

方案1：修改checkout动作，拉取完整历史并切换到目标分支 #

将子工作流中的actions/checkout步骤修改为：

- uses: actions/checkout@main
  with:
    fetch-depth: 0  # 拉取完整仓库历史
    ref: main       # 明确切换到main分支

fetch-depth: 0确保获取所有提交记录，ref: main让本地仓库处于正常分支状态，避免分离HEAD问题。

方案2：推送前同步远程最新代码 #

在脚本的Git提交步骤前，添加拉取远程最新代码的操作，确保本地历史与远程一致：

### Save to git
git config --local user.email "name@mail.com"
git config --local user.name "Username"
git pull origin main  # 拉取远程最新代码，解决历史差异
git add .
git commit -m "commit message"
git push origin main  # 移除-f参数，避免强制覆盖

若拉取时出现冲突，可根据任务场景选择git pull origin main --rebase自动合并，或提前规划文件操作路径避免冲突。

方案3：杜绝无必要的强制推送 #

自动化任务中除非明确需要覆盖历史，否则禁止使用-f参数。普通推送在本地历史落后时会失败，可通过拉取同步解决后再推送，从根源避免历史覆盖风险。

验证步骤 #

1. 修改子工作流的checkout配置，添加fetch-depth: 0和ref: main。
2. 更新脚本，添加git pull origin main并移除git push的-f参数。
3. 手动触发工作流，检查远程仓库提交历史是否完整保留。
4. 多次运行工作流，确认后续提交不会覆盖之前的历史记录。

内容的提问来源于stack exchange，提问作者A-d-r-i