如何通过GitHub Actions同步gh-pages到main分支编译Sass部署GitHub Pages

核心改进逻辑 #

• 全程不删除gh-pages分支，彻底规避GitHub Pages自动重置部署源的问题
• 用硬重置方案实现gh-pages分支和main分支内容完全同步，确保无旧的生成文件残留
• 编译环节增加确定性配置，保证相同源码每次编译输出的CSS完全一致

完整工作流代码 #

name: Compile Sass & Deploy to gh-pages

on:
  push:
    branches:
      - main

jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout full repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 拉取完整提交历史，支持分支操作
          submodules: true

      - name: Switch to gh-pages branch and sync with main
        run: |
          git config --local user.email 'action@github.com'
          git config --local user.name 'GitHub Action'
          git checkout gh-pages
          git reset --hard origin/main # 完全覆盖gh-pages内容为main分支最新状态

      - name: Compile Sass to CSS (deterministic build)
        uses: gha-utilities/sass-build@v0.4.5
        with:
          source: styles/index.scss
          destination: styles/index.css
          args: --style=compressed --no-source-map # 固定编译参数，保证输出一致性

      - name: Commit and push changes
        run: |
          git add styles/*
          # 仅当有变更时执行提交，避免工作流报错
          if ! git diff --staged --quiet; then
            git commit -m "chore: compile Sass from main commit ${{ github.sha }}"
            git push origin gh-pages --force # 强制推送重置后的分支
          fi

关键说明 #

• 原来的删除分支方案会触发GitHub Pages的部署源自动重置机制，本方案全程保留gh-pages分支，完全避免该问题
• git reset --hard origin/main操作会将gh-pages分支的所有文件完全替换为main分支的最新内容，比rebase操作更稳定，无需处理冲突，也能保证无任何旧文件残留
• CI环境中rebase操作失败的核心原因是默认浅克隆没有完整的提交历史，本方案设置fetch-depth: 0拉取全量历史，也可以支持rebase操作，但硬重置方案更适合该场景
• 增加变更判断逻辑后，非样式代码的推送不会生成空提交，也不会导致工作流运行失败

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