Jira Cloud Integration
Overview
MindBacklog's Jira Cloud integration provides bidirectional, real-time synchronization between your product management workflow in MindBacklog and your engineering workflow in Jira. Changes flow both ways — so product and engineering always stay aligned.
Features, User Stories, and Bugs — including their titles, descriptions, statuses, priorities, story points, comments, labels/tags, and due dates. All changes are tracked in the activity log.
Connecting Jira Cloud
Only Admin users can connect Jira. The integration uses OAuth 2.0 — no API tokens required.
Open the Integrations page
Open Integrations in the left sidebar (under "The Mind"), then open the Native Apps tab. You will see the Jira Cloud card.
Click "Connect Jira"
Expand the Jira Cloud card and click the Connect button. You'll be redirected to Atlassian to authorize access.
Authorize & Return
Select the Jira Cloud site to connect and approve access. MindBacklog will redirect you back with the connection established.
If the admin who connected Jira is deactivated from MindBacklog, syncing will continue using the stored OAuth tokens. Another admin can disconnect and reconnect at any time to refresh the credentials.
Project Selection
After connecting, select the Jira project to sync with:
Browse or Enter Project Key
Click Browse Projects to fetch a list from Jira, or type the project key manually (e.g., PROJ).
Save Settings
Click Save Jira Settings. MindBacklog will auto-detect custom fields like Story Points, Epic Link, and Epic Name.
You can change the linked Jira project at any time via the Change button. Existing links to issues in the old project are preserved — items won't be deleted from Jira. New pushes will go to the new project.
Issue Type Mappings
Map MindBacklog work item types to Jira issue types:
| MindBacklog Type | Default Jira Type | Notes |
|---|---|---|
| Feature | Epic | Pushed as Epics; child items linked via Epic Link |
| User Story | Story | Linked to the parent Feature's Epic |
| Bug | Bug | Linked to the parent Feature's Epic |
You can change these via the Issue Types accordion in the Mappings section. Only standard (non-subtask) Jira issue types are available.
Status Mappings
Map each MindBacklog status to its Jira equivalent. Separate mappings are available for:
| Category | MindBacklog Statuses |
|---|---|
| Feature Statuses | Intelligence Hub: New, Closed, Archive · Roadmap: Under Consideration, Planned, Scheduled, In Progress, Completed, Archived |
| Story & Bug Statuses | Draft, Ready, In Progress, Ready for QA, In QA, Waiting Acceptance, Done |
Status changes sync both ways — updating a status in Jira will update it in MindBacklog (and vice versa), using the mapping you've configured.
Field Mappings (Description Sections)
MindBacklog has multiple content fields per item (e.g., Summary, Problem Statement, Business Value), while Jira uses a single Description field. The Field Mapping section controls how these are combined and split.
MindBacklog → Jira
Selected fields are combined into the Jira Description as ADF sections with headings. For example, a Feature's description in Jira will contain ## Summary, ## Problem Statement, and ## Business Value sections.
Jira → MindBacklog
When syncing back, MindBacklog parses the ADF headings and routes each section to the correct field. Content that doesn't match any known heading goes to the Fallback Field (defaults to Summary).
Each work item type has a configurable Fallback Field. If someone edits the Jira description and removes or renames a section heading, the unrecognized content will be placed in this field rather than lost.
Sync Preferences
| Setting | Description |
|---|---|
| Two-Way Sync | Enable/disable automatic bidirectional syncing. When on, changes push and pull automatically. |
| Auto-Push Children | When pushing a Feature to Jira, automatically push its User Stories and Bugs as well. |
| Sync Labels ↔ Tags | Bidirectional sync between Jira labels and MindBacklog tags. |
Pushing to Jira
There are two ways to push items to Jira:
Push from Feature Detail
On any Feature, User Story, or Bug detail page, click the Jira sync button. If the item hasn't been pushed yet, it will create a new Jira issue. If it already has a Jira key, it will update the existing issue.
Automatic Push on Edit
When Two-Way Sync is enabled, editing any synced item in MindBacklog automatically pushes the changes to Jira via a background job.
Pulling from Jira
Click the Pull from Jira button on any linked item to fetch the latest data from Jira. This pulls:
- Title (from Jira's Summary field)
- Description sections (parsed back to individual MB fields)
- Status (mapped via your status mappings)
- Priority
- Story Points
- Due Date
- Labels → Tags
- Comments (from Jira discussions)
Real-Time Webhooks
MindBacklog automatically registers a Jira webhook when you connect. This means changes in Jira are pushed to MindBacklog in real-time — no manual pulling required.
issue_updated — field changes (title, description, status, priority, story points, due date); issue_deleted — unlinks the item; comment_created / comment_updated — syncs discussion comments.
All changes received via webhooks are logged in the Activity tab with per-field old/new values, attributed to the "Jira Bot" system user.
Comment Sync
Comments added in Jira are automatically synced to MindBacklog's Discussion tab. Each synced comment shows:
- The original author's name and email from Jira
- The comment body, converted from Jira's ADF format to readable text
- Posted by the "Jira Bot" system user for attribution
Comments sync both via webhook (real-time) and via Pull from Jira (manual). Duplicates are automatically detected and skipped.
Story Points
Jira Story Points are mapped differently depending on the work item type:
| Work Item Type | MindBacklog Field | Constraint |
|---|---|---|
| Feature | WSJF Job Size | Fibonacci values only (1, 2, 3, 5, 8, 13, 21) — rounds to nearest |
| User Story | Story Points | Any integer value |
| Bug | Story Points | Any integer value |
Disconnecting Jira
Click the Disconnect button in the Jira Cloud connection banner. This will:
- Revoke the OAuth access tokens
- Unregister the webhook from Jira
- Pause all syncing
- Preserve all existing links — Jira issue keys remain on your items. If you reconnect later, the links resume automatically.
Troubleshooting
| Issue | Solution |
|---|---|
| Changes in Jira aren't syncing to MindBacklog | Check that Two-Way Sync is enabled in Sync Preferences. Verify the webhook is registered by toggling sync OFF → ON. |
| Push to Jira fails with "authentication" error | The OAuth token may have expired. Disconnect and reconnect Jira to refresh credentials. |
| Description fields not splitting correctly | Ensure the Jira description uses heading markers (e.g., ## Summary) that match the field labels in your Field Mapping configuration. |
| Story points show wrong value for features | Feature WSJF Job Size only accepts Fibonacci values (1, 2, 3, 5, 8, 13, 21). Non-Fibonacci values are rounded to the nearest allowed value. |
| Comments not appearing | Ensure the webhook is registered. You can manually pull comments via the Pull from Jira button. |
| Status not updating when changed in Jira | Verify that the Jira status name is mapped in your Status Mappings. Unmapped statuses are silently skipped. |