Skip to main content

JIRA

CatalogScorecards

Summary

Jira is a project management tool. You can use Jira to drive insights into values such as:

  • Customer facing incidents
  • Security tickets
  • Ongoing projects

Setup

JIRA Cloud

When using JIRA Cloud (hosted on atlassian.net or jira.com), you'll need to create a Jira API Token, and add it under Settings → Jira. The email address you add in Settings need to be the same as the user that the Token is associated with.

If you're using a legacy Cloud JIRA instance (your JIRA instance is accessed on jira.com), change the Base URL when adding your Token.

JIRA Self-Hosted

If running a self-hosted JIRA instance, you'll need to use basic auth to connect to JIRA. Add your JIRA host, username, and password under Settings → JIRA by selecting On-Prem in the dropdown.

caution
If you’re using a self-hosted instance of Jira, you’ll need to verify that your Cortex instance is able to reach the Jira instance. See our IP Whitelist section for more.

Issue Tracking

Discovery

By default, Cortex will tie JIRA tickets to the service by looking for any tickets where the label, component, or project field on the Issue includes the Cortex service identifier (e.g. my-service). For example, if your service identifier is “my-service”, then the corresponding tickets in Jira should have “my-service” as a label, component, or project.

If your Jira labels/components/projects don’t cleanly match the Cortex service identifier, you can override this in the Cortex Service Descriptor.

Service Descriptor

If you need to override the automatic discovery, you can define the following block in your Cortex Service Descriptor.

x-cortex-issues:
jira:
labels:
- labelA
- labelB

You can also use Jira Components or Jira Projects to match services.

x-cortex-issues:
jira:
components:
- component1
x-cortex-issues:
jira:
projects:
- project1

Troubleshooting

  1. I've added a JIRA integration but I'm not sure what JQL is being generated to query JIRA.
    1. When running scorecard rules, Cortex appends AND (component = service-tag OR label = service-tag OR project = service-tag) to the JQL you defined, where service-tag is the x-cortex-tag for the service.
  2. My scorecard rules are failing even though there are tickets.
    1. Make sure that the ticket has a label, component, or project that matches exactly with the service tag or the list defined in your Service Descriptor.