Fix fork PR permission error with specific guidance (#243) (#245)

Detect fork PRs and show targeted error message suggesting
pull_request_target event instead of generic permissions advice.
Add Fork PRs troubleshooting section to README.

Closes #243

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: MishaKav

README.md

@@ -45,6 +45,7 @@ A GitHub Action that adds pytest coverage reports as comments to your pull reque
     - [Multiple Files (Monorepo)](#multiple-files-monorepo)
   - [🔧 Troubleshooting](#-troubleshooting)
     - [Comment Not Appearing](#comment-not-appearing)
+    - [Fork PRs](#fork-prs)
     - [Unrecognized Arguments Error](#unrecognized-arguments-error)
     - [Coverage Report Too Large](#coverage-report-too-large)
     - [GitHub Step Summary Too Large](#github-step-summary-too-large)
@@ -603,6 +604,26 @@ Instead of a badge image:
 
 **Why it works on forks but not main repos**: Forks often have different default permission settings than the main repository. Organizations frequently set restrictive defaults for security.
 
+### Fork PRs
+
+**Issue**: Permission denied when a pull request is opened from a fork.
+
+**Root Cause**: GitHub restricts the `GITHUB_TOKEN` to **read-only** for `pull_request` events triggered from forks. This is a security measure — even if your workflow has `pull-requests: write`, the token is downgraded for fork PRs.
+
+**Solution**: Use the `pull_request_target` event, which runs in the context of the base branch and gets a token with write permissions:
+
+```yaml
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+```
+
+> **Security Warning**: `pull_request_target` runs with access to the base repo's secrets and a write token. Never checkout and run untrusted code from the fork with these elevated permissions. Only check out the base branch code, or carefully limit what fork code is executed.
+
 ### Unrecognized Arguments Error
 
 **Issue**: `pytest: error: unrecognized arguments: --cov --cov-report`

dist/index.js

@@ -39398,11 +39398,41 @@ const truncateSummary = (content, maxLength) => {
 };
 
 const handlePermissionError = (error, context) => {
-  const eventName = context?.eventName || 'this event';
-  if (error?.status === 403) {
-    const helpfulMessage = [
-      'Permission denied when trying to create/update comment.',
+  if (error?.status !== 403) {
+    core.setFailed(`Failed to create/update comment: ${error.message}`);
+    throw error;
+  }
+
+  const isForkPR = context?.payload?.pull_request?.head?.repo?.fork === true;
+  const lines = ['Permission denied when trying to create/update comment.', ''];
+
+  if (isForkPR) {
+    lines.push(
+      'This PR is from a fork. GitHub restricts the GITHUB_TOKEN to read-only',
+      'for fork PRs triggered by the `pull_request` event.',
+      '',
+      'To fix this, use the `pull_request_target` event instead:',
+      '',
+      '```yaml',
+      'on:',
+      '  pull_request_target:',
+      '    types: [opened, synchronize, reopened]',
+      '',
+      'permissions:',
+      '  contents: read',
+      '  pull-requests: write',
+      '```',
+      '',
+      'Note: `pull_request_target` runs in the context of the base branch.',
+      'Be cautious when checking out fork code — never run untrusted code',
+      'from the fork with elevated permissions.',
       '',
+      'For more information, see:',
+      'https://github.com/MishaKav/pytest-coverage-comment#fork-prs',
+    );
+  } else {
+    const eventName = context?.eventName || 'this event';
+    lines.push(
       'This error usually occurs because the GITHUB_TOKEN lacks necessary permissions.',
       '',
       'To fix this, add a permissions block to your workflow:',
@@ -39415,12 +39445,10 @@ const handlePermissionError = (error, context) => {
       '',
       `For ${eventName === 'push' ? 'push events creating commit comments' : 'pull request events and more information'}, see:`,
       'https://github.com/MishaKav/pytest-coverage-comment#comment-not-appearing',
-    ].join('\n');
-
-    core.setFailed(helpfulMessage);
-  } else {
-    core.setFailed(`Failed to create/update comment: ${error.message}`);
+    );
   }
+
+  core.setFailed(lines.join('\n'));
   throw error;
 };
 

src/index.js

@@ -87,11 +87,41 @@ const truncateSummary = (content, maxLength) => {
 };
 
 const handlePermissionError = (error, context) => {
-  const eventName = context?.eventName || 'this event';
-  if (error?.status === 403) {
-    const helpfulMessage = [
-      'Permission denied when trying to create/update comment.',
+  if (error?.status !== 403) {
+    core.setFailed(`Failed to create/update comment: ${error.message}`);
+    throw error;
+  }
+
+  const isForkPR = context?.payload?.pull_request?.head?.repo?.fork === true;
+  const lines = ['Permission denied when trying to create/update comment.', ''];
+
+  if (isForkPR) {
+    lines.push(
+      'This PR is from a fork. GitHub restricts the GITHUB_TOKEN to read-only',
+      'for fork PRs triggered by the `pull_request` event.',
+      '',
+      'To fix this, use the `pull_request_target` event instead:',
+      '',
+      '```yaml',
+      'on:',
+      '  pull_request_target:',
+      '    types: [opened, synchronize, reopened]',
+      '',
+      'permissions:',
+      '  contents: read',
+      '  pull-requests: write',
+      '```',
+      '',
+      'Note: `pull_request_target` runs in the context of the base branch.',
+      'Be cautious when checking out fork code — never run untrusted code',
+      'from the fork with elevated permissions.',
       '',
+      'For more information, see:',
+      'https://github.com/MishaKav/pytest-coverage-comment#fork-prs',
+    );
+  } else {
+    const eventName = context?.eventName || 'this event';
+    lines.push(
       'This error usually occurs because the GITHUB_TOKEN lacks necessary permissions.',
       '',
       'To fix this, add a permissions block to your workflow:',
@@ -104,12 +134,10 @@ const handlePermissionError = (error, context) => {
       '',
       `For ${eventName === 'push' ? 'push events creating commit comments' : 'pull request events and more information'}, see:`,
       'https://github.com/MishaKav/pytest-coverage-comment#comment-not-appearing',
-    ].join('\n');
-
-    core.setFailed(helpfulMessage);
-  } else {
-    core.setFailed(`Failed to create/update comment: ${error.message}`);
+    );
   }
+
+  core.setFailed(lines.join('\n'));
   throw error;
 };