fix(auto-fix): gate to same-repo PRs, avoid stray commits

Address review feedback on the auto-fix flow:

- Gate the PR-branch checkout and the auto-commit/push steps to
  same-repository pull requests. Fork PRs previously hard-failed the
  checkout (the fork's branch isn't on origin) and could not push; now
  they are skipped with a warning.
- Guard against tag refs: compute the destination branch from the PR
  head ref or a pushed branch ref, and skip otherwise so we never push
  HEAD to refs/heads/<tag> and create a stray branch.
- Stage only tracked modifications with `git add -u` instead of
  `git add -A`, so unrelated untracked/generated files are not swept
  into the auto-fix commit.
- docs/permissions.md: clarify the write permission is for the
  actions/checkout token, and correct the `[skip ci]` guidance (it only
  matters for PAT/App-token pushes, since the default GITHUB_TOKEN push
  does not trigger CI anyway).
- Example workflow: downgrade `pull-requests: write` to `read` (the
  example uses no review/thread-comment feature; `read` is still needed
  for files-changed-only on pull_request events).

Author: shenxianpeng

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

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write  # needed for auto-fix commits
-      pull-requests: write
+      pull-requests: read  # needed to list changed files on pull_request events
     steps:
       - uses: actions/checkout@v7
         # For auto-fix commits to trigger new CI runs, use a PAT instead:

action.yml

@@ -458,7 +458,10 @@ runs:
         }
 
     - name: Checkout PR branch for auto-fix push capability
-      if: (inputs.auto-fix == 'true' || inputs.auto-fix == true) && github.event_name == 'pull_request'
+      if: >-
+        (inputs.auto-fix == 'true' || inputs.auto-fix == true)
+        && github.event_name == 'pull_request'
+        && github.event.pull_request.head.repo.full_name == github.repository
       shell: nu {0}
       run: |
         let head_ref = $env.GITHUB_HEAD_REF
@@ -469,6 +472,15 @@ runs:
           print $"(ansi green)Switched to PR branch \"($head_ref)\"(ansi reset)"
         }
 
+    - name: Warn that auto-fix is skipped on forked pull requests
+      if: >-
+        (inputs.auto-fix == 'true' || inputs.auto-fix == true)
+        && github.event_name == 'pull_request'
+        && github.event.pull_request.head.repo.full_name != github.repository
+      shell: nu {0}
+      run: |
+        print "::warning title=Auto-fix skipped::auto-fix cannot push to a third-party fork's branch, so no formatting commit was made. Apply clang-format fixes from within the fork or run cpp-linter locally."
+
     - name: Run cpp-linter
       id: cpp-linter
       shell: nu {0}
@@ -531,9 +543,28 @@ runs:
         ^$'($env.UV_INSTALL_DIR)/uv' ...$uv_args cpp-linter ...$args
 
     - name: Auto-commit clang-format fixes
-      if: inputs.auto-fix == 'true' || inputs.auto-fix == true
+      if: >-
+        (inputs.auto-fix == 'true' || inputs.auto-fix == true)
+        && (github.event_name != 'pull_request'
+        || github.event.pull_request.head.repo.full_name == github.repository)
       shell: nu {0}
       run: |
+        # Determine the destination branch up-front: the PR head ref, or the
+        # pushed branch. Bail out on tag refs (or anything that is not a branch)
+        # so we never push HEAD to refs/heads/<tag> and create a stray branch.
+        let head_ref = $env.GITHUB_HEAD_REF
+        let branch = if ($head_ref | is-not-empty) {
+          $head_ref
+        } else if ($env.GITHUB_REF | str starts-with "refs/heads/") {
+          $env.GITHUB_REF_NAME
+        } else {
+          ""
+        }
+        if ($branch | is-empty) {
+          print $"::notice title=Auto-fix skipped::($env.GITHUB_REF) is not a branch or pull request ref; skipping auto-fix commit."
+          exit 0
+        }
+
         # Refresh index first so stat-only differences don't create false positives
         ^git update-index -q --refresh
         let has_changes = (^git diff-index --name-status --exit-code HEAD -- | complete | $in.exit_code == 1)
@@ -550,19 +581,20 @@ runs:
           }
           let git_user = $"user.name=($git_user_name)"
           let git_email = $"user.email=($git_user_email)"
-          ^git add -A
+          # Stage only tracked modifications (clang-format edits existing sources).
+          # Avoid `git add -A`, which would also sweep in unrelated untracked files.
+          ^git add -u
           let commit_msg = if ('${{ inputs.auto-fix-commit-msg }}' | is-empty) {
             'style: apply styling format fix'
           } else {
             '${{ inputs.auto-fix-commit-msg }}'
           }
           ^git -c $git_user -c $git_email commit -m $"($commit_msg)"
-          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 {
             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)"
+              print $"::warning title=Auto-fix push failed::This action does not have permission to push to this branch. Ensure the token used by actions/checkout has `contents: write` (branch protection rules may also block the push). See docs/permissions.md for details."
             } else {
               print $"::warning title=Auto-fix push failed::(ansi yellow)($push_result.stderr)(ansi reset)"
             }

docs/permissions.md

@@ -89,29 +89,32 @@ in addition to any other permissions needed for other features:
       contents: write # (1)!
 ```
 
-1. Needed to commit and push the formatted changes back to the PR branch.
+1. Needed by the token used in `actions/checkout` to commit and push the
+   formatted changes back to the 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:
+    (PAT) with `contents: write` scope on the checkout step:
 
     ```yaml
     - uses: actions/checkout@v7
       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.
+    Conversely, if you use a PAT or GitHub App token (whose pushes **do**
+    trigger CI) but do not want the auto-fix commit itself to start a new
+    run, include `[skip ci]` in the commit message via the
+    [`auto-fix-commit-msg`](./inputs-outputs.md#auto-fix-commit-msg) input.
+    With the default `GITHUB_TOKEN`, `[skip ci]` is unnecessary since the
+    push does not trigger CI anyway.
 
 !!! 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.
+    Auto-fix is automatically skipped for pull requests from third-party
+    forks: the `GITHUB_TOKEN` cannot push to the fork's branch, so the
+    action emits a warning and makes no commit. Use `auto-fix` on `push`
+    events or on pull requests from the same repository.