Start free trial
Sign in Start free trial

Jira key results

Note

Jira Key Results are available on Enterprise and custom plans and require an active Atlassian OAuth connection with Jira scope granted.

A Jira Key Result pulls its value from a JQL filter — the number of matching issues, their total story points, or the sum of a custom numeric field. The metric is refreshed on the same scheduled sweep as computed key results, and can be synced on-demand from the KR detail view.

Prerequisites

Jira Key Results need the Dependra for Jira app connected to your Atlassian site. It is a separate app from Dependra for Confluence — installing one does not connect the other — but both attach to the same Dependra organisation and can share a single connection code.

  1. Follow the Connect Atlassian guide: install Dependra for Jira from the Atlassian Marketplace, generate a connection code in Settings → Atlassian Integration, and paste it into the app’s configuration page in Jira.
  2. Wait for the status to move from Pending to Connected. Atlassian issues the app’s access token on a scheduled trigger, so this can take up to an hour on a fresh connection.

The app requests all the read permissions a Jira-driven metric needs — there are no scopes to pick, and the app never writes to Jira. If you are still on the deprecated OAuth 2.0 connection, the required scopes are listed at the bottom of the Connect Atlassian guide.

Warning

Missing Jira scopes are surfaced as a sync error on the KR. If you see “Insufficient scope” in the KR’s error field, reconnect the Atlassian OAuth with the correct scopes.

Warning

Your JQL must be bounded. Atlassian rejects unrestricted queries on the search endpoints with Unbounded JQL queries are not allowed here. Always include a restriction such as project = PLAT — a bare sort like order by created DESC on its own will fail.

Configuring a Jira Key Result

  1. Add a Key Result to your Objective and select Jira as the drive mode.

  2. Enter a JQL filter that defines the issue set to measure. Examples:

    project = "PLAT" AND issuetype = Bug AND status != Done
    project = "MOBILE" AND sprint in openSprints() AND priority = High
    project = "DATA" AND labels = "gdpr-remediation" AND fixVersion = "Q3-2026"

  3. Select a metric mode:

    Mode What is counted
    Issue count The number of issues matching the JQL filter
    Story point sum The total story points of matching issues
    Custom numeric field sum The sum of a named custom numeric field across matching issues

  4. If using custom numeric field sum, enter the field name as it appears in your Jira instance (e.g., customfield_10016 or the display name if your Atlassian instance exposes it).

  5. Set the start value and target value as with any other KR.

  6. Save. The first sync runs within the next sweep cycle (hourly by default).

Pagination

The Jira integration paginates results up to 10,000 issues per sync. If your JQL filter matches more than 10,000 issues, the metric value reflects only the first 10,000 results. Design your JQL to scope issues appropriately — by project, sprint, fix version, or label — to stay within this bound.

Tip

Use updatedDate >= -30d or sprint in openSprints() in your JQL to scope to recent or active work, which is almost always the relevant set for a quarterly KR.

Sync behaviour

Scheduled sweep — The sweep runs hourly by default, identical to the computed metric sweep. Each run executes your JQL against the Atlassian API, paginates results, computes the metric, and records a check-in.

On-demand sync — From the KR detail view, click Sync Now to trigger an immediate fetch outside the sweep schedule. Useful when you know a sprint has just closed or a batch of issues has just been resolved.

Each sync result appears in the KR’s check-in history, timestamped and attributed to the integration. Manual check-ins can coexist with sync-generated ones.

Error surfacing

If a sync fails — due to an expired OAuth token, an invalid JQL expression, insufficient Jira scope, or an Atlassian API error — the error is stored on the KR and displayed in the KR detail view alongside the last successful sync timestamp. Errors do not overwrite the last known value.

Common errors and fixes:

Error Fix
Insufficient scope / scope does not match Reconnect the Atlassian OAuth and grant read:jira-work, read:jql:jira and read:issue-details:jira
JQL parse error Review the JQL filter; test it in Jira’s issue search before saving
Unbounded JQL queries are not allowed here Add a restriction to the filter (e.g. project = PLAT); Atlassian rejects unrestricted queries
Token expired Go to Settings → Atlassian and click Reconnect
Pagination limit reached Narrow your JQL filter to return fewer than 10,000 issues
Field not found Verify the custom field name against your Jira project’s field configuration

When to use Jira Key Results

Jira is the right drive mode when your metric is naturally expressed as work in Jira:

  • Bug backlog reduction (“open P1 bugs in project PLAT below 5”)
  • Delivery throughput (“story points completed this sprint above 40”)
  • Remediation progress (“GDPR-labelled issues resolved above 90%”)
  • Technical debt (“tech-debt labelled tickets below 20”)

For metrics that live in your landscape model (health, incidents, GDPR scope, blast radius), prefer Computed Key Results. For metrics from other external systems, use the API push.