feat: implement graceful fork PR degradation and document workflow_run pattern

shenxianpeng · shenxianpeng · commit 4d64e46bca74 · 2026-06-16T18:58:32.000+03:00
- Add Job Summary notice when PR comments are skipped for fork PRs (not just a ::warning:: log line, but also visible in GH UI) - Update warning message to reference new documentation section - Add comprehensive Fork PR Comments section to README with: - Two-workflow (workflow_run) pattern as recommended best practice - pull_request_target alternative with security warnings - Add unit tests for the new Job Summary behavior Closes #143
diff --git a/README.md b/README.md
@@ -26,6 +26,7 @@ A GitHub Action for checking commit message formatting, branch naming, committer
 * [Optional Inputs](#optional-inputs)
 * [GitHub Action Job Summary](#github-action-job-summary)
 * [GitHub Pull Request Comments](#github-pull-request-comments)
+* [Fork PR Comments](#fork-pr-comments)
 * [Badging Your Repository](#badging-your-repository)
 * [Versioning](#versioning)
 
@@ -123,7 +124,12 @@ jobs:
 > [!IMPORTANT]
 > `pr-comments` is an experimental feature. By default, it's disabled.
 >
-> PR comments are skipped for pull requests from forked repositories. For more details, refer to issue [`#143`](https://github.com/commit-check/commit-check-action/issues/143).
+> PR comments are skipped for pull requests from forked repositories. See
+> [Fork PR Comments](#fork-pr-comments) for details on how to enable this feature
+> for fork contributions.
+>
+> Note: write-access to pull-requests requires the `pull-requests: write` permission.
+> See [usage example](#usage).
 
 Note: the default rule of above inputs is following [this configuration](https://github.com/commit-check/commit-check-action/blob/main/commit-check.toml). If you want to customize, just add your [`commit-check.toml`](https://commit-check.github.io/commit-check/configuration.html) config file under your repository root directory.
 
@@ -149,6 +155,184 @@ By default, commit-check-action results are shown on the job summary page of the
 
 ![Failure pull request comment](https://github.com/commit-check/.github/blob/main/screenshot/failure-pr-comments.png)
 
+## Fork PR Comments
+
+When a pull request is opened from a **forked repository**, the `GITHUB_TOKEN` used by the
+`pull_request` event has **read-only** permissions by design (GitHub security policy).
+This means `pr-comments: true` cannot write a comment back to the PR.
+
+By default, commit-check-action handles this gracefully:
+
+- PR comment writing is **skipped** with a `::warning::` message in the logs
+- A **notice is added to the Job Summary** explaining why and how to fix it
+- The commit checks themselves **still run normally**
+
+> **For most projects, this is sufficient** — contributors can see check results in the
+> action Job Summary. But if you *must* have PR comments on fork contributions, there
+> are two recommended approaches.
+
+---
+
+### Option 1: Two-workflow pattern (recommended)
+
+This is the **official GitHub-recommended best practice** for writing PR comments from
+fork PRs. It uses the [`workflow_run`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run)
+event with **no security risks**.
+
+**How it works:**
+
+```
+  pull_request          workflow_run
+      │                      │
+      ▼                      ▼
+┌──────────────┐     ┌──────────────────┐
+│ Workflow A   │     │ Workflow B       │
+│ (checks)     │────►│ (comment writer) │
+│              │     │                  │
+│ Token: READ  │     │ Token: WRITE     │
+│ Saves result │     │ Reads artifact   │
+│ as artifact  │     │ Posts PR comment │
+└──────────────┘     └──────────────────┘
+```
+
+**Workflow A** — `.github/workflows/commit-check.yml` (triggered by `pull_request`):
+
+```yaml
+name: Commit Check
+
+on:
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: commit-check/commit-check-action@v2
+        with:
+          message: true
+          branch: true
+          pr-comments: false  # comments handled by Workflow B
+          job-summary: true
+
+      # Save results so Workflow B can post a PR comment
+      - uses: actions/upload-artifact@v4
+        with:
+          name: commit-check-result-${{ github.event.number }}
+          path: result.txt
+```
+
+**Workflow B** — `.github/workflows/commit-check-comment.yml` (triggered by `workflow_run`):
+
+```yaml
+name: Commit Check Comment
+
+on:
+  workflow_run:
+    workflows: ["Commit Check"]  # must match Workflow A's name exactly
+    types: [completed]
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      actions: read  # needed to download artifacts
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: commit-check-result-${{ github.event.workflow_run.pull_requests[0].number }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      - name: Read result and post PR comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const prNumber = ${{ github.event.workflow_run.pull_requests[0].number }};
+            const resultText = fs.readFileSync('result.txt', 'utf8').trim();
+
+            const successTitle = '# Commit-Check ✔️';
+            const failureTitle = '# Commit-Check ❌';
+            const body = resultText
+              ? `${failureTitle}\n\`\`\`\n${resultText}\n\`\`\``
+              : successTitle;
+
+            const { data: comments } = await github.rest.issues.listComments({
+              ...context.repo,
+              issue_number: prNumber,
+            });
+
+            const existing = comments.find(c =>
+              c.body.startsWith(successTitle) || c.body.startsWith(failureTitle)
+            );
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                ...context.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                ...context.repo,
+                issue_number: prNumber,
+                body,
+              });
+            }
+```
+
+> **Key security benefits:**
+> - Workflow B runs in the **base repository's context**, so `GITHUB_TOKEN` has full write
+>   permissions (you explicitly grant `pull-requests: write`)
+> - Workflow B **does not checkout the PR code**, so untrusted fork code never runs
+>   with elevated permissions
+> - The artifact only contains `result.txt` — no code or secrets
+
+---
+
+### Option 2: pull_request_target (advanced, use with caution)
+
+If you understand the security implications, you can use
+[`pull_request_target`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target)
+which runs in the base repository's context with **write token access**.
+
+> **⚠️ Security warning:** Never check out (`actions/checkout`) the PR's HEAD commit
+> when using `pull_request_target`. Always check out the base branch or use the
+> default merge commit. Otherwise, fork code could exfiltrate your repository's secrets.
+
+```yaml
+name: Commit Check
+
+on:
+  pull_request_target:
+    branches: ["main"]
+
+jobs:
+  commit-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      # SAFE: checkout the merge commit, NOT the PR head
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: commit-check/commit-check-action@v2
+        with:
+          message: true
+          branch: true
+          pr-comments: true
+```
+
+> **When to use this:** Only if the two-workflow pattern is too complex for your setup
+> and you have thoroughly reviewed the security implications.
+
 ## Badging Your Repository
 
 You can add a badge to your repository to show your contributors/users that you use commit-check!
diff --git a/main.py b/main.py
@@ -271,13 +271,26 @@ def add_pr_comments() -> int:
     # Fork PRs triggered by the pull_request event receive a read-only token;
     # the GitHub API will always reject comment writes with 403.
     if is_fork_pr():
-        print(
-            "::warning::Skipping PR comment: pull requests from forked repositories "
+        msg = (
+            "Skipping PR comment: pull requests from forked repositories "
             "cannot write comments via the pull_request event (GITHUB_TOKEN is "
-            "read-only for forks). Use the pull_request_target event or the "
-            "two-workflow artifact pattern instead. "
-            "See https://github.com/commit-check/commit-check-action/issues/77"
+            "read-only for forks). "
+            "See https://github.com/commit-check/commit-check-action#fork-pr-comments "
+            "for how to enable PR comments on fork PRs."
         )
+        print(f"::warning::{msg}")
+        if JOB_SUMMARY_ENABLED:
+            with open(GITHUB_STEP_SUMMARY, "a") as f:
+                f.write(
+                    "\n---\n"
+                    "### \u2139\ufe0f PR Comment Skipped\n\n"
+                    "Pull requests from forked repositories cannot write comments "
+                    "using the `pull_request` event because `GITHUB_TOKEN` has "
+                    "read-only permissions.\n\n"
+                    "> **\U0001f4a1 Tip:** To enable PR comments on fork PRs, see "
+                    "[Enabling PR Comments on Fork Pull Requests]"
+                    "(https://github.com/commit-check/commit-check-action#fork-pr-comments).\n"
+                )
         return 0
 
     try:
diff --git a/main_test.py b/main_test.py
@@ -467,6 +467,55 @@ def test_failure_writes_failure_title(self):
         self.assertIn("bad commit message", content)
 
 
+class TestAddPrComments(unittest.TestCase):
+    def setUp(self):
+        import tempfile
+
+        self._orig_dir = os.getcwd()
+        self._tmpdir = tempfile.mkdtemp()
+        os.chdir(self._tmpdir)
+        with open("result.txt", "w", encoding="utf-8"):
+            pass
+
+    def tearDown(self):
+        os.chdir(self._orig_dir)
+
+    def test_disabled_returns_zero(self):
+        with patch("main.PR_COMMENTS_ENABLED", False):
+            rc = main.add_pr_comments()
+        self.assertEqual(rc, 0)
+
+    def test_fork_pr_skips_comment_and_warns(self):
+        with (
+            patch("main.PR_COMMENTS_ENABLED", True),
+            patch("main.is_fork_pr", return_value=True),
+            patch("main.JOB_SUMMARY_ENABLED", False),
+            patch("builtins.print") as mock_print,
+        ):
+            rc = main.add_pr_comments()
+        self.assertEqual(rc, 0)
+        printed = mock_print.call_args[0][0]
+        self.assertIn("::warning::", printed)
+        self.assertIn("read-only", printed)
+
+    def test_fork_pr_writes_job_summary_hint(self):
+        summary_path = os.path.join(self._tmpdir, "summary.txt")
+        with (
+            patch("main.PR_COMMENTS_ENABLED", True),
+            patch("main.is_fork_pr", return_value=True),
+            patch("main.JOB_SUMMARY_ENABLED", True),
+            patch("main.GITHUB_STEP_SUMMARY", summary_path),
+            patch("builtins.print"),
+        ):
+            rc = main.add_pr_comments()
+        self.assertEqual(rc, 0)
+        with open(summary_path, encoding="utf-8") as f:
+            content = f.read()
+        self.assertIn("PR Comment Skipped", content)
+        self.assertIn("read-only", content)
+        self.assertIn("fork-pr-comments", content)
+
+
 class TestIsForkPr(unittest.TestCase):
     def test_no_event_path(self):
         with patch.dict(os.environ, {}, clear=True):
