From b3799203d83e3518d61e45fc0c835209804ac1e7 Mon Sep 17 00:00:00 2001
From: Brendan <2bndy5@gmail.com>
Date: Mon, 26 Aug 2024 12:30:55 -0700
Subject: [PATCH] begin documenting permissions

resolves #17

This is mostly copied and pasted from cpp-linter-action's corresponding doc.

The parts about PR reviews have been commented out and should be un-commented when addressing #9.
---
 docs/src/SUMMARY.md     |  1 +
 docs/src/permissions.md | 88 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 docs/src/permissions.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 5ae2d66..07ab886 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -4,3 +4,4 @@
 
 - [Introduction](./index.md)
 - [Command Line Interface](./cli.md)
+- [Token Permissions](./permissions.md)
diff --git a/docs/src/permissions.md b/docs/src/permissions.md
new file mode 100644
index 0000000..31e7050
--- /dev/null
+++ b/docs/src/permissions.md
@@ -0,0 +1,88 @@
+<!-- markdownlint-disable MD024 -->
+
+# Token Permissions
+
+This is an exhaustive list of required permissions organized by features.
+
+> [!important]
+> The `GITHUB_TOKEN` environment variable should be supplied when running on a private repository.
+> Otherwise the runner does not not have the privileges needed for the features mentioned here.
+>
+> See also [Authenticating with the `GITHUB_TOKEN`](https://docs.github.com/en/actions/reference/authentication-in-a-workflow)
+
+[push-events]: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push
+[pr-events]: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
+
+## File Changes
+
+When using [`--files-changed-only`](cli.md#-f---files-changed-only) or
+[`--lines-changed-only`](cli.md#-l---lines-changed-only) to get the list
+of file changes for a CI event, the following permissions are needed:
+
+### Push
+
+For [`push` events][push-events].
+
+```yaml
+    permissions:
+        contents: read
+```
+
+The `contents` permission is also needed to download files if the repository is not
+checked out before running cpp-linter.
+
+### Pull Request
+
+For [`pull_request` events][pr-events].
+
+```yaml
+    permissions:
+        contents: read
+        pull-requests: read
+```
+
+For pull requests, the `contents` permission is only needed to download files if
+the repository is not checked out before running cpp-linter.
+
+* Specifying `write` to the `pull-requests` permission 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`](cli.md#-g---thread-comments) feature requires the following permissions:
+
+### Push
+
+For [`push` events][push-events].
+
+```yaml
+    permissions:
+      metadata: read
+      contents: write
+```
+
+* The `metadata` permission is needed to fetch existing comments.
+* The `contents` permission is needed to post or update a commit comment.
+  This also allows us to delete an outdated comment if needed.
+
+### Pull_request
+
+For [`pull_request` events][pr-events].
+
+```yaml
+    permissions:
+      pull-requests: write
+```
+
+<!--
+## Pull Request Reviews
+
+The [`tidy-review`](cli.md#-t---tidy-review), [`format-review`](cli.md#-f---format-review), and [`passive-reviews`](cli.md#-p---passive-reviews) features require the following permissions:
+
+```yaml
+    permissions:
+      pull-requests: write
+```
+-->