update roles and scopes information (#2216)

Author: khorne3

docs/deployment/managed-scanning/gitlab.md

@@ -66,7 +66,8 @@ You can enabled managed scanning for additional repositories after onboarding us
 
 ### If the page doesn't display any repositories
 
-1. Ensure that you've connected your GitLab account by following the steps in [Connect a source code manager](/deployment/connect-scm) and confirm the PAT is created with the required `API` scope and [a role of, at minimum, Reporter](https://docs.gitlab.com/ee/user/permissions.html#roles).
+1. Ensure that you've connected your GitLab account by following the steps in [Connect a source code manager](/deployment/connect-scm) and confirm the [PAT is created with the required `API` scope](https://docs.gitlab.com/user/profile/personal_access_tokens/#personal-access-token-scopes) by someone assigned the [role of **Maintainer** or **Owner**](https://docs.gitlab.com/ee/user/permissions.html#roles).
+   1. Once you successfully create the connection, the role for the person who owns the token can be downgraded to **Developer**.
 2. In Semgrep AppSec Platform, click **<i class="fa-solid fa-folder-open"></i> Projects**.
 3. If the page doesn't display the repository you want to add, click **Can't find your project? > Sync projects**.
 4. If the page doesn't display any repositories, click **Sync projects**.

docs/semgrep-appsec-platform/bitbucket-data-center-pr-comments.md

@@ -47,7 +47,7 @@ PR comments appear for the following types of scans under these conditions:
 ### Prerequisites
 
 In addition to finishing the previous steps in your deployment journey, it is recommended that you complete a **full scan** on your **default branch** for the repository in which you want to receive comments.
-- You must have a Bitbucket Data Center HTTP access token. Ensure that the [token HTTP access token that you create](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) has been granted **Project write** permissions. You'll provide this token to your CI provider during the setup process.
+- You must have a Bitbucket Data Center HTTP access token. Ensure that the [HTTP access token that you create](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) has been granted **Project write** permissions. You'll provide this token to your CI provider during the setup process.
 - Semgrep has been tested with Bitbucket Data Center v8.19. If you are using a different version of BBDC and there are issues, please contact [<i class="fa-regular fa-envelope"></i> support@semgrep.com](mailto:support@semgrep.com).
 
 ### Confirm your Semgrep account's connection

docs/semgrep-appsec-platform/gitlab-mr-comments.md

@@ -57,10 +57,11 @@ To enable MR comments, connect your GitLab organization to Semgrep AppSec Platfo
 1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login?return_path=/manage/projects).
 1. Go to **Settings > Source code managers**.
 1. Click **Add connection** and select **GitLab**.
