Skip to content
DashboardWebsite

Jira Integration

Just want to do it in the dashboard? See the guide: Send findings to Jira.

Connect a Jira Cloud or Data Center site to create issues for findings. A person can click Create issue, or an organization’s rule can create an issue when a finding reaches a matching status. The sync comments on status changes and moves issues to Done, Won’t do, or Reopen when appropriate.

The sync goes one way. OpenTremor owns the finding’s status, and Jira owns the work: assignee, sprint, priority, and discussion. Changes in Jira do not change a finding.

WhoWhere
1Platform adminTurn Jira on: Platform Admin → Connections → Jira
2Jira adminCreate a service account with permission to create, comment on, and transition issues
3Org adminConnect the site: Organization → Connections → Jira
4Org adminOptional: set a target per product (Products → Jira) or team

In the dashboard, open Platform Admin → Connections → Jira:

  • Offer the Jira integration: turn it on.
  • Allow private network addresses: turn this on if Jira Data Center is on a private company network.
  • Allowed hosts: optional. Add *.atlassian.net to restrict orgs to Jira Cloud.

The same settings are available through the API (jira):

PATCH /v1/admin/settings
{"jira_enabled": true, "jira_egress": {"allowed_hosts": ["*.atlassian.net"]}}

Turning Jira off pauses every organization. OpenTremor sends nothing to Jira and keeps connections, rules, and issue links. When Jira is turned on again, sync resumes from the findings’ current statuses; it does not replay every intermediate status change.

OpenTremor creates issues, adds comments, and transitions issues as this account. It needs Browse projects, Create issues, Add comments, and Transition issues in every target project.

  • Jira Cloud: create an API token for the account. You also need its email address.
  • Jira Data Center: create a personal access token for the account.

In the dashboard, open Organization → Connections → Jira and enter:

  • the site URL, such as https://acme.atlassian.net;
  • the account email for Cloud and the token;
  • a CA certificate in PEM format if Data Center uses a company CA;
  • the default target: project key and issue type (default Bug), plus optional labels and components;
  • optional rules, priorities, and transition names (described below).

Connecting checks the token with Jira and checks that the default project exists. Then use Test to check every target’s project and issue type. The test also lists fields Jira requires on issue creation that OpenTremor does not fill. Jira cannot create issues in a project with a required custom field unless that field is optional or has a default.

TriggerDefaultWhy
Create issue on a findingAvailable when Jira is connectedA person can create an issue for any finding except one that is closed or false_positive. Requires findings:triage.
Rule: finding becomes acknowledged at or above a severityOffA person confirmed it is real, and the pull request did not fix it.
Rule: finding becomes needs_review at or above a severityOffFor teams that run security review from Jira: the issue is the review task.
openNever automaticMost open findings close on the next push.

A rule applies to findings that reach its status after the rule was added. Turning on a rule does not create issues for existing findings. Use Backfill to count matching findings first, then apply the rules to them.

Demo findings never get an issue.

A status change adds a comment with the new status, the reason and note if present, and a link to the finding. When a finding appears in a new pull request, the sync adds a comment for that too.

The finding becomesThe issue
open, needs_review, or acknowledgedComment only. An acknowledged issue stays open because the work is tracked in Jira.
closed (a push no longer reports it)Comment with the revision, then Done
suppressed with reason fixedComment, then Done
suppressed with any other reason or no reasonComment, then Won’t do
false_positiveComment, then Won’t do
A finding returns after one of those statusesComment, then Reopen, but only if OpenTremor closed the issue

OpenTremor does not undo a person’s move in Jira. It closes only an issue that is still open, and reopens only an issue it closed itself. If someone closes the issue in Jira and the finding returns, the sync adds a comment but leaves the issue closed.

Transitions. By default, Done and Won’t do use the first transition into a done status. Reopen uses the first transition into a to do status. If your workflow has a separate Won’t Do transition, name it under Transitions.

An edit that keeps the bug. Findings are tied to the code where they were found. If a push edits that code but the issue remains, the old finding closes and a new one opens. If the new finding has the same rule on the same resource, the issue moves to it and stays open. Its triage status does not move.

In the dashboard, open Analysis → Findings. The Jira column shows each finding’s issue key and Jira status. Use the Jira filter to show findings with or without an issue. A finding whose issue is still being created counts as having no issue.

The API accepts the same filter: GET /v1/findings?has_ticket=true or has_ticket=false. Each finding’s ticket field holds the issue key, link, and status.

OpenTremor chooses the first matching target:

  1. The first product with a target among the products of the repositories where the finding was seen (Products → Jira).
  2. The first team assigned to the finding that has a target (Organization → Connections → Jira → Team targets).
  3. The default target.

OpenTremor chooses the target once, when it creates the issue. A later sighting in another product does not move it.

  • Summary: [SEVERITY] title.
  • Description: the resource, rule, severity, pull requests where the finding appeared, and a link to the finding. With Include the analysis on, the description also includes why the finding matters and the suggested next step.
  • Labels: opentremor, the finding’s own label (opentremor-<12 hex>), and the target’s labels.
  • Priority: the value set under Priority by severity, if any.

Finding text comes from analysed code. OpenTremor sends it as plain text, so Jira does not treat it as markup, mentions, or links.

The task scheduler calls POST /v1/admin/jira/sync every minute. Each call handles up to jira.batch_size findings per organization (default 50).

  • If Jira fails (for example, it is down, the token was revoked, or a required field is missing), the organization’s sync backs off: 1, 2, 4 … up to 60 minutes. Last sync on the integration page shows the error.
  • If an issue was deleted in Jira, the finding keeps its link and shows the error. Unlink the finding to let a rule create another issue.
  • Disconnecting removes every finding’s link. The issues remain in Jira.
  • One Jira site per organization.
  • Jira does not sync changes back to OpenTremor. Triage happens in OpenTremor.
  • The integration uses a service account token; it does not use OAuth or a Forge app.
  • OpenTremor does not fill required custom fields. Test lists them.

Use opentremor_jira_integration, opentremor_jira_product_target, and opentremor_jira_team_target in the Terraform provider. See the API reference at Integrations, Resources & Reports.