Webhooks access and permissions for triage by comment

[armchairlinguist]

Fixing a few issues where we don't clearly articulate requirements for feature support related to webhooks (particularly GitLab Free).

Fixes https://linear.app/semgrep/issue/TEC-492/ensure-webhooks-requirementssupport-are-properly-documented.

Please ensure

• A subject matter expert (SME) reviews the content
• A technical writer reviews the content or PR
• This change has no security implications or else you have pinged the security team
• Redirects are added if the PR changes page URLs
• If you have changed any header tag links (doc/#this-kind-of-anchor), update all instances of that link

---

Adding a new documentation page? Click to expand the checklist

• Create .md or .mdx file in /docs/[section]/ with frontmatter: slug, title, description, displayed_sidebar, tags
• Add page to appropriate sidebar in /sidebars.js (shows in side nav)
• If adding the doc in a new directory: Update /src/theme/Navbar/Content/index.tsx → add path to getCurrentSection() (highlights top nav)

Sidebars fields for displayed_sidebar:
scanSidebar | rulewritingSidebar | devSidebar | learnSidebar | aboutSidebar | kbSidebar | whatsSemgrepSidebar

Top nav fields for getCurrentSection():
'scan' | 'write-rules' | 'learning-guides' | 'help' | 'explore'

[netlify]

✅ Deploy Preview for semgrep-docs-prod ready!

Name	Link
🔨 Latest commit	d4017e3
🔍 Latest deploy log	https://app.netlify.com/projects/semgrep-docs-prod/deploys/6984fdd7087bb80008316a8a
😎 Deploy Preview	https://deploy-preview-2453--semgrep-docs-prod.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[khorne3]

@armchairlinguist I took the work you started and expanded it. I did reconsider updating the SMS snippets for reuse here, but I was afraid that the permissions required for these two features would diverge, so I did not. Perhaps we’ll decide to standardize the requirements for features that require code access, and at that point, we could revisit the use of snippets.

You'll also notice that I introduced a bit of redundancy -- because the user already has to go to so many places, I opted to include all of the instructions required in the Triage through PR comments section to minimize the need switch to other pages. I also cleaned up the dataflow traces information so that these pages no longer display irrelevant details.

Let me know what you think; I'd be happy to change anything or even go back to the drawing board if you think these changes hurt more than they help!

[armchairlinguist]

@khorne3 I think this is the way to go for now. I don't love how long the pages are with it, but partly that's just because the whole process is more complex than it ought to be, not a problem with the docs.

I did notice a few things when I was re-reading:

• We need to decide if it's called "by" or "through" and "comment" or "comments", since the current changes aren't consistent (I wasn't consistent, but I'm not sure it was before either lol). Or indeed "via" since that's what the toggle in the app is called. 😅
• BB pages are missing the "you can downgrade permissions" note. Maybe also the wording of that note should be more consistent?
• I don't love having the plan requirement for GL incorporated in to the bullets, I'd tend to want to call that out separately since changing your plan is a bigger deal than using a different token/role.
• It doesn't seem to be consistent how we introduce the cross-file findings + dataflow traces section - some have a separate section, on some it's within.

[armchairlinguist]

To be explicit - I can take that stuff on if you like, other than the wording which I think we should decide mutually, or I'm happy for you to continue.

[khorne3]

@armchairlinguist Sorry for the delay -- my email dumped all my GitHub notifications into spam (I was wondering why things were so quiet).

Because we use through in lieu of via pretty much everywhere else, let's do "Triage through PR comments" (plural)? I think it sounds a bit better than the singular, but singular versus plural doesn't matter that much to me

If you have time, feel free to continue. Otherwise, I'll pick this up near the end of next week when I'm done with release notes!

[armchairlinguist]

Picking up work on this again!

[khorne3]

Just some minor things -- thank you!