Skip to main content
Integrations

Jira Integration

Overview

The Jira integration bridges the gap between retrospective insights and your development backlog. When your team commits action items during a retrospective, Unpack can automatically create corresponding Jira issues in the project and issue type you configure. This eliminates the manual step of transferring action items and ensures nothing is lost between the retro and the next sprint.

The Jira integration is available on the Pro and Enterprise plans. You must be an organization Admin or Owner to connect and configure Jira.

Connecting Jira

Unpack connects to Jira Cloud through Atlassian's OAuth 2.0 flow. On-premise Jira Server installations are not currently supported.

  1. Navigate to Organization Settings → Integrations.
  2. In the Jira card, click Connect to Jira.
  3. You will be redirected to Atlassian's authorization page. Sign in with the Atlassian account that has access to the Jira site you want to connect.
  4. If your Atlassian account has access to multiple Jira sites, select the site you want Unpack to use.
  5. Review the permissions. Unpack requests permission to read projects and issue types, and to create and update issues.
  6. Click Accept to authorize.
  7. You will be redirected back to Unpack. A confirmation banner confirms the connection along with your Jira site URL.

The Atlassian account you use to authorize does not need to be a Jira admin. However, it must have permission to create issues in the target project. We recommend using a service account if your organization's security policy requires it.

Configuring Sync Settings

After connecting Jira, configure how action items are mapped to Jira issues. These settings determine where new issues are created and how they are categorized.

  1. Navigate to Organization Settings → Integrations → Jira.
  2. Under Default Project, select the Jira project where action items should be created. The dropdown lists all projects accessible to the authorized account.
  3. Under Issue Type, choose the issue type for new items. Common choices are "Task" or "Story," but any issue type available in the selected project will appear.
  4. Optionally, enable Per-Team Overrides to configure different project and issue type mappings for individual teams within your organization.
  5. Click Save Settings.

Field Mapping

Unpack maps action item fields to Jira issue fields as follows:

  • Title → Jira issue Summary
  • Description → Jira issue Description (formatted as Atlassian Document Format)
  • Assignee → Jira issue Assignee (matched by email address)
  • Due date → Jira issue Due Date
  • Retrospective link → Appended to the description as a reference URL

Assignee matching relies on email addresses. If a team member's Unpack email does not match their Atlassian account email, the Jira issue will be created without an assignee. You can manually assign it in Jira afterward.

How Sync Works

Action items are synced to Jira when a retrospective enters the Commit phase. Unpack creates one Jira issue per action item. Each synced action item displays a Jira issue key (for example, PROJ-142) that links directly to the issue in your Jira board.

Sync is one-directional by default: changes in Unpack push to Jira. If you update an action item's title or assignee in Unpack, the corresponding Jira issue is updated on the next sync cycle. Changes made directly in Jira are not reflected back in Unpack unless you have webhooks enabled.

Webhook Events from Jira

For two-way status tracking, you can enable Jira webhooks. When enabled, Unpack registers a webhook with your Jira site that listens for issue status changes.

  1. Navigate to Organization Settings → Integrations → Jira.
  2. Under Webhooks, toggle Enable Jira Webhooks on.
  3. Click Save Settings.

When a Jira issue that was created by Unpack transitions to a "Done" category status, the corresponding action item in Unpack is automatically marked as complete. This keeps your retro action items up to date without manual intervention.

Webhooks are delivered in real time. If Jira experiences an outage or the webhook fails, Unpack will process the event on the next successful delivery. Jira retries failed webhooks automatically.

Retry and Manual Sync

Occasionally a sync may fail due to network issues, permission changes, or Jira downtime. Unpack provides tools to handle these situations:

Automatic Retry

When a sync fails, Unpack retries up to three times with exponential backoff. If all retries fail, the action item is marked with a sync error status and appears in the error log.

Manual Retry

  1. Navigate to Organization Settings → Integrations → Jira.
  2. Under Sync Log, locate the failed sync entry. Each entry shows the action item title, the error message, and a timestamp.
  3. Click Retry next to the failed entry to attempt the sync again.

Manual Sync for Individual Action Items

You can also trigger a sync for a specific action item from the retrospective view:

  1. Open the retrospective and navigate to the Action Items panel.
  2. Find the action item you want to sync and click the overflow menu (…).
  3. Select Sync to Jira. The item will be pushed to Jira immediately.

Manual sync is useful when you add action items after the retrospective has already been committed, or when you want to re-sync an item after fixing a configuration issue.

Disconnecting Jira

  1. Navigate to Organization Settings → Integrations → Jira.
  2. Click Disconnect Jira at the bottom of the page.
  3. Confirm the disconnection.

Disconnecting removes the OAuth token and stops all syncing. Jira issues that were already created will remain in your Jira project. The Jira issue keys displayed on action items in Unpack will continue to link to the issues, but no further updates will be synced.

Troubleshooting

  • Sync fails with "permission denied": Verify that the authorized Atlassian account has permission to create issues in the configured project. Project permissions may have changed since the integration was set up.
  • Issue type not available: The selected issue type may have been removed from the project's scheme. Update the issue type in the integration settings.
  • Assignee not matched: Ensure the team member's email in Unpack matches their Atlassian account email exactly.
  • Webhook events not arriving: Check that webhooks are enabled in the integration settings and that your Jira site can reach Unpack's webhook endpoint.