docs: document CI re-triggering limitation and fork PR incompatibility

- docs/permissions.md: Add warning about GITHUB_TOKEN not triggering CI
  on auto-fix commits, with PAT workaround. Add warning about
  third-party fork PRs where auto-fix cannot work.
- action.yml: Add intelligent fork-detection in push failure warning
  (checks for 403/refused/permission errors and shows context-aware
  message referencing docs).
- .github/workflows/examples/auto-fix.yml: Add comment about PAT
  option for CI re-triggering.

Author: shenxianpeng

.github/workflows/examples/auto-fix.yml

@@ -12,6 +12,9 @@ jobs:
       pull-requests: write
     steps:
       - uses: actions/checkout@v5
+        # For auto-fix commits to trigger new CI runs, use a PAT instead:
+        #   with:
+        #     token: ${{ secrets.MY_PAT }}
 
       - uses: cpp-linter/cpp-linter-action@v2
         id: linter

action.yml

@@ -538,7 +538,12 @@ runs:
           let branch = $env.GITHUB_HEAD_REF | default $env.GITHUB_REF_NAME
           let push_result = (^git push origin $"HEAD:refs/heads/($branch)") | complete
           if $push_result.exit_code != 0 {
-            print $"::warning title=Auto-fix push failed::(ansi yellow)($push_result.stderr)(ansi reset)"
+            let stderr_lower = ($push_result.stderr | str downcase)
+            if ($stderr_lower | str contains "403") or ($stderr_lower | str contains "refused") or ($stderr_lower | str contains "not have permission") {
+              print $"::warning title=Auto-fix push failed::This action does not have permission to push to this branch. When using auto-fix on pull_request events from a third-party fork, the GITHUB_TOKEN cannot write to the fork repository. See docs/permissions.md for details.(ansi reset)"
+            } else {
+              print $"::warning title=Auto-fix push failed::(ansi yellow)($push_result.stderr)(ansi reset)"
+            }
           } else {
             print $"(ansi green)Auto-fix commit pushed successfully(ansi reset)"
           }

docs/permissions.md

@@ -81,7 +81,7 @@ The [`tidy-review`](inputs-outputs.md#tidy-review), [`format-review`](inputs-out
 
 ## Auto-fix
 
-The [`auto-fix`](inputs-outputs.md#auto-fix) feature requires the following permission
+The [`auto-fix`](inputs-outputs.md#auto-fix) feature requires `contents: write` permission
 in addition to any other permissions needed for other features:
 
 ```yaml
@@ -90,3 +90,28 @@ in addition to any other permissions needed for other features:
 ```
 
 1. Needed to commit and push the formatted changes back to the PR branch.
+
+!!! warning "CI re-triggering with auto-fix"
+
+    The default `GITHUB_TOKEN` **cannot** trigger new CI runs when pushing
+    a commit. If you need the auto-fix commit to trigger CI checks
+    (e.g. to verify the fix builds clean), use a personal access token
+    (PAT) with `contents: write` scope:
+
+    ```yaml
+    - uses: actions/checkout@v5
+      with:
+        token: ${{ secrets.MY_PAT }}
+    ```
+
+    When using the default `GITHUB_TOKEN`, you can include `[skip ci]` in
+    the auto-fix commit message to avoid unnecessary CI runs on the
+    fix commit itself. See the [`auto-fix-commit-msg`](./inputs-outputs.md#auto-fix-commit-msg) input.
+
+!!! warning "Pull requests from third-party forks"
+
+    Auto-fix does not work on pull requests from third-party forks. The
+    `GITHUB_TOKEN` lacks write permission to the fork repository, and
+    `git push` to the fork's branch is not possible. Consider
+    restricting `auto-fix` to `push` events or pull requests from the
+    same repository.