From 4aa177ed37a5795e0640d9fd2c4b13c49fd0e443 Mon Sep 17 00:00:00 2001
From: Syngnat <yangguofeng919@gmail.com>
Date: Fri, 6 Mar 2026 11:05:27 +0800
Subject: [PATCH] =?UTF-8?q?=20=F0=9F=94=A7=20chore(branch-sync):=20?=
 =?UTF-8?q?=E8=A1=A5=E5=85=85=20main=20=E5=9B=9E=E7=81=8C=20dev=20?=
 =?UTF-8?q?=E6=9D=83=E9=99=90=E5=89=8D=E7=BD=AE=E6=9D=A1=E4=BB=B6=E5=B9=B6?=
 =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E5=A4=B1=E8=B4=A5=E5=91=8A=E8=AD=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/sync-main-to-dev.yml | 37 +++++++++++++++++++++-----
 CONTRIBUTING.md                        |  1 +
 CONTRIBUTING.zh-CN.md                  |  1 +
 3 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/sync-main-to-dev.yml b/.github/workflows/sync-main-to-dev.yml
index 8a4028b..c46cbcf 100644
--- a/.github/workflows/sync-main-to-dev.yml
+++ b/.github/workflows/sync-main-to-dev.yml
@@ -49,6 +49,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
+          echo "permission_blocked=false" >> "$GITHUB_OUTPUT"
           existing_number="$(gh pr list --base dev --head main --state open --json number --jq '.[0].number // empty')"
 
           if [ -n "${existing_number}" ]; then
@@ -58,6 +59,7 @@ jobs:
             echo "created=false" >> "$GITHUB_OUTPUT"
           else
             body_file="$(mktemp)"
+            error_file="$(mktemp)"
             {
               echo "## 自动回灌：\`main -> dev\`"
               echo
@@ -68,14 +70,28 @@ jobs:
               echo "- 无冲突：直接合并该 PR（建议 \`Merge commit\`）"
               echo "- 有冲突：在该 PR 内解决冲突后再合并"
             } > "${body_file}"
-            pr_url="$(gh pr create \
+
+            if pr_url="$(gh pr create \
               --base dev \
               --head main \
               --title "🔁 chore(sync): 回灌 main 到 dev" \
-              --body-file "${body_file}")"
-            pr_number="${pr_url##*/}"
-            echo "已创建同步 PR：#${pr_number}"
-            echo "created=true" >> "$GITHUB_OUTPUT"
+              --body-file "${body_file}" 2>"${error_file}")"; then
+              pr_number="${pr_url##*/}"
+              echo "已创建同步 PR：#${pr_number}"
+              echo "created=true" >> "$GITHUB_OUTPUT"
+            else
+              error_message="$(tr '\n' ' ' < "${error_file}")"
+              if printf '%s' "${error_message}" | grep -Fq "GitHub Actions is not permitted to create or approve pull requests"; then
+                echo "::warning::仓库未开启“Allow GitHub Actions to create and approve pull requests”，已跳过自动创建同步 PR。"
+                echo "permission_blocked=true" >> "$GITHUB_OUTPUT"
+                echo "created=false" >> "$GITHUB_OUTPUT"
+                echo "pr_number=" >> "$GITHUB_OUTPUT"
+                echo "pr_url=" >> "$GITHUB_OUTPUT"
+                exit 0
+              fi
+              echo "::error::创建同步 PR 失败：${error_message}"
+              exit 1
+            fi
           fi
 
           echo "pr_number=${pr_number}" >> "$GITHUB_OUTPUT"
@@ -83,7 +99,7 @@ jobs:
 
       - name: 检查合并状态
         id: merge_state
-        if: steps.diff_check.outputs.has_changes == 'true'
+        if: steps.diff_check.outputs.has_changes == 'true' && steps.sync_pr.outputs.permission_blocked != 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         shell: bash
@@ -98,7 +114,7 @@ jobs:
 
       - name: 可合并时开启自动合并
         id: auto_merge
-        if: steps.diff_check.outputs.has_changes == 'true' && steps.merge_state.outputs.mergeable == 'MERGEABLE'
+        if: steps.diff_check.outputs.has_changes == 'true' && steps.sync_pr.outputs.permission_blocked != 'true' && steps.merge_state.outputs.mergeable == 'MERGEABLE'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         shell: bash
@@ -123,6 +139,13 @@ jobs:
               echo "- 状态：无需同步（dev 已包含 main 最新提交）"
               exit 0
             fi
+            if [ "${{ steps.sync_pr.outputs.permission_blocked }}" = "true" ]; then
+              echo "- 状态：已跳过自动创建同步 PR"
+              echo "- 原因：仓库未开启 GitHub Actions 创建与审批 Pull Request 权限"
+              echo "- 处理：前往 Settings -> Actions -> General -> Workflow permissions，开启 Allow GitHub Actions to create and approve pull requests"
+              echo "- 兜底：由维护者手动执行 main 到 dev 合并，或开启该设置后重新运行 workflow"
+              exit 0
+            fi
             echo "- PR：${{ steps.sync_pr.outputs.pr_url }}"
             echo "- 可合并状态：${{ steps.merge_state.outputs.mergeable }}"
             echo "- 合并状态详情：${{ steps.merge_state.outputs.merge_state_status }}"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ce2e2bf..b89e554 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -84,6 +84,7 @@ This repository provides automatic sync via GitHub Actions workflow:
 - `.github/workflows/sync-main-to-dev.yml`
 - Trigger: every push to `main`
 - Behavior: create/reuse a PR from `main` to `dev`; if mergeable, it tries to enable auto-merge
+- Prerequisite: in `Settings -> Actions -> General -> Workflow permissions`, enable `Allow GitHub Actions to create and approve pull requests`; otherwise the workflow will skip PR creation and only emit a warning summary
 
 Manual fallback (when conflicts or automation is unavailable):
 
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
index 5e8f70c..3e79997 100644
--- a/CONTRIBUTING.zh-CN.md
+++ b/CONTRIBUTING.zh-CN.md
@@ -84,6 +84,7 @@ feature/* / fix/* -> dev -> release/* -> main -> tag(vX.Y.Z)
 - `.github/workflows/sync-main-to-dev.yml`
 - 触发时机：每次 `main` 分支有新的 push
 - 行为：自动创建或复用 `main` 到 `dev` 的同步 PR；若可合并，则尝试开启自动合并
+- 前置条件：需在 `Settings -> Actions -> General -> Workflow permissions` 中开启 `Allow GitHub Actions to create and approve pull requests`，否则 workflow 只会输出告警摘要并跳过建 PR
 
 当出现冲突，或自动化暂不可用时，使用以下手动兜底方式：