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.

Registration​

Discovery​

By default, Cortex will tie JIRA tickets by looking for any tickets where the label, component, or project field on the Issue includes the Cortex Entity Tag (e.g. my-service). For example, if your Entity Tag 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 Entity Tag, you can override this in the Cortex Catalog Descriptor.

Catalog Descriptor​

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

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

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

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

By default, Cortex will surface outstanding issues per entity in the catalog with a default JQL query: status = "Open" OR status = "To Do". If you'd like to override this, you can provide a new default query with:

x-cortex-issues:
  jira:
    defaultJql: 'status = "In Progress"'

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 Entity Tag.
  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.