Jira
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
along with access to the needed Jira projects.
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
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 in ("To Do", "In Progress")
. If you'd like to override this, you can provide a new default query with:
x-cortex-issues:
jira:
defaultJql: 'status = "In Progress"'
Troubleshooting
- I've added a Jira integration but I'm not sure what JQL is being generated to query Jira.
- When running Scorecard rules, Cortex appends
AND (component = service-tag OR labels = service-tag OR project = service-tag)
to the JQL you defined, whereservice-tag
is the Entity Tag.
- When running Scorecard rules, Cortex appends
- My Scorecard rules are failing even though there are tickets.
- 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.