This is an automated email from the ASF dual-hosted git repository.
zky 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 f9f9f953dc docs: jira auth token (#476)
f9f9f953dc is described below
commit f9f9f953dce047f63913af0faa93f8cb09f204ad
Author: abeizn <[email protected]>
AuthorDate: Tue Mar 28 20:32:20 2023 +0800
docs: jira auth token (#476)
* docs: jira auth token
* docs: update jira token auth
* docs: highlight the description for Jira roles
---------
Co-authored-by: Louis.z <[email protected]>
---
docs/Configuration/Jira.md | 44 ++++++++++++++++++----
.../version-v0.15/UserManuals/ConfigUI/Jira.md | 44 ++++++++++++++++++----
versioned_docs/version-v0.16/Configuration/Jira.md | 44 ++++++++++++++++++----
3 files changed, 111 insertions(+), 21 deletions(-)
diff --git a/docs/Configuration/Jira.md b/docs/Configuration/Jira.md
index 56655e7e5c..099063172f 100644
--- a/docs/Configuration/Jira.md
+++ b/docs/Configuration/Jira.md
@@ -7,25 +7,50 @@ description: Config UI instruction for Jira
Visit config-ui: `http://localhost:4000`.
### Step 1 - Add Data Connections
+
#### Connection Name
+
Name your connection.
#### Endpoint URL
+
This should be a valid REST API endpoint
- - If you are using Jira Cloud, the endpoint will be
`https://<mydomain>.atlassian.net/rest/`
- - If you are self-hosting Jira v7+ or v8+, the endpoint may look like
`https://jira.<mydomain>.com/rest/`
-The endpoint url should end with `/`.
+
+- If you are using Jira Cloud, the endpoint will be
`https://<mydomain>.atlassian.net/rest/`
+- If you are self-hosting Jira v7+ or v8+, the endpoint may look like
`https://jira.<mydomain>.com/rest/`
+ 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 v7+ or v8+, please input the password of your
Jira account.
+#### Auth Token
+
+When accessing Jira API using a Jira Auth Token, users may encounter access
restrictions if their token does not have sufficient permissions. This is
typically caused by insufficient scope or role settings for the Jira Auth Token.
+
+To solve this issue, users can take the following steps:
+
+- Checking User Permissions
+
+Users can confirm whether they have sufficient permissions by checking their
permissions in Jira. For cloud users, they can view their global and project
permissions through the "Permissions" tab on the "Profile" page. For server
users, they can log in to Jira as an administrator and view user permissions on
the "User Management" page.
+
+- Ensuring Sufficient Permissions
+
+Before using Jira API, users need to ensure that their account has at least
the necessary project or global permissions. Global permissions include various
Jira system settings and management operations, while project permissions
control specific operations and configurations for each Jira project. Users can
assign roles such as `Project Administrator`, `Project Lead`, `Developer`, etc.
for the corresponding projects, or assign global permissions such as `Jira
Administrators`, `Jira Soft [...]
+
+- Solving Access Restrictions
+
+To solve access restrictions caused by insufficient Jira Auth Token
permissions, users should check the token's permission settings to ensure the
correct scope and role are set. If the permission settings are correct but the
required API is still inaccessible, consider using other authentication
methods, such as authenticating with a username and password. If the issue
persists, contact the Jira administrator for further assistance.
+
#### 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)
@@ -34,25 +59,29 @@ DevLake uses a dynamic rate limit to collect Jira data. You
can adjust the rate
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.
+Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
### Step 2 - Setting Data Scope
+
#### Projects
+
Choose the Jira boards to collect.
#### Data Entities
+
Usually, you don't have to modify this part. However, if you don't want to
collect certain Jira entities, you can unselect some entities to accerlerate
the collection speed.
+
- Issue Tracking: Jira issues, issue comments, issue labels, etc.
- Cross Domain: Jira accounts, etc.
### Step 3 - Adding Transformation Rules (Optional)
+
-
+
Without adding transformation rules, you can not view all charts in "Jira" or
"Engineering Throughput and Cycle Time" dashboards.<br/>
Each Jira board has at most ONE set of transformation rules.
@@ -68,11 +97,12 @@ Each Jira board has at most ONE set of transformation rules.
- Story Point: choose the custom field that represents story points. In most
cases, it is "Story Points".
#### Additional Settings
+
- Remotelink Commit SHA: parse the commits from an issue's remote links by the
given regular expression so that the relationship between `issues` and
`commits` can be created. You can directly use the regular expression
`/commit/([0-9a-f]{40})$`.
### Step 4 - Setting Sync Frequency
-You can choose how often you would like to sync your data in this step by
selecting a sync frequency option or enter a cron code to specify your prefered
schedule.
+You can choose how often you would like to sync your data in this step by
selecting a sync frequency option or enter a cron code to specify your prefered
schedule.
## Troubleshooting
diff --git a/versioned_docs/version-v0.15/UserManuals/ConfigUI/Jira.md
b/versioned_docs/version-v0.15/UserManuals/ConfigUI/Jira.md
index f9aaf2683a..5e0b81dc0f 100644
--- a/versioned_docs/version-v0.15/UserManuals/ConfigUI/Jira.md
+++ b/versioned_docs/version-v0.15/UserManuals/ConfigUI/Jira.md
@@ -7,25 +7,50 @@ description: Config UI instruction for Jira
Visit config-ui: `http://localhost:4000`.
### Step 1 - Add Data Connections
+
#### Connection Name
+
Name your connection.
#### Endpoint URL
+
This should be a valid REST API endpoint
- - If you are using Jira Cloud, the endpoint will be
`https://<mydomain>.atlassian.net/rest/`
- - If you are self-hosting Jira v8+, the endpoint will look like
`https://jira.<mydomain>.com/rest/`
-The endpoint url should end with `/`.
+
+- If you are using Jira Cloud, the endpoint will be
`https://<mydomain>.atlassian.net/rest/`
+- If you are self-hosting Jira v8+, the endpoint will look like
`https://jira.<mydomain>.com/rest/`
+ 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.
+#### Auth Token
+
+When accessing Jira API using a Jira Auth Token, users may encounter access
restrictions if their token does not have sufficient permissions. This is
typically caused by insufficient scope or role settings for the Jira Auth Token.
+
+To solve this issue, users can take the following steps:
+
+- Checking User Permissions
+
+Users can confirm whether they have sufficient permissions by checking their
permissions in Jira. For cloud users, they can view their global and project
permissions through the "Permissions" tab on the "Profile" page. For server
users, they can log in to Jira as an administrator and view user permissions on
the "User Management" page.
+
+- Ensuring Sufficient Permissions
+
+Before using Jira API, users need to ensure that their account has at least
the necessary project or global permissions. Global permissions include various
Jira system settings and management operations, while project permissions
control specific operations and configurations for each Jira project. Users can
assign roles such as Project Administrator, Project Lead, Developer, etc. for
the corresponding projects, or assign global permissions such as Jira
Administrators, Jira Software Admi [...]
+
+- Solving Access Restrictions
+
+To solve access restrictions caused by insufficient Jira Auth Token
permissions, users should check the token's permission settings to ensure the
correct scope and role are set. If the permission settings are correct but the
required API is still inaccessible, consider using other authentication
methods, such as authenticating with a username and password. If the issue
persists, contact the Jira administrator for further assistance.
+
#### 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)
@@ -34,25 +59,29 @@ DevLake uses a dynamic rate limit to collect Jira data. You
can adjust the rate
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.
+Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
### Step 2 - Setting Data Scope
+
#### Projects
+
Choose the Jira boards to collect.
#### Data Entities
+
Usually, you don't have to modify this part. However, if you don't want to
collect certain Jira entities, you can unselect some entities to accerlerate
the collection speed.
+
- Issue Tracking: Jira issues, issue comments, issue labels, etc.
- Cross Domain: Jira accounts, etc.
### Step 3 - Adding Transformation Rules (Optional)
+
-
+
Without adding transformation rules, you can not view all charts in "Jira" or
"Engineering Throughput and Cycle Time" dashboards.<br/>
Each Jira board has at most ONE set of transformation rules.
@@ -68,11 +97,12 @@ Each Jira board has at most ONE set of transformation rules.
- Story Point: choose the custom field that represents story points. In most
cases, it is "Story Points".
#### Additional Settings
+
- Remotelink Commit SHA: parse the commits from an issue's remote links by the
given regular expression so that the relationship between `issues` and
`commits` can be created. You can directly use the regular expression
`/commit/([0-9a-f]{40})$`.
### Step 4 - Setting Sync Frequency
-You can choose how often you would like to sync your data in this step by
selecting a sync frequency option or enter a cron code to specify your prefered
schedule.
+You can choose how often you would like to sync your data in this step by
selecting a sync frequency option or enter a cron code to specify your prefered
schedule.
## Troubleshooting
diff --git a/versioned_docs/version-v0.16/Configuration/Jira.md
b/versioned_docs/version-v0.16/Configuration/Jira.md
index f0d4732747..422b7c8c1d 100644
--- a/versioned_docs/version-v0.16/Configuration/Jira.md
+++ b/versioned_docs/version-v0.16/Configuration/Jira.md
@@ -7,25 +7,50 @@ description: Config UI instruction for Jira
Visit config-ui: `http://localhost:4000`.
### Step 1 - Add Data Connections
+
#### Connection Name
+
Name your connection.
#### Endpoint URL
+
This should be a valid REST API endpoint
- - If you are using Jira Cloud, the endpoint will be
`https://<mydomain>.atlassian.net/rest/`
- - If you are self-hosting Jira v8+, the endpoint will look like
`https://jira.<mydomain>.com/rest/`
-The endpoint url should end with `/`.
+
+- If you are using Jira Cloud, the endpoint will be
`https://<mydomain>.atlassian.net/rest/`
+- If you are self-hosting Jira v8+, the endpoint will look like
`https://jira.<mydomain>.com/rest/`
+ 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.
+#### Auth Token
+
+When accessing Jira API using a Jira Auth Token, users may encounter access
restrictions if their token does not have sufficient permissions. This is
typically caused by insufficient scope or role settings for the Jira Auth Token.
+
+To solve this issue, users can take the following steps:
+
+- Checking User Permissions
+
+Users can confirm whether they have sufficient permissions by checking their
permissions in Jira. For cloud users, they can view their global and project
permissions through the "Permissions" tab on the "Profile" page. For server
users, they can log in to Jira as an administrator and view user permissions on
the "User Management" page.
+
+- Ensuring Sufficient Permissions
+
+Before using Jira API, users need to ensure that their account has at least
the necessary project or global permissions. Global permissions include various
Jira system settings and management operations, while project permissions
control specific operations and configurations for each Jira project. Users can
assign roles such as Project Administrator, Project Lead, Developer, etc. for
the corresponding projects, or assign global permissions such as Jira
Administrators, Jira Software Admi [...]
+
+- Solving Access Restrictions
+
+To solve access restrictions caused by insufficient Jira Auth Token
permissions, users should check the token's permission settings to ensure the
correct scope and role are set. If the permission settings are correct but the
required API is still inaccessible, consider using other authentication
methods, such as authenticating with a username and password. If the issue
persists, contact the Jira administrator for further assistance.
+
#### 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)
@@ -34,25 +59,29 @@ DevLake uses a dynamic rate limit to collect Jira data. You
can adjust the rate
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.
+Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
### Step 2 - Setting Data Scope
+
#### Projects
+
Choose the Jira boards to collect.
#### Data Entities
+
Usually, you don't have to modify this part. However, if you don't want to
collect certain Jira entities, you can unselect some entities to accerlerate
the collection speed.
+
- Issue Tracking: Jira issues, issue comments, issue labels, etc.
- Cross Domain: Jira accounts, etc.
### Step 3 - Adding Transformation Rules (Optional)
+
-
+
Without adding transformation rules, you can not view all charts in "Jira" or
"Engineering Throughput and Cycle Time" dashboards.<br/>
Each Jira board has at most ONE set of transformation rules.
@@ -68,11 +97,12 @@ Each Jira board has at most ONE set of transformation rules.
- Story Point: choose the custom field that represents story points. In most
cases, it is "Story Points".
#### Additional Settings
+
- Remotelink Commit SHA: parse the commits from an issue's remote links by the
given regular expression so that the relationship between `issues` and
`commits` can be created. You can directly use the regular expression
`/commit/([0-9a-f]{40})$`.
### Step 4 - Setting Sync Frequency
-You can choose how often you would like to sync your data in this step by
selecting a sync frequency option or enter a cron code to specify your prefered
schedule.
+You can choose how often you would like to sync your data in this step by
selecting a sync frequency option or enter a cron code to specify your prefered
schedule.
## Troubleshooting
