doc/solutions/components/jira_dora.md
{{< details >}}
{{< /details >}}
With GitLab, you can get visibility into DORA metrics to help you measure your DevOps performance. The 4 metrics are:
While the first two metrics are generated from GitLab CI/CD and Merge Requests, the latter two depend on GitLab incidents being created.
For teams using Jira for incident tracking, this means that incidents need to be replicated from Jira to GitLab in real-time. This project walks through setting up that replication.
[!note] A similar integration exists for issue replication to generate Value Stream Analytics metrics (Lead Time, Issues Created, and Issues Closed). If you're interested in issue replication for VSA metrics, refer to the Jira to GitLab VSA Integration.
We will need to create 2 automation workflows:
This walkthrough assumes that you have:
Jira places limits on the frequency of Automation runs depending on your Jira license. As of today, the limits are as follows:
| Tier | Limit |
|---|---|
| Free | 100 runs per month |
| Standard | 1700 runs per month |
| Premium | 1000 runs per user per month |
| Enterprise | Unlimited runs |
Each incident creation counts as 1 run, and each incident resolution counts as 1 run.
First we'll need to create an HTTP endpoint that can be triggered to create/resolve alerts in GitLab, which in turn create/resolve incidents.
HTTP Endpoint, give it a name (e.g. Jira incident sync), and set Enable integration to Active. We will come back to customize the alert payload mapping, once we've set up our Jira automation workflows.To automatically trigger the GitLab alert endpoint when a Jira incident is created, we'll use Jira automation.
Navigate to your Jira project where your incidents are managed. From the sidebar, head to Project settings > Automation (you may have to scroll down a bit to find it).
From here we can manage our Jira automation workflows. In the upper right, click Create rule.
For your trigger, search for and select Issue created. Click Save.
Next, select IF: Add a condition. Here you can specify what conditions to check for, in order to determine if the issue created relates to an incident. For this guide, we'll select Issue fields condition. Under Field, we'll select Summary, the Condition will be set to contains, and the value will be incident. Click Save.
With our trigger and condition set, select THEN: Add an action. Search for and select Send web request.
Set the Web request URL to your GitLab Webhook URL from the previous section.
Check the GitLab documentation for endpoint authentication options. For this guide, we'll use the Bearer authorization header method. In your Jira automation configuration, add the following headers:
| Name | Value |
|---|---|
| Authorization | Bearer <GitLab endpoint auth key from the previous section> |
| Content-Type | application/json |
Authorization header to "Hidden".Make sure the HTTP method is set to POST, and set Web request body to Issue data (Jira format).
Finally, click Save, give your automation a name (e.g. Jira incident creation), and click Turn it on. In the upper right, click Return to list.
The last thing you'll need to do is map the Jira payload values to the GitLab alert parameters. If you're planning to also set up incident resolution for the Time to restore service metric, skip this step for now. Otherwise, jump to Map Jira payload values to GitLab alert parameters and follow the steps there.
Once you've mapped the payload values, incidents you create in Jira will also be created in GitLab. This will allow you to see the Change failure rate DORA metric.
Create another Jira automation workflow as described above, with the following changes:
Closed, Done, Resolved, Completed).Jira incident close).Once you've created your Jira automation workflow, click on the workflow you just created, and select Then: Send web request.
Expand the Validate your web request configuration section, and enter a resolved issue key to test with (you must have an existing issue key that you can use). Click Validate.
Expand the Request POST section, and expand the Payload section. Copy the entire payload.
Head back into your GitLab project, and go to Settings > Monitor > Alerts > Current Integrations. Click the 'settings' icon next to the integration you created earlier, and switch to the Configure details tab.
Under Customize alert payload mapping, paste the payload you copied from Jira in step 3. Then click Parse payload fields.
Map the fields as shown below:
| GitLab alert key | Payload alert key |
|---|---|
| Title | issue.fields.summary |
| Description | issue.fields.status.description |
| End time | issue.fields.resolutiondate<sup>1</sup> |
| Monitoring tool | issue.fields.reporter.accountType |
| Severity | issue.fields.priority.name |
| Fingerprint | issue.key |
| Environment | issue.fields.project.name |
<sup>1</sup> This is only needed if you set up the incident resolution automation. If this field doesn't appear as an option, make sure you entered a resolved issue key to test with in step 2 above.
At this point, incidents you resolve in Jira will also be resolved in GitLab. This will allow you to see the Time to restore service DORA metric.