Jira Integration

Last updated: October 27, 2026

Span's Jira integration syncs issues, issue history, sprints, boards, projects, workflows and pull request links from Jira Cloud or Jira Data Center. Span only reads from Jira and never writes to it.

Why it matters

Jira data powers issue cycle time, sprint metrics, DORA metrics, work allocation, cost capitalization and pull request traceability in Span.

  • Issue lifecycle metrics: cycle time, lead time and time in status.

  • Sprint metrics: planning accuracy, estimation accuracy and burndown.

  • Issue completion: issues completed per week, 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 from your categorization fields.

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

  • Team capacity: FTE-days and cost allocation based on issue assignment.

How it works

Span pulls data from Jira on a schedule. You don't need to set up webhooks in Jira.

Cloud or Data Center. Span decides from the domain you enter. Domains ending in .atlassian.net, .jira.com or .atlassian-us-gov-mod.com are treated as Jira Cloud. Any other domain is treated as Jira Data Center. If you use a custom domain for Jira Cloud, contact support so Span treats it as Cloud.

Connection types.

Connection type

Works with

What you enter

API token (default)

Jira Cloud and Jira Data Center

Domain, Email and API Token. On Jira Cloud, the API Token is an Atlassian API token without scopes. On Jira Data Center, enter a personal access token in the API Token field.

OAuth 2.0 (service account)

Jira Cloud only

The service account's Client ID and Client Secret, then the Jira site to connect. To sync pull request links, also enter an Email and API Token (see below).

Guardette (configured with OAuth 2.0 service account credentials)

Jira Cloud only

Connects through Guardette, a redacting proxy you deploy in your own infrastructure that holds the service account's OAuth 2.0 credentials. Span turns this option on for your organization on request.

Pull request links need an email and API token. Span reads issue-to-pull-request links from Jira's development-status API, which doesn't accept OAuth tokens. With the OAuth 2.0 connection type, the Email and API Token fields are optional: fill in both to sync pull request links, or leave both blank to connect without them.

What Span syncs.

Data

Sync method

Availability

Issues

Incremental

Cloud and Data Center

Issue change history

Incremental

Cloud and Data Center (on Data Center, history syncs with each issue)

Pull request links

Incremental

Cloud and Data Center

Sprints

Full refresh

Cloud and Data Center

Projects and project versions

Full refresh

Cloud and Data Center

Boards

Full refresh

Cloud and Data Center

Users

Full refresh

Cloud and Data Center

Workflow statuses

Full refresh

Cloud and Data Center

On Jira Cloud, Span syncs only the custom fields you configure. New organizations sync 6 months of history by default, unless your organization settings say otherwise.

Setup

Before you begin, you need:

  • The Admin or Integrations Admin role in Span.

  • A Jira user with read access to every project you want Span to analyze. A regular user with broader permissions is fine: Span only calls read endpoints, so write permissions go unused. You don't need a dedicated read-only user.

  • Your Jira domain, for example yourcompany.atlassian.net or jira.yourcompany.com.

  • A credential for your connection type: an API token (Jira Cloud), a personal access token (Jira Data Center), or OAuth 2.0 service account credentials (Jira Cloud). Your Jira password doesn't work.

Step 1: Create a token (API token connection type).

  • Jira Cloud: go to Atlassian Account Settings → Security → API tokens. Click Create API token, not Create API token with scopes. Give it a label such as Span Integration and copy the value. Atlassian won't show it again.

  • Jira Data Center: create a personal access token for the Jira user in your Jira profile and copy the value.

Why a token without scopes (Jira Cloud). With the API token connection type, Span calls your Jira site's own domain with your email and token. Atlassian's scoped tokens are meant for Atlassian's API gateway, and on a site domain they can fail to authenticate or return incomplete data, including missing pull request links. Because Span only reads, a token without scopes from a regular user is safe to use.

Step 2: Connect Jira to Span.

  1. In Span, go to Settings → Integrations and select Jira.

  2. Click Connect and choose a Connection type.

  3. Fill in the fields for that type and click Continue. Span checks the connection before it saves it.

Field (API token)

What to enter

Domain

