add description to .gitleaks.toml

.gitleaks.toml

@@ -1,3 +1,18 @@
+# This file exists primarily to influence scheduled scans that Apollo runs of all repos in Apollo-managed orgs. 
+# This is an Apollo-Internal link, but more information about these scans is available here:
+# https://apollographql.atlassian.net/wiki/spaces/SecOps/pages/81330213/Everything+Static+Application+Security+Testing#Scheduled-Scans.1
+# 
+# Apollo is using Gitleaks (https://github.com/gitleaks/gitleaks) to run these scans.
+# However, this file is not something that Gitleaks natively consumes. This file is an
+# Apollo-convention. Prior to scanning a repo, Apollo merges
+# our standard Gitleaks configuration (which is largely just the Gitleaks-default config) with
+# this file if it exists in a repo. The combined config is then used to scan a repo.
+# 
+# We did this because the natively-supported allowlisting functionality in Gitleaks didn't do everything we wanted
+# or wasn't as robust as we needed. For example, one of the allowlisting options offered by Gitleaks depends on the line number
+# on which a false positive secret exists to allowlist it. (https://github.com/gitleaks/gitleaks#gitleaksignore).
+# This creates a fairly fragile allowlisting mechanism. This file allows us to leverage the full capabilities of the Gitleaks rule syntax
+# to create allowlisting functionality.
 
 [[ rules ]]
     id = "high-entropy-base64"