Skip to main content




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

  • Customer facing incidents
  • Security tickets
  • Ongoing projects


Jira Cloud

When using Jira Cloud (hosted on or, 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 along with access to the needed Jira projects.

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

Multi-account support

The Jira integration has multi-account support so you can add a configuration for each additional instance by repeating the above process.

Each configuration requires an alias, which Cortex uses to correlate the designated instance with registrations for various entities. Registrations can also use a default configuration without a listed alias.

You can edit aliases and default configurations from the Jira page in Settings. Select the edit icon next to a given configuration and toggle "Set as default" on. If you only have one configuration, it will automatically be set as the default.


If you do not see the Settings page you're looking for, 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 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 and /oauth/internal/jira for default configuration or the url of your Cortex instance and /oauth/internal/jira/{accountAlias} for the non-default configuration
  • 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.



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 entity descriptor.

Entity descriptor

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

Alias is optional and default Jira configuration will be used if not provided:

- name: labelA
alias: alias1
- name: labelB

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

Alias is optional and default Jira configuration will be used if not provided:

- name: component1
alias: alias1
- name: project1
alias: alias1

By default, Cortex will surface outstanding issues per entity in the catalog with a default JQL query: statusCategory in ("To Do", "In Progress"). If you'd like to override this, you can provide a new default query with:

defaultJql: 'status = "In Progress"'


  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.