Jira Integration

Overview

Span integrates with Jira to sync issue, sprint, project, and workflow data, powering engineering metrics including cycle time, sprint health, DORA metrics, and work allocation analysis. Both Jira Cloud and Jira Server / Data Center are supported.

Span automatically detects your Jira type: domains ending in .atlassian.net are treated as Jira Cloud; all other domains are treated as Jira Server / Data Center.

Before You Begin

You will need: 

• Admin access to Span (or the Integrations Admin role)

• A Jira user account with read access to all projects you want Span to analyze

• A Jira API token (not your Jira password)

• Your Jira domain (e.g. yourcompany.atlassian.net or jira.yourcompany.com)

Setup

Step 1 — Generate a Jira API Token

1. Go to Atlassian Account Settings → Security → API Tokens

2. Click Create API token, give it a descriptive label (e.g. Span Integration), and copy the token value

3. Save it somewhere safe — Atlassian will not show it again

Your Jira password cannot be used in place of an API token.

Step 2 — Connect Jira to Span

1. In Span, go to Settings → Tools & Integrations

2. Select Jira

3. Enter your credentials:

4. Click Validate & Continue. Span verifies the connection before proceeding.

If validation fails, you'll see one of the following messages:

Step 3 — Configure Custom Fields

After validation, Span fetches your Jira instance's field definitions and auto-detects common fields. You'll configure three areas: 

Story Points

Span auto-detects and enables these standard fields when present:

• Story Points — used by Next Gen / Team-managed projects

• Story point estimate — used by Classic / Company-managed projects

If detected, they appear pre-selected and cannot be deselected. If your team uses a custom field for story points, you can select one additional custom field from a dropdown. If no story point fields are found, you can continue without configuring them.

Pull Request Linking

Choose how Span links pull requests to Jira issues:

Issue Categorization

Select up to 10 custom fields for categorizing issues. These fields power DORA metrics, investment mix analysis, and work type classification. Search by field name or field ID.

Auto-Detected System Fields

If Span finds your Sprint or Epic fields, they are automatically included in the summary. Note: Epic field auto-detection is available on Jira Data Center only — on Jira Cloud, configure it manually as a custom field if needed.

4. Click Create Integration to complete setup.

What Data Span Syncs

No webhooks need to be configured on the Jira side. Span pulls data on a scheduled basis: 

Only the custom fields you configured during setup are synced.

Historical data: New organizations sync 6 months of historical data by default, unless configured otherwise in your organization settings.

Metrics & Features Powered by Jira

With the Jira integration active, Span enables:

• Issue lifecycle metrics — cycle time, lead time, time in status

• Sprint metrics — planning accuracy, estimation accuracy, burndown analysis

• Issue completion — issues completed per week, broken down by type (Story, Bug, Task, Sub-task)

• DORA metrics — change failure rate and deployment frequency (correlated with Jira work items)

• Work allocation — investment mix and capacity analysis via custom field categories

• PR traceability — pull requests linked to the Jira issues they address

• Team capacity — FTE days and cost allocation based on issue assignment

Jira Cloud vs. Server / Data Center

Security & Permissions

• Authentication method: Email + API token (no OAuth flow required)

• Required Jira permissions: Read access to all projects you want analyzed

• API token storage: Tokens are encrypted at rest — never stored as plain text

• Span role required: Admin or Integrations Admin

Troubleshooting