Assess push permission (#226)

* use `contents: write` permission to post comments on push events
* update docs

Author: 2bndy5

.github/workflows/self-test.yml

@@ -2,7 +2,7 @@ name: Self test action
 
 on:
   push:
-    branches: main
+    branches: [main]
     paths:
       - 'action.yml'
       - 'requirements.txt'
@@ -19,7 +19,7 @@ on:
 jobs:
   test:
     permissions:
-      issues: write
+      contents: write
       pull-requests: write
     strategy:
       matrix:

docs/action.yml

@@ -14,15 +14,15 @@ inputs:
     minimum-version: '1.3.0'
   lines-changed-only:
     minimum-version: '1.5.0'
-    required-permission: 'content: read #file-changes'
+    required-permission: 'contents: read #file-changes'
   files-changed-only:
     minimum-version: '1.3.0'
-    required-permission: 'content: read #file-changes'
+    required-permission: 'contents: read #file-changes'
   ignore:
     minimum-version: '1.3.0'
   thread-comments:
     minimum-version: '2.6.2'
-    required-permission: 'issues: write #thread-comments'
+    required-permission: 'contents: write #thread-comments'
   no-lgtm:
     minimum-version: '2.6.2'
   step-summary:

docs/examples/index.md

@@ -31,6 +31,7 @@ Here are some example workflows to get started quickly.
     --8<-- "docs/examples/only-PR-comments.yml"
     ```
 
-    1. See also [`style`][style]
-    2. See also [`tidy-checks`][tidy-checks]
-    3. See also [`thread-comments`][thread-comments]
+    1. See also our [token permissions document](../permissions.md)
+    2. See also [`style`][style]
+    3. See also [`tidy-checks`][tidy-checks]
+    4. See also [`thread-comments`][thread-comments]

docs/examples/only-PR-comments.yml

@@ -10,6 +10,8 @@ on:
 jobs:
   cpp-linter:
     runs-on: ubuntu-latest
+    permissions: # (1)!
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4
 
@@ -20,9 +22,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          style: 'file'  # Use .clang-format config file. (1)
-          tidy-checks: '' # Use .clang-tidy config file. (2)
-          # only 'update' a single comment in a pull request's thread. (3)
+          style: 'file'  # Use .clang-format config file. (2)
+          tidy-checks: '' # Use .clang-tidy config file. (3)
+          # only 'update' a single comment in a pull request's thread. (4)
           thread-comments: ${{ github.event_name == 'pull_request' && 'update' }}
 
       - name: Fail fast?!

docs/permissions.md

@@ -14,26 +14,61 @@ When using [`files-changed-only`](inputs-outputs.md#files-changed-only) or
 [`lines-changed-only`](inputs-outputs.md#lines-changed-only) to get the list
 of file changes for a CI event, the following permissions are needed:
 
-```yaml
-    permissions:
-      contents: read # (1)!
-```
+=== "`#!yaml on: push`"
+
+    For [push events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
+
+    ```yaml
+        permissions:
+          contents: read # (1)!
+    ```
+
+    1. This permission is also needed to download files if the repository is not
+       checked out before running cpp-linter.
+
+=== "`#!yaml on: pull_request`"
+
+    For [pull_request events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)
+
+    ```yaml
+        permissions:
+          contents: read # (1)!
+          pull-requests: read # (2)!
+    ```
 
-1. This permission is also needed to download files if the repository is not checked out before
-    running cpp-linter (for both push and pull_request events).
+    1. For pull requests, this permission is only needed to download files if
+       the repository is not checked out before running cpp-linter.
+    2. Specifying `#!yaml write` is also sufficient as that is required for
+
+        * posting [thread comments](#thread-comments) on pull requests
+        * posting [pull request reviews](#pull-request-reviews)
 
 ## Thread Comments
 
 The [`thread-comments`](inputs-outputs.md#thread-comments) feature requires the following permissions:
 
-```yaml
-    permissions:
-      issues: write # (1)!
-      pull-requests: write # (2)!
-```
+=== "`#!yaml on: push`"
+
+    For [push events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
+
+    ```yaml
+        permissions:
+          metadata: read # (1)!
+          contents: write # (2)!
+    ```
+
+    1. needed to fetch existing comments
+    2. needed to post or update a commit comment. This also allows us to delete
+       an outdated comment if needed.
+
+=== "`#!yaml on: pull_request`"
+
+    For [pull_request events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)
 
-1. for [push events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
-2. for [pull_request events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)
+    ```yaml
+        permissions:
+          pull-requests: write
+    ```
 
 ## Pull Request Reviews
 

docs/stylesheets/extra.css

@@ -204,3 +204,25 @@ th {
     display: block;
     max-height: none
 }
+
+/* annotation buttons' pulse animation */
+a.md-annotation__index {
+    border-radius: 2.2ch;
+}
+
+@keyframes pulse {
+    0% {
+        box-shadow: 0 0 0 0 var(--md-accent-fg-color);
+        transform: scale(.95)
+    }
+
+    75% {
+        box-shadow: 0 0 0 .625em transparent;
+        transform: scale(1)
+    }
+
+    to {
+        box-shadow: 0 0 0 0 transparent;
+        transform: scale(.95)
+    }
+}