Fix issue #68: Improve error handling and documentation for permission errors (#231)

* Fix issue #68: Add better error handling and documentation for permission errors

This commit addresses the "Resource not accessible by integration" error
that users encounter when the GITHUB_TOKEN lacks necessary permissions.

Changes:
- Add comprehensive error handling in src/index.js that catches 403 permission
  errors and provides actionable guidance with correct permissions block
- Update README.md permissions examples to show minimal required permissions
  (contents: read, pull-requests: write) instead of excessive permissions
- Expand troubleshooting section with detailed explanation of permission errors,
  common error messages, and why the issue appears differently on forks
- Update action.yml description to mention required permissions upfront
- Add permission requirement note to github-token input description

The action now provides clear, helpful error messages when permission issues
occur, directing users to add the correct permissions block to their workflow.

Fixes #68

* Update CHANGELOG and bump version to 1.1.59

* Add Node version file and update package-lock

- Add .nvmrc to specify Node v20.12.2
- Update package-lock.json to lockfileVersion 3

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Address PR review comments

- Update Node.js to v20.19.5 (fixes CVE-2024-27980)
- Improve error handling with null safety and consistent error reporting
- Update error message for better clarity
- Add lockfile upgrade explanation to CHANGELOG

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Remove internal Node.js version update from CHANGELOG

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Upgrade ESLint from 8.57.1 to 9.39.1

- Update to ESLint 9 with flat config system
- Add @eslint/js and globals packages
- Create eslint.config.js with flat config format
- Remove deprecated eslintConfig from package.json
- All tests passing with no linting errors

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Remove peer dependencies from package-lock.json for several packages to streamline dependency management.

---------

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

Author: MishaKav

.nvmrc

@@ -0,0 +1 @@
+v20.19.5

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog of the Pytest Coverage Comment
 
+## [Pytest Coverage Comment 1.1.59](https://github.com/MishaKav/pytest-coverage-comment/tree/v1.1.59)
+
+**Release Date:** 2025-11-08
+
+#### Changes
+
+- fix "Resource not accessible by integration" error with better error handling and documentation (#68)
+- update permission examples to show minimal required permissions (contents: read, pull-requests: write)
+- upgrade package-lock.json from lockfileVersion 2 to 3 (causes extensive but cosmetic changes in dist/index.js)
+
 ## [Pytest Coverage Comment 1.1.58](https://github.com/MishaKav/pytest-coverage-comment/tree/v1.1.58)
 
 **Release Date:** 2025-11-08

README.md

@@ -107,8 +107,7 @@ on:
       - '*'
 
 permissions:
-  contents: write
-  checks: write
+  contents: read
   pull-requests: write
 
 jobs:
@@ -540,16 +539,40 @@ If you want auto-update the coverage badge on your README, you can see the [work
 
 **Issue**: The action runs successfully but no comment appears on the PR.
 
+**Root Cause**: This is usually caused by insufficient GitHub token permissions. The `GITHUB_TOKEN` needs write access to create/update PR comments.
+
+**Common Error Messages**:
+- `Error: Resource not accessible by integration`
+- `HttpError: Resource not accessible by integration`
+- `403 Forbidden` errors in the action logs
+
 **Solutions**:
 
-- Ensure proper permissions are set:
-  ```yaml
-  permissions:
-    contents: write
-    pull-requests: write
-  ```
-- For `workflow_dispatch`, provide the `issue-number` input
-- Check if `hide-comment` is set to `false`
+1. **Add permissions block to your workflow** (Recommended):
+   ```yaml
+   permissions:
+     contents: read        # Required for checkout and comparing commits
+     pull-requests: write  # Required for creating/updating PR comments
+   ```
+
+2. **For `push` events with commit comments**, use:
+   ```yaml
+   permissions:
+     contents: write       # Required for creating commit comments
+     pull-requests: write  # If you also want PR comments
+   ```
+
+3. **Repository/Organization Settings** (Admin access required):
+   - Go to Settings > Actions > General
+   - Under "Workflow permissions", select "Read and write permissions"
+   - Note: This affects all workflows, so adding permissions to individual workflows is more secure
+
+4. **Other checks**:
+   - For `workflow_dispatch` events, provide the `issue-number` input
+   - Verify `hide-comment` is not set to `true`
+   - Check branch protection rules aren't blocking automated comments
+
+**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.
 
 ### Unrecognized Arguments Error
 

action.yml

@@ -1,13 +1,13 @@
 name: 'Pytest Coverage Comment'
-description: 'GitHub Action that adds pytest coverage reports as comments to pull requests with badges, test statistics, and direct file links'
+description: 'GitHub Action that adds pytest coverage reports as comments to pull requests with badges, test statistics, and direct file links. Requires pull-requests: write permission.'
 author: 'Misha Kav'
 branding:
   icon: 'message-circle'
   color: 'blue'
 
 inputs:
   github-token:
-    description: 'GitHub token for API access to create/update comments'
+    description: 'GitHub token for API access to create/update comments. Ensure your workflow has pull-requests: write permission.'
     default: ${{ github.token }}
     required: true