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 needs to be the same as the user that the token is associated with. This user should have the Browse users and groups permissions in Jira.

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

If you do not see the Settings page you're looking for in the sidebar, you likely don't have the proper permissions and need to contact your admin.

Jira Self-Hosted

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.
We route our requests through a static IP address. Reach out to support at help@cortex.io to receive details about our static IP. If you're unable to directly whitelist our static IP, you can route requests through a secondary proxy in your network that has this IP whitelisted, and have that proxy route traffic to your Jira instance.

Basic Authentication

If running a self-hosted Jira instance, you can use basic auth to connect to Jira. Add your Jira host, username, and password under Settings → Jira by selecting On-Prem (Basic Auth) in the dropdown.

OAuth Authentication

If running a self-hosted Jira instance (requires Jira Server version 8.22 or higher) you can also use OAuth to connect to Jira. In order to do so you will need to follow these steps to set up an application link

  • In your Jira server go to the Settings -> Applications -> Application Links -> Create Link
  • For the application type pick "External" and for the direction select "Incoming"
  • For the redirect url, put in the url of your cortex instance + /oauth/internal/jira
  • For the Permission, select "Write" and click save
  • Copy the client ID and client secret for the created link

Once the link is created, add your Jira host, client ID, and client secret under Settings → Jira by selecting On-Prem (OAuth) in the dropdown and filling out the form.

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: statusCategory = "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 labels = 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.