Athenian provides further insights and metrics if your organization uses Jira for its ticketing. To enjoy these, you first must set a few things up from your side.
1. Create a Jira user and group as a service account.
Go to Jira Administration → User management
On the left panel, you will find Users and Groups.
1.1. Create a new user that will be the service account used for Athenian integration. Example: jira-athenian-user.
1.2. Add a new group that will have the user above as a member and will be used to grant a limited permission scope in the next step.
Example: jira-athenian-group.
1.3. Add the user created in 1.1 to the new group added in 1.2.
Note: For security, we recommend that the user should belong only to the new group; you may remove it from the default groups as jira-software-users, etc.
1.4. Go to Applications and grant our group application access to Jira Software.
Note: In case of further doubts on Jira account and group management, you can refer to Jira documentation on user and group management.
2. Grant permission scope to the group for project permission schemas
2.1. Go to Jira Administration → Issues. On the left panel choose Permission schemes
2.2. Choose a permission scheme that corresponds to the projects you want to include in the analysis.
2.3. Grant the Browse Projects permissions to the group created in 1.2
3. [optional] Generate an authentication token for the user.
While it is possible to skip this step and authenticate using a username/password, we do recommend generating a token for the users created in 1.1 as a best practice for extra security.
However, since Jira Server does not yet provide user token generation as a native feature, if you prefer to share an authentication token with us you should either:
Use your token management application if you have one internally.
Search the Atlassian Marketplace for reputable add-ons that provide the API token feature and are compatible with your version of Jira (example).
4. Test the user credentials and permissions granted to the app.
Open a terminal and ensure the 3 following API calls get successful responses.
curl --user ${your_user}:${your_token} \
--request GET \
--url 'https://${your_hostname}/rest/api/2/issue/${your_issue}' \
--header 'Accept: application/json'
curl --user ${your_user}:${your_token} \
--request GET \
--url 'https://${your_hostname}/rest/api/2/user/search?username=.' \
--header 'Accept: application/json'
curl --user ${your_user}:${your_token} \
--request GET \
--url 'https://${your_hostname}/rest/agile/1.0/issue/${your_issue}' \
--header 'Accept: application/json'
If the 3 previous API calls do not return errors, you can proceed with the last step.
Typical error responses often reflect problems with the user credentials authentication (401) or the user permissions granted (403). Double-check the steps from the beginning or ask us for some help.
Note: you can refer to Atlassian documentation on Jira response codes.
5. Provide Athenian with username, token, Jira URL
Once the previous steps are done, you should now provide us with:
the username of the account created eg.
jira-athenian-userthe respective password or authentication token
your Jira hostname eg.
jira.athenian.co
With those 3 elements, we are now able to complete the Jira integration on Athenian's side.
Congratulations! You are on the way to data-driven engineering with GitHub and Jira empowered analytics.