jira

README

Jira

Summary

This plugin collects Jira data through Jira Cloud REST API. It then computes and visualizes various engineering metrics from the Jira data.

Project Metrics This Covers

Metric Name	Description
Requirement Count	Number of issues with type "Requirement"
Requirement Lead Time	Lead time of issues with type "Requirement"
Requirement Delivery Rate	Ratio of delivered requirements to all requirements
Requirement Granularity	Number of story points associated with an issue
Bug Count	Number of issues with type "Bug" bugs are found during testing
Bug Age	Lead time of issues with type "Bug" both new and deleted lines count
Bugs Count per 1k Lines of Code	Amount of bugs per 1000 lines of code
Incident Count	Number of issues with type "Incident" incidents are found when running in production
Incident Age	Lead time of issues with type "Incident"
Incident Count per 1k Lines of Code	Amount of incidents per 1000 lines of code

Configuration

In order to fully use this plugin, you will need to set various config variables in the root of this project in the .env file.

Set JIRA_ENDPOINT

This is the setting that is used as the base of all Jira API calls. You can see this in all of your Jira Urls as the start of the Url.

Example:

If you see https://mydomain.atlassian.net/secure/RapidBoard.jspa?rapidView=999&projectKey=XXX, you will need to set JIRA_ENDPOINT=https://mydomain.atlassian.net in your .env file.

Generating API token

1. Once logged into Jira, visit the url https://id.atlassian.com/manage-profile/security/api-tokens
2. Click the Create API Token button, and give it any label name
3. Encode with login email using command echo -n <jira login email>:<jira token> | base64

NOTE: You can see your project's issue statuses here:

Or you can make a cUrl request to see the statuses:

curl --location --request GET 'https://<YOUR_JIRA_ENDPOINT>/rest/api/2/project/<PROJECT_ID>/statuses' \
--header 'Authorization: Basic <BASE64_ENCODED_TOKEN>' \
--header 'Content-Type: application/json'

Set JIRA_BASIC_AUTH_ENCODED

1. Once logged into Jira, visit the url: https://id.atlassian.com/manage-profile/security/api-tokens
2. Click the Create API Token button, and give it any label name
3. Encode with login email using the command echo -n <jira login email>:<jira token> | base64

Set Jira Custom Fields

This applies to JIRA_ISSUE_STORYPOINT_FIELD and JIRA_ISSUE_EPIC_KEY_FIELD

Custom fields can be applied to Jira stories. We use this to set JIRA_ISSUE_EPIC_KEY_FIELD in the .env file.

Example: JIRA_ISSUE_EPIC_KEY_FIELD=customfield_10024

Please follow this guide: How to find Jira the custom field ID in Jira? · merico-dev/lake Wiki

Set Issue Type Mapping

Same as status mapping, different companies might use different issue types to represent their Bug/Incident/Requirement, type mappings allow Devlake to recognize your specific setup with respect to Jira statuses. Devlake supports three different standard issue types:

• Bug
• Incident
• Requirement

For example, say we were using Story to represent our Requirement, what we have to do is setting the following Environment Variables before running Devlake:

Example:

# JIRA_ISSUE_TYPE_MAPPING=<STANDARD_TYPE>:<YOUR_TYPE_1>,<YOUR_TYPE_2>;....
JIRA_ISSUE_TYPE_MAPPING=Requirement:Story;Incident:CustomerComplaint;Bug:QABug;

Type mapping is critical for some metrics, like Requirement Count, make sure to map your custom type correctly.

Set Issue status mapping

Jira is highly customizable, different companies may use different status names to represent whether an issue was resolved or not. One company may name it "Done" and others might name it "Finished".

In order to collect life-cycle information correctly, you'll have to map your specific status to Devlake's standard status, Devlake supports two standard status:

• Resolved: issue was ended successfully
• Rejected: issue was ended by termination or cancellation

For example, say we were using Done and Cancelled to represent the final stages of Story issues. We will have to set the following Environment Variables in the .env file at the root of this project before running Devlake:

#JIRA_ISSUE_<YOUR_TYPE>_STATUS_MAPPING=<STANDARD_STATUS>:<YOUR_STATUS>;...
JIRA_ISSUE_BUG_STATUS_MAPPING=Resolved:Done;Rejected:Cancelled
JIRA_ISSUE_INCIDENT_STATUS_MAPPING=Resolved:Done;Rejected:Cancelled
JIRA_ISSUE_STORY_STATUS_MAPPING=Resolved:Done;Rejected:Cancelled

Status mapping is critical for metrics like Lead Time since the leadtime that we store in the database is calculated only for Resolved issues.

Set JIRA_ISSUE_STORYPOINT_COEFFICIENT

This is a value you can set to something other than the default of 1 if you want to skew the results of story points.

Find Board Id

1. Navigate to the Jira board in the browser
2. in the URL bar, get the board id from the parameter ?rapidView=

Example:

https://<your_jira_endpoint>/secure/RapidBoard.jspa?rapidView=51

Your board id is used in all REST requests to DevLake. You do not need to set this in your .env file.

How do I find the custom field ID in Jira?

Using URL

1. Navigate to Administration >> Issues >> Custom Fields .
2. Click the cog and hover over Configure or Screens option.
3. Observe the URL at the bottom left of the browser window. Example: The id for this custom field is 10006.

How to Trigger Data Collection for This Plugin

Example:

curl -XPOST 'localhost:8080/task' \
-H 'Content-Type: application/json' \
-d '[{
    "plugin": "jira",
    "options": {
        "boardId": 8
    }
}]'