Skip to main content

Jira Integration Setup

Complete guide to connecting Distil with your Jira workspace.

What You'll Need​

Before starting:

  • Jira Cloud account (Jira Server/Data Center not supported)
  • Admin role in your Distil workspace
  • Project Admin or higher in your Jira workspace
  • 15 minutes

Supported Jira Products​

Distil works with:

  • Jira Software (Cloud)
  • Jira Work Management (Cloud)

Not supported:

  • Jira Server (self-hosted)
  • Jira Data Center
  • Jira Service Management (JSM)

Step 1: Connect Jira​

  1. Log in to Distil
  2. Go to Settings → Integrations
  3. Find the Jira card
  4. Click "Connect Jira"
  5. Sign in with your Atlassian account
  6. Click "Accept" to authorize Distil

You'll be redirected back to Distil with a success message.

Step 2: Configure Default Project​

After connecting, you need to choose which Jira project cards should push to.

  1. In the Jira integration settings, click "Configure Project"
  2. Select a project from the dropdown (e.g., "PROD - Product Backlog")
  3. Select a default issue type (e.g., "Task")
  4. Click "Save"

Tip: Choose a project where you manage product backlog items, not where you track bugs or support tickets.

Step 3: Test the Integration​

Create a test card and push it to Jira:

  1. Go to your Distil dashboard
  2. Create a new card: "Test Jira Integration"
  3. Accept the card with rationale: "Testing Jira integration"
  4. Click "Push to Jira" at the bottom of the card
  5. Confirm the push

Then check Jira:

  • Open your configured Jira project
  • Find the new issue (it should appear within seconds)
  • Verify the description includes a link back to Distil

If this works, you're all set!

Step 4: Configure Team Workflow (Optional)​

Decide how your team will use the integration:

Option 1: PM-Only Pushing​

Only product managers push to Jira. Engineers never touch Distil.

Pros: Simple, clear ownership Cons: PM becomes a bottleneck

Setup: Only give PM users access to Distil

Option 2: Shared Pushing​

PMs and tech leads both have access. Either can push cards when ready.

Pros: Flexible, no bottlenecks Cons: Requires coordination

Setup: Invite tech leads as Members in Distil

Option 3: Bulk Sprint Planning​

PM accumulates accepted cards, then bulk-pushes before each sprint.

Pros: Efficient, batched workflow Cons: Cards don't flow to Jira until sprint planning

Setup: Use the bulk push feature from Roadmap view

Advanced Configuration​

Multiple Projects​

By default, all cards push to your configured project. But you can override this per-push.

When you'd want this:

  • You have separate Jira projects for frontend and backend
  • You want to route cards based on tags or themes

How to do it:

  1. When pushing, click "Advanced Options"
  2. Select a different project
  3. Choose issue type for that project
  4. Push

Issue Type Mapping​

Distil suggests issue types based on card content:

  • Bug: If the title/description mentions "bug," "error," "broken," etc.
  • Story: If the title/description mentions "user," "customer," "feature," etc.
  • Task: Default for everything else

You can override this on every push.

Permissions​

The Distil integration needs these Jira permissions:

  • View projects (to list available projects)
  • Create issues (to push cards)
  • Edit issues (to update descriptions with backlinks)

If you get permission errors, check with your Jira admin that your account has these permissions.

What Happens When You Push​

When you push a card to Jira, Distil:

  1. Creates a new Jira issue
  2. Copies the card title to the issue summary
  3. Formats the card description as Jira Description (with acceptance rationale if Governance Pack enabled)
  4. Adds a "View in Distil" link to the issue
  5. Converts Distil tags to Jira labels
  6. Saves the Jira issue link on the Distil card
  7. Changes the card status to "Ready"

The card remains in Distil as a historical record.

Monitoring Integration Health​

Admins can view diagnostics to ensure the integration stays healthy:

  1. Go to Settings → Diagnostics → Jira Integration
  2. Review metrics:
    • Success rate (should be >95%)
    • Recent failures
    • Error breakdown
    • Performance (p95 latency)

Set up monitoring alerts if:

  • Success rate drops below 90%
  • More than 5 token refresh failures per day
  • Repeated permission errors

Security and Privacy​

OAuth Token Storage​

Distil stores your Jira OAuth tokens securely in encrypted database fields. Tokens are never logged or exposed in client-side code.

Token Refresh​

OAuth tokens expire after 60 minutes. Distil automatically refreshes them as needed. You'll never need to re-authenticate unless you revoke access.

Data Access​

Distil can only:

  • Read project and issue type metadata (to show you options)
  • Create issues in projects you select
  • View issues created by Distil (to show you links)

Distil cannot:

  • Read other Jira issues
  • Modify issues not created by Distil
  • Access Jira user data
  • Delete issues

Revoking Access​

To disconnect Jira:

  1. Go to Settings → Integrations
  2. Click "Disconnect Jira"
  3. Confirm

Your OAuth token will be deleted immediately. Existing Jira issues created by Distil remain unchanged (they're real Jira issues now).

Troubleshooting​

"No projects found"​

Cause: Your Jira account doesn't have access to any projects, or Distil couldn't load them.

Fix:

  1. Log in to Jira and verify you can see projects
  2. Refresh the Distil integration settings page
  3. If still failing, disconnect and reconnect Jira

"Failed to push: Unauthorized"​

Cause: Your Jira token expired or was revoked.

Fix: Go to Settings → Integrations and reconnect Jira.

"Failed to push: Field required"​

Cause: Your Jira project has custom required fields that Distil doesn't populate.

Fix: Either:

  1. Change the Jira project configuration to make those fields optional
  2. Use a different Jira project that doesn't have custom required fields

"Rate limit exceeded"​

Cause: You've made too many pushes in a short time (Atlassian rate limits apply).

Fix: Wait 5-10 minutes and try again. Consider using bulk push instead of individual pushes.

For more troubleshooting, see Troubleshooting Jira Integration.

Best Practices​

Use a dedicated product backlog project: Don't push to your bug tracker or support project. Create a separate "Product Backlog" project in Jira.

Configure issue types that match your workflow: If your team uses "Story" instead of "Task," set that as your default.

Push in batches during planning: Don't push cards the moment you accept them. Batch pushes during sprint planning for efficiency.

Monitor integration health monthly: Check diagnostics once a month to catch issues early.

Document your workflow: Make sure your team knows when and how cards get pushed to Jira.

Next Steps​