fix: annotate failed PR comment posts and name the right permission

The 403 hint told users to grant 'issues: write', but a PR comment is
written with the pull-requests scope — following the hint does not fix
the failure. Every other failure path only printed to stderr, so a run
whose comment never posted stayed green with nothing on the page saying
why; those now emit ::warning:: too.

Also refresh the workflow examples: drop the push trigger from the
README example (pr-comments only works on pull_request, which made the
event_name conditional dead weight) and move actions/checkout from v5
to v7.

Author: shenxianpeng

README.md

@@ -39,7 +39,6 @@ Create a new GitHub Actions workflow in your project, e.g. at [.github/workflows
 name: Commit Check
 
 on:
-  push:
   pull_request:
     branches: 'main'
 
@@ -50,7 +49,7 @@ jobs:
       contents: read
       pull-requests: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0  # Required for merge-base checks
       - uses: commit-check/commit-check-action@v2
@@ -60,7 +59,7 @@ jobs:
           author-name: false
           author-email: false
           job-summary: true
-          pr-comments: ${{ github.event_name == 'pull_request' }}
+          pr-comments: true
 ```
 
 > [!NOTE]

docs/fork-pr-comments.md

@@ -56,7 +56,7 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - uses: commit-check/commit-check-action@v2
@@ -148,7 +148,7 @@ jobs:
       pull-requests: write
     steps:
       # SAFE: checkout the merge commit, NOT the PR head
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - uses: commit-check/commit-check-action@v2

examples/commit-check-workflow-a.yml

@@ -16,7 +16,7 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - uses: commit-check/commit-check-action@v2

main.py

@@ -884,15 +884,18 @@ def add_pr_comments(results: list[ScopeResult]) -> int:
         if e.status == 403:
             print(
                 "::warning::Unable to post PR comment (403 Forbidden). "
-                "Ensure your workflow grants 'issues: write' permission. "
+                "Ensure your workflow grants 'pull-requests: write' permission. "
                 f"Error: {e.data.get('message', str(e))}",
                 file=sys.stderr,
             )
             return 0
-        print(f"Error posting PR comment: {e}", file=sys.stderr)
+        # Annotated, not just printed: posting the comment is best-effort and
+        # never fails the step, so without an annotation the run is green, the
+        # comment is absent, and nothing says why.
+        print(f"::warning::Unable to post PR comment: {e}", file=sys.stderr)
         return 0
     except Exception as e:
-        print(f"Error posting PR comment: {e}", file=sys.stderr)
+        print(f"::warning::Unable to post PR comment: {e}", file=sys.stderr)
         return 0
 
 

main_test.py

@@ -1085,6 +1085,88 @@ def test_skips_when_comment_is_up_to_date(self):
         mock_pull_request.create_comment.assert_not_called()
 
 
+class _StubGithubException(Exception):
+    """Stands in for github.GithubException, which is mocked away in these tests.
+
+    The real class has to be a genuine exception type or the ``except`` clause
+    in add_pr_comments raises TypeError before the handler is reached.
+    """
+
+    def __init__(self, status, data=None):
+        super().__init__(f"status {status}")
+        self.status = status
+        self.data = data or {}
+
+
+class TestAddPrCommentsFailures(unittest.TestCase):
+    """Posting the comment is best-effort, but it must never fail silently.
+
+    Every branch here returns 0 so the step stays green — which is the point:
+    without an annotation the run is green, the comment is absent, and nothing
+    on the page says why.
+    """
+
+    def _run(self, side_effect):
+        mock_pull_request = MagicMock()
+        mock_pull_request.get_comments.return_value = []
+        mock_pull_request.create_comment.side_effect = side_effect
+        mock_repo = MagicMock()
+        mock_repo.get_issue.return_value = mock_pull_request
+
+        github_module = MagicMock()
+        github_module.GithubException = _StubGithubException
+        github_module.Github.return_value.get_repo.return_value = mock_repo
+
+        with (
+            patch("main.PR_COMMENTS_ENABLED", True),
+            patch("main.is_fork_pr_with_readonly_token", return_value=False),
+            patch.dict(
+                os.environ,
+                {
+                    "GITHUB_TOKEN": "token",
+                    "GITHUB_REPOSITORY": "owner/repo",
+                    "GITHUB_REF": "refs/pull/12/merge",
+                },
+            ),
+            patch.dict(sys.modules, {"github": github_module}),
+            patch("builtins.print") as mock_print,
+        ):
+            rc = main.add_pr_comments([fail_scope()])
+        printed = [
+            call[0][0]
+            for call in mock_print.call_args_list
+            if call[0] and isinstance(call[0][0], str)
+        ]
+        return rc, printed
+
+    def test_forbidden_names_the_permission_that_actually_grants_this(self):
+        rc, printed = self._run(
+            _StubGithubException(403, {"message": "Resource not accessible"})
+        )
+        self.assertEqual(rc, 0)
+        warning = next(w for w in printed if "::warning::" in w)
+        # pull-requests, not issues: a PR comment is written with the
+        # pull-requests scope, and this hint is the only guidance a user gets.
+        self.assertIn("pull-requests: write", warning)
+        self.assertNotIn("issues: write", warning)
+
+    def test_other_api_errors_are_annotated(self):
+        rc, printed = self._run(_StubGithubException(500, {"message": "boom"}))
+        self.assertEqual(rc, 0)
+        self.assertTrue(
+            any("::warning::" in w for w in printed),
+            f"a failed post must be annotated, got: {printed}",
+        )
+
+    def test_unexpected_errors_are_annotated(self):
+        rc, printed = self._run(RuntimeError("network went away"))
+        self.assertEqual(rc, 0)
+        self.assertTrue(
+            any("::warning::" in w and "network went away" in w for w in printed),
+            f"a failed post must be annotated, got: {printed}",
+        )
+
+
 class TestIsForkPrWithReadonlyToken(unittest.TestCase):
     def test_fork_pr_with_pull_request_event(self):
         with (