update more docs

khorne3 · khorne3 · commit b3a81b714df3 · 2026-01-15T10:05:13.000-05:00
diff --git a/docs/semgrep-appsec-platform/azure-pr-comments.md b/docs/semgrep-appsec-platform/azure-pr-comments.md
@@ -65,7 +65,7 @@ To update your connection between Semgrep and Azure DevOps:
 3. Return to Semgrep and [<i class="fas fa-external-link fa-xs"></i> sign in](https://semgrep.dev/login).
 4. Go to **<i class="fa-solid fa-gear"></i> Settings > Source code managers**, and find your Azure DevOps connection.
 5. Click **Update access token**.
-6. In the **Update access token** that appears, provide the token granting full access that you created. Click **Update** to save and proceed.
+6. In the **Update access token** dialog that appears, provide the token you created. Click **Update** to save and proceed.
 7. Toggle the **Incoming webhooks** setting on.
 
 Once you've successfully turned on the triage by PR comment feature, you can change the token you provide to Semgrep to one that's more restrictive. The token scopes required for the more restrictive token are:
diff --git a/docs/semgrep-appsec-platform/bitbucket-cloud-pr-comments.md b/docs/semgrep-appsec-platform/bitbucket-cloud-pr-comments.md
@@ -114,17 +114,22 @@ Confirm that you have the correct connection and access:
 
 #### Triage through PR comments
 
-If you want developers to able to triage findings via their MR comments, without leaving Bitbucket, you must have provided a Bitbucket workspace access token to Semgrep. Triage through PR comments is not supported with repository access tokens.
-
-The workspace access tokens must be created by a user with the Product Admin role. The scopes you must assign to the token include:
-
-* webhook (read and write)
-* repository (read and write)
-* pullrequest (read and write)
-* project (admin)
-* account (read)
-
-Once you have triage through PR comments fully configured, you can update the token's role and scopes to be more restrictive (how restrictive?).
+Developers can triage Semgrep findings without leaving Bitbucket by responding to the PR comments authored by Semgrep. To turn this feature on, you must update your Semgrep organization's connection to Bitbucket to use a workspace access token or an HTTP access token. This allows you to enable webhooks, which Semgrep requires for the triage through PR comment feature.
+
+To update your connection between Semgrep and Bitbucket:
+
+1. Log in to Bitbucket using an account assigned with the **Product Admin** role.
+2. [Create a workspace access token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/). Ensure that you assign the following scopes to the token:
+   - `webhook (read and write)`
+   - `repository (read and write)`
+   - `pullrequest (read and write)`
+   - `project (admin)`
+   - `account (read)`
+3. Return to Semgrep and [<i class="fas fa-external-link fa-xs"></i> sign in](https://semgrep.dev/login).
+4. Go to **<i class="fa-solid fa-gear"></i> Settings > Source code managers**, and find your Bitbucket connection.
+5. Click **Update access token**.
+6. In the **Update access token** dialog that appears, provide the new token you created. Click **Update** to save and proceed.
+7. Toggle the **Incoming webhooks** setting on.
 
 ### Define the `BITBUCKET_TOKEN` environment variable
 
diff --git a/docs/semgrep-appsec-platform/bitbucket-data-center-pr-comments.md b/docs/semgrep-appsec-platform/bitbucket-data-center-pr-comments.md
@@ -59,14 +59,18 @@ Confirm that you have the correct connection and access:
 
 #### Triage through PR comments
 
-If you want developers to able to triage findings via their MR comments, without leaving Bitbucket, you must have:
-
-- Bitbucket Data Center v8.8 or above
-- A Bitbucket HTTP access token in the Source code manager (SCM) connection to Semgrep, created by a user with the Project Admin role.
-
-This access token must be created with PROJECT_ADMIN permissions. Project-level webhooks are required to support triage though PR comments.
-
-After providing a token with the appropriate role and permissions, enable the **Incoming webhooks** toggle on the SCM connection for the Bitbucket project.
+Developers can triage Semgrep findings without leaving Bitbucket by responding to the PR comments authored by Semgrep. To turn this feature on, you must update your Semgrep organization's connection to Bitbucket to use a workspace access token or an HTTP access token. This allows you to enable webhooks, which Semgrep requires for the triage through PR comment feature.
+
+To update your connection between Semgrep and Bitbucket:
+
+1. Ensure that you're using Bitbucket Data Center version 8.8 or later.
+2. Log in to Bitbucket using an account assigned with the **Project Admin** role.
+3. [Create an HTTP access token](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html). When setting the token's **Project permissions**, ensure that you select **Project admin**.
+4. Return to Semgrep and [<i class="fas fa-external-link fa-xs"></i> sign in](https://semgrep.dev/login).
+5. Go to **<i class="fa-solid fa-gear"></i> Settings > Source code managers**, and find your Bitbucket connection.
+6. Click **Update access token**.
+7. In the **Update access token** dialog that appears, provide the new token you created. Click **Update** to save and proceed.
+8. Toggle the **Incoming webhooks** setting on.
 
 ### Configure comments for Semgrep Code
 
diff --git a/docs/semgrep-appsec-platform/gitlab-mr-comments.md b/docs/semgrep-appsec-platform/gitlab-mr-comments.md
@@ -59,21 +59,25 @@ PR comments are enabled by default for users who have connected their GitLab gro
 
 #### Triage though MR comment
 
-If you want developers to able to triage findings via their MR comments, without leaving GitLab, you must also have one of the following plans:
-
-- GitLab Premium
-- GitLab Ultimate
-- GitLab Self Managed
-
-The token used in the Source code manager (SCM) connection to the GitLab group must have one of the following roles:
-
-- `Maintainer`
-- `Owner`
-- `Admin`
-
-This is because GitLab repositories require the enablement of webhooks allow Semgrep to be notified of new review comments. After providing a token with the appropriate role, enable the **Incoming webhooks** toggle on the SCM connection.
-
-Once the toggle is enabled and webhooks have been created, you can downgrade the role assigned to the token to `Developer`.
+Developers can triage Semgrep findings without leaving GitLab by responding to the MR comments authored by Semgrep. To turn this feature on, you must update your Semgrep organization's connection to GitLab to use an access token with an elevated role. This allows you to enable webhooks, which Semgrep requires for the triage through MR comment feature.
+
+To update your connection between Semgrep and GitLab:
+
+1. Ensure that you're using one of the following GitLab plans:
+   - GitLab Premium
+   - GitLab Ultimate
+   - GitLab Self Managed
+2. Log in to GitLab, and create an access token with one of the following roles assigned:
+   - `Maintainer`
+   - `Owner`
+   - `Admin`
+3. Return to Semgrep and [<i class="fas fa-external-link fa-xs"></i> sign in](https://semgrep.dev/login).
+4. Go to **<i class="fa-solid fa-gear"></i> Settings > Source code managers**, and find your GitLab connection.
+5. Click **Update access token**.
+6. In the **Update access token** dialog that appears, provide the new token you created. Click **Update** to save and proceed.
+7. Toggle the **Incoming webhooks** setting on.
+
+Once you've successfully turned on the triage by PR comment feature, you can change the token you provide to Semgrep to one that's more restrictive. You can downgrade the role assigned to the token to `Developer`.
 
 ### Configure comments for Semgrep Code
 
diff --git a/docs/semgrep-code/triage-remediation.md b/docs/semgrep-code/triage-remediation.md
@@ -185,21 +185,23 @@ You can triage your Semgrep AppSec Platform findings displayed as comments in PR
 Before proceeding, ensure that you have:
  - One or more repositories hosted by a [Semgrep-supported source code manager (SCM)](/getting-started/scm-support).
  - Configured [PR or MR comments](/category/pr-or-mr-comments) for your SCM.
- - For SCMs other than GitHub: granted Semgrep permission to interact with pull requests and create webhooks for your SCM, and enabled the **Incoming webhooks** option on the SCM connection.
+ - *For SCMs other than GitHub:*
+   - Granted Semgrep permission to interact with pull requests and create webhooks for your SCM
+   - Enabled the **Incoming webhooks** option on the SCM connection
 
-### Granting permissions
+### Grant permission to interact with pull requests and create webhooks for your SCM
 
-Use the steps included under **Triage through PR/MR comment** in the PR/MR comment guides if you need assistance granting the correct permissions to enable pull request interaction and webhook management.
+See the following documents for instructions on granting the correct permissions to enable pull request interaction and webhook management:
 
 - [GitLab](/docs/semgrep-appsec-platform/gitlab-mr-comments#triage-through-mr-comment)
 - [Bitbucket Cloud](/docs/semgrep-appsec-platform/bitbucket-cloud-pr-comments#triage-through-pr-comment)
 - [Bitbucket Data Center](/docs/semgrep-appsec-platform/bitbucket-cloud-pr-comments#triage-through-pr-comment)
 - [Azure DevOps](/docs/semgrep-appsec-platform/azure-pr-comments#triage-through-pr-comment)
 
-To triage a finding:
+Once you've turned on this feature, you can triage a finding using the following steps:
 
 1. Find an open comment created by Semgrep in your pull request or merge request.
-2. In a subsequent comment, reply with the action you want to take. You must provide a reason to help the reader understand why the finding has been triaged as ignored:
+2. Reply to the comment with the action you want to take. You must provide a reason to help the reader understand why the finding has been triaged as ignored:
  <TriageReason />
  Semgrep attempts to reply to your comment if it successfully triages the finding.
 
