Skip to content

Commit 3313a7f

Browse files
isaidnocookiesisaidnocookies
committed
Add app token information
1 parent bf16f37 commit 3313a7f

File tree

6 files changed

+109
-2
lines changed

6 files changed

+109
-2
lines changed

‎_media/bitbucketAppPasswordCreation.png

77.8 KB
Loading

‎_media/gitlabAccessTokenCreation.png

87.6 KB
Loading

‎_sidebar.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
* Home
22
* [Home](/home.md)
33

4-
* Github Browser
5-
* [Setup](/docs/primitive-setup.md)
4+
* Cloud Platform
5+
* [General](/docs/cloud/general.md)
6+
* [Bitbucket App Passwords](/docs/cloud/bitbucket-tokens.md)
7+
* [GitLab Access Token](/docs/cloud/gitlab-tokens.md)
68

79
* Private Scraper Setup
810
* [Requirements](/docs/private/requirements.md)

‎docs/cloud/bitbucket-tokens.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Bitbucket App Passwords
2+
3+
Bitbucket app passwords are used to connect applications to your Git repositories. For information related to creating app passwords, please see the following documentation:
4+
5+
* [Atlassian Support for App Passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/)
6+
7+
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.
8+
9+
## App Password Creation
10+
11+
1. Go to <a href="https://bitbucket.org/account/settings/app-passwords/">bitbucket.org/account/settings/app-passwords</a>
12+
* This can be accessed via 'Profile' on the top right -> Settings -> Personal settings -> App passwords
13+
2. Select `Create app password`
14+
3. Provide a meaningful label
15+
* 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.
16+
4. Make sure the following permissions are selected:
17+
* `Account: Read`
18+
* `Workspace membership: Read`
19+
* `Projects: Read`
20+
* `Repositories: Read`
21+
5. Select `Create`
22+
6. Securely store or take note of the app password presented within the pop-up
23+
* This app password will not be shown again. If this is accidentally closed before copying, revoke it, and create a new one
24+
25+
## Primitive Permissions
26+
27+
Primitive requires READ access to:
28+
29+
* Account
30+
* Workspace Membership
31+
* Projects
32+
* Repositories
33+
34+
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.
35+
36+
<p><img src="/_media/bitbucketAppPasswordCreation.png" style="width: 90%; border: 1px solid #000;
37+
"></p>

‎docs/cloud/general.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Primitive Cloud Platform
2+
3+
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).
4+
5+
## App Passwords
6+
7+
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.
8+
9+
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:
10+
11+
1. Have an admin generate the token to provide the greatest visibility into various repositories.
12+
2. Create a new account with access to whichever repositories that are going to be analyzed by Primitive.
13+
3. Make sure the app passwords are scoped properly (i.e., read-only access).
14+
4. Be aware that admins of your scraper will have visibility into whichever repositories are associated with the account that created the app password.
15+
16+
For platform-specific information related to token/app password creation, please see below:
17+
18+
* [GitLab Access Tokens](/docs/cloud/gitlab-tokens.md)
19+
* [Bitbucket App Passwords](/docs/cloud/bitbucket-tokens.md)
20+
21+
## General Troubleshooting
22+
23+
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:
24+
25+
1. Scraping repositories through the admin interface
26+
2. Creating a new scraper via the cloud portal dashboard
27+
3. Accessing repositories within Primitive once repo-level permission checking is enabled
28+
29+
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);
30+
31+
* [GitLab Status Page](https://status.gitlab.com/)
32+
* [Bitbucket Status Page](https://bitbucket.status.atlassian.com/)

‎docs/cloud/gitlab-tokens.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# GitLab Access Tokens
2+
3+
GitLab Access Tokens are used to connect applications to your Git repositories. For information related to creating app passwords, please see the following documentation:
4+
5+
* [GitLab Personal Access Tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
6+
7+
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.
8+
9+
## App Password Creation
10+
11+
1. Go to <a href="https://gitlab.com/-/profile/personal_access_tokens/">gitlab.com/-/profile/personal_access_tokens</a>
12+
* This can be accessed via 'Profile' on the top right -> Edit profile -> Access Tokens
13+
2. Provide a meaningful token name
14+
* 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.
15+
4. Make sure the following permissions are selected:
16+
* `read_api`
17+
* `read_user`
18+
* `read_repositories`
19+
5. Select `Create personal access token`
20+
6. Securely store or take note of the app password presented after creation
21+
* This app password will not be shown again. If this is accidentally closed before copying, revoke it, and create a new one
22+
23+
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.
24+
25+
## Primitive Permissions
26+
27+
Primitive requires READ access to:
28+
29+
* read_api
30+
* read_user
31+
* read_repositories
32+
33+
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.
34+
35+
<p><img src="/_media/gitlabAccessTokenCreation.png" style="width: 90%; border: 1px solid #000;
36+
"></p>

0 commit comments

Comments
 (0)