[llvm] [Github][Docs] Add best practice for top level read permissions (PR #131470)

[Aiden Grossman via llvm-commits]

https://github.com/boomanaiden154 created https://github.com/llvm/llvm-project/pull/131470

This patch adds a section pointing out how permissions should be done within Github workflows. I believe all of our workflows are currently compliant with this, but it helps to have something to point to documenting the practice and especially the motivation.

>From 113edb5fb2b3e20024c06d4f991f8dc36df374b0 Mon Sep 17 00:00:00 2001
From: Aiden Grossman <aidengrossman at google.com>
Date: Sat, 15 Mar 2025 20:23:29 +0000
Subject: [PATCH] [Github][Docs] Add best practice for top level read
 permissions

This patch adds a section pointing out how permissions should be done
within Github workflows. I believe all of our workflows are currently
compliant with this, but it helps to have something to point to
documenting the practice and especially the motivation.
---
 llvm/docs/CIBestPractices.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/llvm/docs/CIBestPractices.rst b/llvm/docs/CIBestPractices.rst
index 398af21a9d966..6136224d65a19 100644
--- a/llvm/docs/CIBestPractices.rst
+++ b/llvm/docs/CIBestPractices.rst
@@ -92,3 +92,19 @@ image to a new version with potentially breaking changes, instead allowing us
 to explicitly opt-in to using the new image when we have done sufficient
 testing to ensure that our existing workflows work as expected in the new
 environment.
+
+Top Level Read Permissions
+--------------------------
+
+The top of every workflow should specify that the job only has read
+permissions:
+
+.. code-block:: yaml
+
+  permissions:
+    contents: read
+
+If specific jobs within the workflow need additional permissions, those
+permissions should be added within the specific job. This practice locks down
+all permissions by default and only enables them when needed, better enforcing
+the principal of least privilege.