Merge pull request #54 from lucassabreu/issue/53

chore: explaning fork limitations

Author: lucassabreu

.gitattributes

@@ -0,0 +1 @@
+bin/* linguist-generated

.github/workflows/summary-example.yml

@@ -0,0 +1,21 @@
+name: example of summary
+on:
+  pull_request:
+
+jobs:
+  build:
+    name: example of workflow
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@master
+
+      - name: clover file to comment (clover.example.base.xml)
+        uses: ./.
+        with:
+          dir-prefix: /var/www/html
+          file: clover.example.base.xml
+          base-file: clover.example.xml
+          chart-size: 75
+          only-with-cover: true
+          signature: "summary example"

CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- explanation about forks and token permissions with them.
+- new option `skip-comments-on-forks` to prevent blocking pull requests from forks because of lack of
+  permissions.
+
+### Changed
+
+- improving error reporting for debugging purposes
+
 ## [0.12.0] - 2024-02-02
 
 ### Added

README.md

@@ -54,6 +54,7 @@ Configuration
 | `table-coverage-change`           | Show only files which their coverage changed equal or above this percentage <br/> Default: `0`                                                                    |
 | `signature`                       | Custom signature to be used at the bottom of the comment. <br/>If you need multiple comments per pull request each step needs to have a unique `signature`        |
 | `github-token`                    | Custom [PAT][pat] to be used instead of the [default action token][default-token], should have the `repo` scope                                                   |
+| `skip-comments-on-forks`          | Should skip trying to comment on [pull requests created from forks](#restrictions-on-forks) <br/> Default: `false`                                                                          |
 
 Example usage
 -------------
@@ -155,10 +156,25 @@ jobs:
           base-file: tests/base/coverage.xml
 ```
 
+Restrictions on Forks
+---------------------
+
+Github Actions [imposes higher Restrictions on workflows triggered from forks in public repositories][fork],
+where the default token generated will have only read permissions.
+
+Because of that when this Action is run on pull requests from forks no comment will be created with the
+coverage report, instead the report will only be shown at the steps summary.
+
+![example of step summary with the report](./assets/summary-example.png)
+
+If comments on pull request from forks are required for your workflow a [PAT](pat) can be used, but be aware
+that doing that may open the owner of the PAT to the malicious intentions of the internet.
+
 [CHANGELOG](CHANGELOG.md)
 ---------
 
 [danhunsaker/clover-reporter-action]: https://github.com/danhunsaker/clover-reporter-action
 [pat]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
 [lang]: https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Intl#argumento_locales
 [default-token]: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+[fork]: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token

action.yml

@@ -73,6 +73,10 @@ inputs:
   signature:
     description: Custom signature to be used at the bottom of the comment
     required: false
+  skip-comments-on-forks:
+    description: Should skip trying to comment on pull requests created from forks
+    default: false
+
 runs:
   using: node20
   main: bin/index.js