-3. Create a GitLab personal access token (PAT) with `api` scope:
-   1. Log in to your GitLab account, and go to [<i class="fas fa-external-link fa-xs"></i> Profile > Access Tokens](https://gitlab.com/-/profile/personal_access_tokens).
-   2. Add a token with `api` scope.
-   3. Copy the generated token.
+3. Create a GitLab [personal access token (PAT) with `api` scope](https://docs.gitlab.com/user/profile/personal_access_tokens/#personal-access-token-scopes):
+   1. Ensure that you're using an account that has been [assigned a role of `Developer` or higher](https://docs.gitlab.com/user/permissions/#roles), and log in to GitLab.
+   2. Go to [<i class="fas fa-external-link fa-xs"></i> Profile > Access Tokens](https://gitlab.com/-/profile/personal_access_tokens).
+   3. Add a token with `api` scope.
+   4. Copy the generated token.
 4. Return to Semgrep AppSec Platform, and in the **Add connection** form:
    1. Enter the **Name of your GitHub Organization**.
    2. Paste the PAT you created in **Access token**.

docs/semgrep-ci/network-broker.md

@@ -48,7 +48,7 @@ Ensure that you are logged in to the server where you want to run Semgrep Networ
 
 <TabItem value='current'>
 
-Create a `config.yaml` file similar to the following snippet, or copy a starting config from the Semgrep AppSec Platform at  **Settings > Broker**. The steps required to generate values for the placeholders `SEMGREP_LOCAL_ADDRESS`, `YOUR_PRIVATE_KEY`, and `YOUR_BASE_URL` are provided in subsequent steps of this guide.
+Create a `config.yaml` file similar to the following snippet, or copy a starting config from the Semgrep AppSec Platform at  **Settings > Broker**. The steps required to generate values for the placeholders `SEMGREP_LOCAL_ADDRESS`, `YOUR_PRIVATE_KEY`, and `YOUR_BASE_URL`, as well as the scopes required for the access tokens, are provided in subsequent steps of this guide.
 
 ```yaml
   inbound:
@@ -153,6 +153,9 @@ azuredevops:
 &nbsp;&nbsp;token: <span className="placeholder">ADO_PAT</span>
 </code></pre>
 
+:::info Access tokens
+Semgrep recommends providing the access token when you [connect the source code manager](/deployment/connect-scm#connect-to-cloud-hosted-orgs) instead of in the Network Broker configuration. However, if you must provide the token in the network broker configuration, see [Prerequisites](/semgrep-appsec-platform/azure-pr-comments#prerequisites) for access token requirements.
+:::
 </TabItem>
 
 <TabItem value='bb'>
@@ -165,6 +168,12 @@ bitbucket:
 &nbsp;&nbsp;token: <span className="placeholder">BITBUCKET_ACCESS_TOKEN</span>
 </code></pre>
 
+:::info Access tokens
+Semgrep recommends providing the access token when you [connect the source code manager](/deployment/connect-scm) instead of in the Network Broker configuration. However, if you must provide the token in the network broker configuration, see Prerequisites for access token requirements:
+- [Bitbucket Cloud](/semgrep-appsec-platform/bitbucket-cloud-pr-comments#create-and-add-a-workspace-access-token)
+- [Bitbucket Data Center](/semgrep-appsec-platform/bitbucket-data-center-pr-comments#prerequisites)
+:::
+
 </TabItem>
 <TabItem value='gh'>
 
@@ -183,6 +192,10 @@ gitlab:
 &nbsp;&nbsp;token: <span className="placeholder">GITLAB_PAT</span>
 </code></pre>
 
+:::info Access token
+Semgrep recommends providing the access token when you [connect the source code manager](/deployment/connect-scm#connect-to-cloud-hosted-orgs) instead of in the Network Broker configuration. However, if you must provide the token in the network broker configuration, see [Prerequisites](/semgrep-appsec-platform/gitlab-mr-comments#prerequisites) for access token requirements.
+:::
+
 </TabItem>
 </Tabs>
 
@@ -275,6 +288,10 @@ azuredevops:
 &nbsp;&nbsp;allowCodeAccess: true
 </code></pre>
 
+:::info Access tokens
+Semgrep recommends providing the access token when you [connect the source code manager](/deployment/connect-scm#connect-to-cloud-hosted-orgs) instead of in the Network Broker configuration. However, if you must provide the token in the network broker configuration, see [Prerequisites and permissions](/deployment/managed-scanning/azure#prerequisites-and-permissions) for access token requirements.
+:::
+
 </TabItem>
 
 <TabItem value='bb'>
@@ -286,6 +303,10 @@ bitbucket:
 &nbsp;&nbsp;allowCodeAccess: true
 </code></pre>
 
+:::info Access tokens
+Semgrep recommends providing the access token when you [connect the source code manager](/deployment/connect-scm#connect-to-cloud-hosted-orgs) instead of in the Network Broker configuration. However, if you must provide the token in the network broker configuration, see [Prerequisites and permissions](/deployment/managed-scanning/bitbucket#prerequisites-and-permissions) for access token requirements.
+:::
+
 </TabItem>
 <TabItem value='gh'>
 
@@ -306,6 +327,10 @@ gitlab:
 &nbsp;&nbsp;allowCodeAccess: true
 </code></pre>
 
+:::info Access tokens
+Semgrep recommends providing the access token when you [connect the source code manager](/deployment/connect-scm#connect-to-cloud-hosted-orgs) instead of in the Network Broker configuration. However, if you must provide the token in the network broker configuration, see [Prerequisites and permissions](/deployment/managed-scanning/gitlab#prerequisites-and-permissions) for access token requirements.
+:::
+
 </TabItem>
 </Tabs>