Connecting Jira
A Jira connection is an Atlassian site plus an API token, reused across every board that pulls from it. Deckgauge only ever reads from Jira — there is no write path back.
The Add-source wizard's provider step, Jira selected.
What it does, and where the data comes from
Deckgauge is a read-only Jira client. Creating a connection stores a site URL, an account email, and an API token; every call it makes afterward is a GET — testing the token, listing projects, pulling issues. It never opens, transitions, comments on, or edits a Jira issue.
| Field | Value |
|---|---|
| Instance Name | A label for the connection, e.g. My Jira Cloud |
| Jira Cloud URL | https://your-domain.atlassian.net — must be the real Atlassian host, not a display domain (see below) |
| The account email the API token belongs to | |
| API Token | Created at id.atlassian.com/manage-profile/security/api-tokens; sent as HTTP Basic auth (email + token) |
| Project Keys | e.g. PLAT, WEB — added one at a time, discovered live once the token is valid |
How to connect a Jira instance
- Create an Atlassian API token at
id.atlassian.com/manage-profile/security/api-tokensand copy it. Jira API tokens carry no scopes — Deckgauge sees exactly the projects your account can already see. - Add source → Jira — enter the Instance Name, Jira Cloud URL, Email, and API Token, then Create & test. The test calls Jira's
/rest/api/3/myselfwith your credentials. - Pick the project key(s) from the live-discovered list (Jira's
/rest/api/3/project), or type a key directly. - Review & attach — the project is attached to the board's Sources tab and starts syncing.
What syncs
| Data | Notes |
|---|---|
| Issues | Every issue under the project key(s) you chose, filtered to the issue types you allow on the board's Source zone |
| Transitions | Full status-change history per issue — the input to cycle-time, flow, and timesheet in-progress calculations |
| Sprint fields | Sprint name/state, auto-detected by shape rather than a hardcoded custom-field id (Jira's numeric field id for Sprint varies per site) — feeds Velocity and Iteration Planning Accuracy |
| Due date | The issue's Jira duedate, written onto the board row's Due date field on every sync — until someone edits it by hand, which takes that field out of sync's control (see Manual edits) |
| Worklogs | Optional, off by default — enable it on the connection if you want logged-time data |
Under the hood
Jira Cloud sites answer on two hosts: the canonical *.atlassian.net API host, and — if your organization uses one — an SSO vanity display domain (something like jira.yourcompany.com). The vanity host renders the Jira UI fine, but it silently discards HTTP Basic credentials, so a perfectly valid API token gets a 401 against it.
serverInfo endpoint, compares hosts, and — when they differ — shows a banner with the real host and a Use this URL button that repoints the connection and retests automatically.If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| Test fails with 401, token looks correct | URL points at an SSO vanity/display domain, not the real Atlassian host | Click Use this URL on the banner, or manually switch to *.atlassian.net |
| No Jira issues appear on the board | The issue's type isn't in the board's allowed issue types for this source | Open the board's Source zone and add the type to the chip list |
| Sprint-based widgets are blank | The project doesn't use Jira sprints, or issues haven't synced since sprint data was added | Confirm the project runs sprints in Jira, then re-sync |
| Retired project keeps accruing timesheet hours | Project stopped syncing but its items never reached a terminal status | Mark it in Retired projects with a cutoff date |
Related
- Mapping source statuses — how Jira's
statusvalues map onto board statuses. - When your data refreshes — scheduled sync, manual sync, and retired projects.
- When a connection breaks — reading the health badge and reconnect flow.
- Boards — how synced issues appear alongside manual rows.
Last updated