fix: handle fork PR permission issue for pr-comments gracefully

.gitignore

@@ -1,3 +1,4 @@
 venv/
 .venv/
 __pycache__/
+result.txt

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](docs/fork-pr-comments.md)
 * [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
+> [docs/fork-pr-comments.md](docs/fork-pr-comments.md) 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,23 @@ 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, see
+> the **[Fork PR Comments](docs/fork-pr-comments.md)** documentation for
+> two recommended approaches with ready-to-use workflow examples.
+
 ## Badging Your Repository
 
 You can add a badge to your repository to show your contributors/users that you use commit-check!

docs/fork-pr-comments.md

@@ -0,0 +1,166 @@
+# 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**.
+
+> 📁 Ready-to-use files: [`examples/commit-check-workflow-a.yml`](../examples/commit-check-workflow-a.yml)
+> and [`examples/commit-check-workflow-b.yml`](../examples/commit-check-workflow-b.yml)
+
+**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
+      - uses: actions/upload-artifact@v4
+        with:
+          name: commit-check-result-${{ github.event.number }}
+          path: result.txt      # saved for Workflow B
+```
+
+> 📄 Full file: [`examples/commit-check-workflow-a.yml`](../examples/commit-check-workflow-a.yml)
+
+### 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: |
+            // See examples/commit-check-workflow-b.yml for full script
+            const fs = require('fs');
+            const prNumber = ${{ github.event.workflow_run.pull_requests[0].number }};
+            const resultText = fs.readFileSync('result.txt', 'utf8').trim();
+            const body = resultText
+              ? '# Commit-Check ❌\n```\n' + resultText + '\n```'
+              : '# Commit-Check ✔️';
+            // Creates or updates the matching PR comment
+```
+
+> 📄 Full file: [`examples/commit-check-workflow-b.yml`](../examples/commit-check-workflow-b.yml)
+
+### 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
+```
+
+> ✅ With `pull_request_target`, `pr-comments: true` **does work** on fork PRs —
+> the token has the workflow's configured permissions regardless of whether the PR
+> is from a fork.
+>
+> **When to use this:** Only if the two-workflow pattern is too complex for your setup
+> and you have thoroughly reviewed the security implications.

examples/commit-check-workflow-a.yml

@@ -0,0 +1,33 @@
+# Workflow A: Run commit checks on pull_request events.
+#
+# This workflow is triggered by pull_request and runs commit checks.
+# It uploads the result as an artifact so Workflow B (commit-check-comment.yml)
+# can read it and post a PR comment with full write permissions.
+#
+# See https://github.com/commit-check/commit-check-action#fork-pr-comments
+
+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

examples/commit-check-workflow-b.yml

@@ -0,0 +1,68 @@
+# Workflow B: Post PR comment after commit checks complete.
+#
+# This workflow is triggered by the workflow_run event from Workflow A.
+# It runs in the base repository's context with full write permissions,
+# making it safe for fork PRs (no checkout of fork code).
+#
+# Prerequisites:
+#   - Workflow A (commit-check.yml) must exist and upload an artifact named
+#     commit-check-result-<PR-number> containing result.txt
+#
+# See https://github.com/commit-check/commit-check-action#fork-pr-comments
+
+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,
+              });
+            }