Add app token information

_sidebar.md

@@ -1,8 +1,10 @@
 * Home
   * [Home](/home.md)
 
-* Github Browser
-  * [Setup](/docs/primitive-setup.md)
+* Cloud Platform
+  * [General](/docs/cloud/general.md)
+  * [Bitbucket App Passwords](/docs/cloud/bitbucket-tokens.md)
+  * [GitLab Access Token](/docs/cloud/gitlab-tokens.md)
 
 * Private Scraper Setup
   * [Requirements](/docs/private/requirements.md)

docs/cloud/bitbucket-tokens.md

@@ -0,0 +1,37 @@
+# Bitbucket App Passwords
+
+Bitbucket app passwords are used to connect applications to your Git repositories. For information related to creating app passwords, please see the following documentation:
+
+* [Atlassian Support for App Passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/)
+
+Once an app password is created, it can NOT be accessed via Bitbucket. Ensure this value is saved somewhere SECURE in case it is needed again. If a new one needs to be regenerated to create a new scraper, change credentials, or be rotated, ensure the old app password is revoked.
+
+## App Password Creation
+
+1. Go to <a href="https://bitbucket.org/account/settings/app-passwords/">bitbucket.org/account/settings/app-passwords</a>
+    * This can be accessed via 'Profile' on the top right -> Settings -> Personal settings -> App passwords
+2. Select `Create app password`
+3. Provide a meaningful label
+    * The label will help keep track of what app password is used for what application. This simplifies the process of revoking passwords when needed and eliminates guessing.
+4. Make sure the following permissions are selected:
+    * `Account: Read`
+    * `Workspace membership: Read`
+    * `Projects: Read`
+    * `Repositories: Read`
+5. Select `Create`
+6. Securely store or take note of the app password presented within the pop-up
+    * This app password will not be shown again. If this is accidentally closed before copying, revoke it, and create a new one
+
+## Primitive Permissions
+
+Primitive requires READ access to:
+
+* Account
+* Workspace Membership
+* Projects
+* Repositories
+
+These permissions are used to access what repositories you have access to analyze, information on permissions, and to clone the repository in order to complete the code analysis.
+
+<p><img src="/_media/bitbucketAppPasswordCreation.png" style="width: 90%; border: 1px solid #000;
+"></p>

docs/cloud/general.md

@@ -0,0 +1,32 @@
+# Primitive Cloud Platform
+
+Primitive's cloud platform allows analysis of your Git repositories on demand. Through your dashboard, you are able to create "scrapers" that connect to your online Git provider, pull information about the repo, and provide information back to the Primitive VR client. This process relies on access to the Git repositories and this is accomplished through application tokens generated within your Git service (e.g., Bitbucket, GitLab).
+
+## App Passwords
+
+Each Git platform provides the ability to generate scoped tokens to be used within applications or automation. These tokens or app passwords be be scoped to only allow certain privileges. As a general rule of thumb, Primitive needs to use tokens that have READ access to your repositories, and the associated APIs.
+
+Because the access tokens are usually associated with individuals, Git admins or those with access to many different repositories should set up the "scraper." This allows the associated scraper visibility to each of the repositories that the user has permission to access. With that said, here are some recommendations when integrating Primitive's cloud platform into your Git service:
+
+1. Have an admin generate the token to provide the greatest visibility into various repositories.
+2. Create a new account with access to whichever repositories that are going to be analyzed by Primitive.
+3. Make sure the app passwords are scoped properly (i.e., read-only access).
+4. Be aware that admins of your scraper will have visibility into whichever repositories are associated with the account that created the app password.
+
+For platform-specific information related to token/app password creation, please see below:
+
+* [GitLab Access Tokens](/docs/cloud/gitlab-tokens.md)
+* [Bitbucket App Passwords](/docs/cloud/bitbucket-tokens.md)
+
+## General Troubleshooting
+
+Because Primitive relies on a few APIs, there may be situations where the associated Git platform is unavailable or undergoing maintenance. This may affect the following actions:
+
+1. Scraping repositories through the admin interface
+2. Creating a new scraper via the cloud portal dashboard
+3. Accessing repositories within Primitive once repo-level permission checking is enabled
+
+As some of these are out of our control, please be patient with us as maintenance is completed or outages are resolved. If you are having issues with one of the above actions, reach out to [email protected] or confirm the underlying system is operational (Git status pages);
+
+* [GitLab Status Page](https://status.gitlab.com/)
+* [Bitbucket Status Page](https://bitbucket.status.atlassian.com/)

docs/cloud/gitlab-tokens.md

@@ -0,0 +1,36 @@
+# GitLab Access Tokens
+
+GitLab Access Tokens are used to connect applications to your Git repositories. For information related to creating app passwords, please see the following documentation:
+
+* [GitLab Personal Access Tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
+
+Once an app password is created, it can NOT be accessed again. Ensure this value is saved somewhere SECURE in case it is needed again. If a new one needs to be regenerated to create a new scraper, change credentials, or be rotated, ensure the old app password is revoked.
+
+## App Password Creation
+
+1. Go to <a href="https://gitlab.com/-/profile/personal_access_tokens/">gitlab.com/-/profile/personal_access_tokens</a>
+    * This can be accessed via 'Profile' on the top right -> Edit profile -> Access Tokens
+2. Provide a meaningful token name
+    * The label will help keep track of what app password is used for what application. This simplifies the process of revoking passwords when needed and eliminates guessing.
+4. Make sure the following permissions are selected:
+    * `read_api`
+    * `read_user`
+    * `read_repositories`
+5. Select `Create personal access token`
+6. Securely store or take note of the app password presented after creation
+    * This app password will not be shown again. If this is accidentally closed before copying, revoke it, and create a new one
+
+An expiration can also be added if needed. If the integration is expected to be long-term, this is not recommended as it may silently fail when the token expires and cause issues within Primitive.
+
+## Primitive Permissions
+
+Primitive requires READ access to:
+
+* read_api
+* read_user
+* read_repositories
+
+These permissions are used to access what repositories you have access to analyze, information on permissions, and to clone the repository in order to complete the code analysis.
+
+<p><img src="/_media/gitlabAccessTokenCreation.png" style="width: 90%; border: 1px solid #000;
+"></p>