Skip to main content

Pushing to Jira

Once you've accepted feedback and are ready to build, you can push cards directly to Jira from Distil. This guide covers setup, workflow, and troubleshooting.

Prerequisites​

Before you can push to Jira, you need:

  1. A connected Jira workspace (Cloud only - Jira Server not supported)
  2. Admin access to configure the integration
  3. A configured default project and issue type
  4. Cards in "Accepted" status

Initial Setup​

1. Connect Your Jira Account​

  1. Go to Settings → Integrations
  2. Click "Connect Jira"
  3. Sign in with your Atlassian account
  4. Authorize Distil to access your Jira workspace

2. Configure Default Project​

After connecting, you'll need to choose:

Default Project: Which Jira project should cards be pushed to?

  • Example: "PROD" (Product Backlog)

Default Issue Type: What type of issue should be created?

  • Example: "Task" (or "Story" if your team uses Story terminology)

Distil will suggest an issue type based on the card content (Bug vs. Task vs. Story), but you can override this per-push.

3. Test the Connection​

Push a test card to verify everything works:

  1. Create a simple test card and accept it
  2. Click "Push to Jira" on the card
  3. Check your Jira project to confirm the issue was created

Pushing a Card​

Once setup is complete, pushing cards is simple.

Single Card Push​

  1. Open a card in "Accepted" status
  2. Scroll to the bottom
  3. Click "Push to Jira"
  4. (Optional) Override the project or issue type
  5. Click "Confirm"

The card status changes to "Ready" and includes a link to the Jira issue.

Bulk Push​

From the Roadmap view:

  1. Select multiple accepted cards (checkbox on each card)
  2. Click "Push all to Jira" at the top of the Accepted section
  3. Confirm the bulk operation

Distil processes pushes in parallel. You'll see progress for each card (succeeded, failed, or skipped).

What Gets Pushed to Jira​

When you push a card, Distil creates a Jira issue with:

Title: Card title (exact copy)

Description: Formatted description including:

  • Original feedback/problem description
  • Link back to the Distil card
  • Acceptance rationale (if Governance Pack enabled)
  • Accepted by and date (if Governance Pack enabled)

Labels: Distil tags are converted to Jira labels

Project: Your configured default (or override)

Issue Type: Your configured default (or auto-suggested)

Every Jira issue created from Distil includes a "View in Distil" link at the bottom.

Why this matters: Engineers working in Jira can jump back to Distil to see:

  • Original customer feedback
  • Signal notes showing patterns
  • Acceptance rationale explaining why this was prioritized

This context helps engineers understand the "why" behind their work.

After Pushing​

Once pushed:

  • Card status changes to "Ready" in Distil
  • Jira link is saved on the Distil card
  • The card stays in Distil as a record

You manage the work in Jira from this point forward. The Distil card becomes a historical record of the decision.

Project Overrides (Advanced)​

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

Use case: You have multiple Jira projects (e.g., "BACKEND" and "FRONTEND") and want to route cards appropriately.

How to override:

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

The override applies only to that specific push - it doesn't change your default.

Governance Pack Features​

If you have the Governance Pack enabled, pushed Jira issues include additional context:

Acceptance rationale: Why this was prioritized Accepted by: Which PM accepted this card Accepted date: When it was accepted

This creates traceability from customer feedback → roadmap decision → engineering work.

Learn more about Governance Pack

Troubleshooting​

See Troubleshooting Jira Integration for common issues and solutions.

Quick fixes:​

"Not connected": Go to Settings → Integrations and reconnect Jira

"No project configured": Go to Settings → Integrations and select a default project

"Card must be accepted first": Only accepted cards can be pushed. Accept the card first.

"Already pushed": This card was already pushed. Check the Jira link on the card.

"Permission denied": Your Jira account needs permission to create issues in the selected project.

Best Practices​

Push When You're Ready to Assign​

Don't push cards until you're ready for them to enter your development backlog. Accepted cards can sit in Distil for weeks while you plan - that's normal.

Push in Batches​

Review your Accepted section weekly or bi-weekly. Push a batch of cards that are ready for development.

Use Bulk Push for Sprint Planning​

During sprint planning, select all cards ready for the upcoming sprint and bulk push them to Jira at once.

Keep Acceptance Rationale Clear​

Engineers will see this context in Jira. Make sure your rationale explains why this matters, not just what it is.

Don't Delete Jira Issues After Pushing​

If you delete a Jira issue, the Distil card still thinks it's pushed. Instead, close or resolve the Jira issue.

Integration Health Monitoring​

Admins can view integration health metrics:

Go to Settings → Diagnostics → Jira Integration

You'll see:

  • Success rate for pushes
  • Error breakdown
  • Performance metrics (latency)
  • Recent failures

Use this to catch configuration issues or permission problems early.

Next Steps​