Your domain without https://, for example yourcompany.atlassian.net. For Data Center, use your instance host.

Email

The email address of the Jira user

API Token

The API token (Cloud) or personal access token (Data Center) from Step 1

For OAuth 2.0, the service account's app must grant these scopes, and Span checks them when you connect: read:jira-work, read:jira-user, read:board-scope:jira-software, read:project:jira and read:sprint:jira-software.

If the check fails, you'll see one of these messages:

Error

Likely cause

"Failed to authenticate. Please check your api token."

Wrong email or token, or the token was revoked

"Please verify your Jira domain."

The domain is wrong or unreachable

"Authentication failed. Please check your credentials and domain."

General credential or domain mismatch

"Connection failed. Please check your network connection and try again."

Span couldn't reach your Jira instance

Step 3: Configure custom fields. After you connect, Span reads your Jira field definitions and detects common fields. The Jira card shows Awaiting Configuration until you save this step.

  • Story Points: Span detects and turns on two standard fields when present: Story Points (shown as Next Generation story points) and Story point estimate (shown as Classic story points). Detected fields stay selected. You can add one custom story points field from a dropdown. If Span finds no story point fields, you can continue without them.

  • Pull Request Linking: choose how Span links pull requests to issues (see the table below).

  • Issue categorization: select up to 10 custom fields. These fields drive DORA metrics, investment mix and work type classification. Search by field name or ID.

  • Auto-detected system fields: Span includes your Sprint field, and on Jira Data Center your Epic Link field, when it finds them.

Pull request linking method

Notes

Jira's Native Method: Development (default)

Uses Jira's built-in Development field. If Span doesn't detect the field, pick it from the dropdown.

Remote Links

Uses Jira's remote links. Contact support to turn it on.

GitKraken Integration

For Jira Data Center instances that use GitKraken. Contact support to turn it on.

Click Save to finish.

Things to know

  • Jira Cloud and Data Center sync the same data: both include issue change history.

  • OAuth 2.0 and Guardette are Cloud-only: Jira Data Center connects with a personal access token.

  • OAuth without an email and API token means no pull request links: issues, sprints and the rest still sync.

  • Epic field detection is Data Center only: on Jira Cloud, add your epic field as a categorization field if you need it.

  • Data Center must be reachable: Span's hosted service connects to your Jira Data Center instance, so your network has to allow it.

  • Token storage: Span encrypts tokens at rest.

  • Worked example: your team connects Jira Cloud with OAuth 2.0 and leaves Email and API Token blank. Issues, history, sprints and boards sync, but Span gets no pull request links from Jira, so no issue shows a linked pull request. Reconnect and enter an Email and an API token without scopes, and Span syncs pull request links on its next run.

Jira Cloud REST endpoints Span calls (API token connection type):

/rest/auth/1/session
/rest/api/3/myself
/rest/api/3/users/search
/rest/api/3/project/search
/rest/agile/1.0/board
/rest/agile/1.0/board/BOARD_ID/sprint
/rest/api/3/field
/rest/api/3/status
/rest/api/3/search/jql
/rest/api/3/issue/ISSUE_KEY
/rest/api/3/issue/ISSUE_ID/changelog
/rest/dev-status/1.0/issue/detail

Troubleshooting

Symptom

Resolution

Development field not detected

Pick the field from the Development Field dropdown during setup.

Issues sync, but no pull requests are linked

On the API token connection type, confirm the token was created without scopes. On OAuth 2.0, confirm you entered an Email and API Token. Then confirm the Development field is filled in on your issues. For Remote Links or GitKraken, contact support.

Story point fields not detected

Span matches the exact field names. Pick your field from the custom story points dropdown.

The integration stops syncing

Your token may have been rotated or revoked. Create a new one and reconnect in Settings → Integrations → Jira.

Epic field not detected (Jira Cloud)

Detection is Data Center only. Add the epic field as a categorization field.

OAuth 2.0 connection reports missing scopes

Grant the five scopes listed in Step 2 to the service account's app, then connect again.

Related articles

How to create an Integrations Admin in Span

Troubleshooting integration connection status

Network Access Requirements

PR Link Rate Report

Need help?

Contact your Span account team or reach out to support@span.app.