This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
The following commit(s) were added to refs/heads/main by this push:
new 4d14f1d9cc feat: add the bitbucket manuals (#401)
4d14f1d9cc is described below
commit 4d14f1d9cc61798e7052b3295bc9dc7efda492a1
Author: Louis.z <[email protected]>
AuthorDate: Tue Jan 17 19:52:55 2023 +0800
feat: add the bitbucket manuals (#401)
* feat: add the bitbucket manuals
* fix: anchor links for advanced mode
Co-authored-by: Startrekzky <[email protected]>
---
docs/UserManuals/ConfigUI/BitBucket.md | 66 +++++++++++++++++++++
docs/UserManuals/ConfigUI/GitHub.md | 11 +++-
docs/UserManuals/ConfigUI/GitLab.md | 14 +++--
docs/UserManuals/ConfigUI/Jenkins.md | 6 ++
docs/UserManuals/ConfigUI/Jira.md | 9 ++-
docs/UserManuals/ConfigUI/Tapd.md | 9 ++-
docs/UserManuals/ConfigUI/Zentao.md | 13 +++-
.../ConfigUI/bitbucket-add-data-connections.png | Bin 0 -> 88775 bytes
.../bitbucket-app-password-permissions.jpeg | Bin 0 -> 62725 bytes
9 files changed, 114 insertions(+), 14 deletions(-)
diff --git a/docs/UserManuals/ConfigUI/BitBucket.md
b/docs/UserManuals/ConfigUI/BitBucket.md
new file mode 100644
index 0000000000..317be3e8d7
--- /dev/null
+++ b/docs/UserManuals/ConfigUI/BitBucket.md
@@ -0,0 +1,66 @@
+---
+title: "Configuring BitBucket(Beta)"
+sidebar_position: 2
+description: Config UI instruction for BitBucket(Cloud)
+---
+
+Visit config-ui: `http://localhost:4000` and go to `Connections` page.
+
+### Step 1 - Add Data Connections
+
+
+
+#### Connection Name
+
+Name your connection.
+
+#### Endpoint URL
+
+This should be a valid REST API endpoint for BitBucket:
`https://api.bitbucket.org/2.0/`. The endpoint URL should end with `/`.
+
+DevLake will support BitBucket Server in the future.
+
+#### Authentication
+
+BitBucket `username` and `app password` are required to add a connection.
Learn about [how to create a BitBucket app
password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/).
+
+The following permissions are required to collect data from BitBucket
repositories:
+
+- Account:Read
+- Workspace membership:Read
+- Projects:Read
+- Repositories:Read
+- Pull requests:Read
+- Issues:Read
+- Pipelines:Read
+- Runners:Read
+
+
+
+
+#### Proxy URL (Optional)
+
+If you are behind a corporate firewall or VPN you may need to utilize a proxy
server. Enter a valid proxy server address on your network, e.g.
`http://your-proxy-server.com:1080`
+
+
+#### Fixed Rate Limit (Optional)
+
+DevLake uses a dynamic rate limit to collect BitBucket data. You can adjust
the rate limit if you want to increase or lower the speed.
+
+The maximum rate limit for different entities in BitBucket(Cloud) is [60,000
or 1,000
requests/hour](https://support.atlassian.com/bitbucket-cloud/docs/api-request-limits/).
Please do not use a rate that exceeds this number.
+
+
+#### Test and Save Connection
+
+Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
+
+
+### Step 2 - Configure Blueprint
+
+Similar to other beta plugins, BitBucket does not support `project`, which
means, you can only collect BitBucket data via blueprint's advanced mode.
+
+Please go to the `Blueprints` page and switch to advanced mode. See how to use
advanced mode and JSON [examples](AdvancedMode.md).
+
+### Troubleshooting
+
+If you run into any problem, please check the
[Troubleshooting](/Troubleshooting/Configuration.md) or [create an
issue](https://github.com/apache/incubator-devlake/issues)
diff --git a/docs/UserManuals/ConfigUI/GitHub.md
b/docs/UserManuals/ConfigUI/GitHub.md
index 391771fc1c..4cb53afc1d 100644
--- a/docs/UserManuals/ConfigUI/GitHub.md
+++ b/docs/UserManuals/ConfigUI/GitHub.md
@@ -31,6 +31,8 @@ Learn about [how to create a GitHub personal access
token](https://docs.github.c
- `read:user`
- `read:org`
+The data collection speed is restricted by the **rate limit of [5,000
requests](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)
per hour per token** (15,000 requests/hour if you pay for GitHub enterprise).
You can accelerate data collection by configuring _multiple_ personal access
tokens. Please note that multiple tokens should be created by different GitHub
accounts. Tokens belonging to the same GitHub account share the rate limit.
+
###### Fine-grained personal access tokens
Note: this token doesn't support GraphQL APIs. You have to disable `Use
GraphQL APIs` on the connection page if you want to use it. However, this will
significantly increase the data collection time.
@@ -44,9 +46,6 @@ The token should be granted read-only permission for the
following entities.
- `Metadata`
- `Pull requests`
-###### Rate Limit
-The data collection speed is restricted by the **rate limit of [5,000
requests](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)
per hour per token** (15,000 requests/hour if you pay for GitHub enterprise).
You can accelerate data collection by configuring _multiple_ personal access
tokens. Please note that multiple tokens should be created by different GitHub
accounts. Tokens belonging to the same GitHub account share the rate limit.
-
#### Use Graphql APIs
If you are using `github.com` or your on-premise GitHub version supports
GraphQL APIs, toggle on this setting to collect data quicker.
@@ -58,6 +57,12 @@ If you are using `github.com` or your on-premise GitHub
version supports GraphQL
If you are behind a corporate firewall or VPN you may need to utilize a proxy
server. Enter a valid proxy server address on your network, e.g.
`http://your-proxy-server.com:1080`
+#### Fixed Rate Limit (Optional)
+
+DevLake uses a dynamic rate limit to collect GitHub data. You can adjust the
rate limit if you want to increase or lower the speed.
+
+The maximum rate limit for GitHub is ** [5,000
requests/hour](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)**
(15,000 requests/hour if you pay for GitHub enterprise). Please do not use a
rate that exceeds this number.
+
#### Test and Save Connection
Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
diff --git a/docs/UserManuals/ConfigUI/GitLab.md
b/docs/UserManuals/ConfigUI/GitLab.md
index f87846ecea..f1db518f2b 100644
--- a/docs/UserManuals/ConfigUI/GitLab.md
+++ b/docs/UserManuals/ConfigUI/GitLab.md
@@ -20,7 +20,7 @@ This should be a valid REST API endpoint.
- If you are using gitlab.com, the endpoint will be
`https://gitlab.com/api/v4/`
- If you are self-hosting GitLab, the endpoint will look like
`https://gitlab.example.com/api/v4/`
- The endpoint url should end with `/`.
+ The endpoint URL should end with `/`.
#### Auth Token(s)
@@ -40,14 +40,18 @@ You also have to double-check your GitLab user permission
settings.
1. Go to the Project information -> Members page of the GitLab projects you
wish to collect.
2. Check your role in this project from the Max role column. Make sure you are
not the Guest role, otherwise, you will not be able to collect data from this
project.
-###### Rate Limit
-
-The data collection speed is restricted by the **rate limit of [120,000
requests/hour](https://docs.gitlab.com/ee/user/gitlab_com/index.html#gitlabcom-specific-rate-limits)**
for GitLab Cloud. Tokens under the same IP address share the rate limit, so
the actual rate limit for your token will be lower than this number.
-
#### Proxy URL (Optional)
If you are behind a corporate firewall or VPN you may need to utilize a proxy
server. Enter a valid proxy server address on your network, e.g.
`http://your-proxy-server.com:1080`
+#### Fixed Rate Limit (Optional)
+
+DevLake uses a dynamic rate limit at around 12,000 requests/hour to collect
GitLab data. You can adjust the rate limit if you want to increase or lower the
speed.
+
+The maximum rate limit for GitLab Cloud is ** [120,000
requests/hour](https://docs.gitlab.com/ee/user/gitlab_com/index.html#gitlabcom-specific-rate-limits)**.
Tokens under the same IP address share the rate limit, so the actual rate
limit for your token will be lower than this number.
+
+For self-managed GitLab rate limiting, please contact your GitLab admin to
[get or set the maximum rate
limit](https://repository.prace-ri.eu/git/help/security/rate_limits.md) of your
GitLab instance. Please do not use a rate that exceeds this number.
+
#### Test and Save Connection
Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
diff --git a/docs/UserManuals/ConfigUI/Jenkins.md
b/docs/UserManuals/ConfigUI/Jenkins.md
index 579451aa30..41ba2d6e51 100644
--- a/docs/UserManuals/ConfigUI/Jenkins.md
+++ b/docs/UserManuals/ConfigUI/Jenkins.md
@@ -26,6 +26,12 @@ Your User ID for the Jenkins Instance.
For help on Username and Password, please see Jenkins docs on [using
credentials](https://www.jenkins.io/doc/book/using/using-credentials/). You can
also use "API Access Token" for this field, which can be generated at `User` ->
`Configure` -> `API Token` section on Jenkins.
+#### Fixed Rate Limit (Optional)
+
+DevLake uses a dynamic rate limit to collect Jenkins data. You can adjust the
rate limit if you want to increase or lower the speed.
+
+There is not any doc about Jenkins rate limiting. Please put up an issue if
you find one.
+
#### Test and Save Connection
Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
diff --git a/docs/UserManuals/ConfigUI/Jira.md
b/docs/UserManuals/ConfigUI/Jira.md
index a1b32a2120..f9aaf2683a 100644
--- a/docs/UserManuals/ConfigUI/Jira.md
+++ b/docs/UserManuals/ConfigUI/Jira.md
@@ -5,6 +5,7 @@ description: Config UI instruction for Jira
---
Visit config-ui: `http://localhost:4000`.
+
### Step 1 - Add Data Connections
@@ -20,7 +21,6 @@ The endpoint url should end with `/`.
#### Username / Email
Input the username or email of your Jira account.
-
#### Password
- If you are using Jira Cloud, please input the [Jira personal access
token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).
- If you are using Jira Server v8+, please input the password of your Jira
account.
@@ -28,6 +28,13 @@ Input the username or email of your Jira account.
#### Proxy URL (Optional)
If you are behind a corporate firewall or VPN you may need to utilize a proxy
server. Enter a valid proxy server address on your network, e.g.
`http://your-proxy-server.com:1080`
+#### Fixed Rate Limit (Optional)
+
+DevLake uses a dynamic rate limit to collect Jira data. You can adjust the
rate limit if you want to increase or lower the speed. If you encounter a 403
error during data collection, please lower the rate limit.
+
+Jira(Cloud) uses a dynamic rate limit and has no clear rate limit. For Jira
Server's rate limiting, please contact your Jira Server admin to [get or set
the maximum rate
limit](https://repository.prace-ri.eu/git/help/security/rate_limits.md) of your
Jira instance. Please do not use a rate that exceeds this number.
+
+
#### Test and Save Connection
Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
diff --git a/docs/UserManuals/ConfigUI/Tapd.md
b/docs/UserManuals/ConfigUI/Tapd.md
index 995489fd45..c65270d449 100644
--- a/docs/UserManuals/ConfigUI/Tapd.md
+++ b/docs/UserManuals/ConfigUI/Tapd.md
@@ -4,7 +4,8 @@ sidebar_position: 6
description: Config UI instruction for Tapd
---
-Visit config-ui: `http://localhost:4000`.
+Visit config-ui: `http://localhost:4000` and go to `Connections` page.
+
### Step 1 - Add Data Connections
@@ -29,8 +30,12 @@ For TAPD, we suggest you setting the rate limit to 3500
#### Test and Save Connection
Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
+### Step 2 - Configure Blueprint
+
+Similar to other beta plugins, TAPD does not support `project`, which means,
you can only collect TAPD data via blueprint's advanced mode.
+Please go to the `Blueprints` page and switch to advanced mode. See how to use
advanced mode and JSON [examples](AdvancedMode.md#6-tapd).
-## Troubleshooting
+### Troubleshooting
If you run into any problem, please check the
[Troubleshooting](/Troubleshooting/Configuration.md) or [create an
issue](https://github.com/apache/incubator-devlake/issues)
diff --git a/docs/UserManuals/ConfigUI/Zentao.md
b/docs/UserManuals/ConfigUI/Zentao.md
index 9f5d189058..d8cfde289a 100644
--- a/docs/UserManuals/ConfigUI/Zentao.md
+++ b/docs/UserManuals/ConfigUI/Zentao.md
@@ -4,7 +4,8 @@ sidebar_position: 6
description: Config UI instruction for Zentao
---
-Visit config-ui: `http://localhost:4000`.
+Visit config-ui: `http://localhost:4000` and go to `Connections` page.
+
### Step 1 - Add Data Connections
@@ -16,7 +17,7 @@ This should be a valid REST API endpoint
- `https://YOUR_DOMAIN:YOUR_PORT/`
The endpoint url should end with `/`.
-#### Username / Password
+#### Username/Password
Input the username and password of your Zentao account.
#### Proxy URL (Optional)
@@ -25,6 +26,12 @@ If you are behind a corporate firewall or VPN you may need
to utilize a proxy se
#### Test and Save Connection
Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
-## Troubleshooting
+### Step 2 - Configure Blueprint
+
+Similar to other beta plugins, Zentao does not support `project`, which means,
you can only collect Zentao data via blueprint's advanced mode.
+
+Please go to the `Blueprints` page and switch to advanced mode. See how to use
advanced mode and JSON [examples](AdvancedMode.md#8-zentao).
+
+### Troubleshooting
If you run into any problem, please check the
[Troubleshooting](/Troubleshooting/Configuration.md) or [create an
issue](https://github.com/apache/incubator-devlake/issues)
diff --git a/static/img/ConfigUI/bitbucket-add-data-connections.png
b/static/img/ConfigUI/bitbucket-add-data-connections.png
new file mode 100644
index 0000000000..78ab5375f7
Binary files /dev/null and
b/static/img/ConfigUI/bitbucket-add-data-connections.png differ
diff --git a/static/img/ConfigUI/bitbucket-app-password-permissions.jpeg
b/static/img/ConfigUI/bitbucket-app-password-permissions.jpeg
new file mode 100644
index 0000000000..c3c28ff06a
Binary files /dev/null and
b/static/img/ConfigUI/bitbucket-app-password-permissions.jpeg differ
