SynthQA

Jira Integration

Connect Jira to create issues from test failures, sync status changes, and automatically queue fix verification re-runs.

GuideIntegrations
Quick Start
Five steps to get the full integration working end to end.
  1. 1Create an Atlassian API token.
  2. 2Connect credentials in SynthQA → Integrations → Jira.
  3. 3Register the SynthQA webhook URL in Jira admin settings.
  4. 4Run a test suite and create Jira issues from the run review page.
  5. 5When a Jira issue is resolved, SynthQA queues the linked test for re-run automatically.
What this integration does

Overview

The Jira integration connects your SynthQA workspace to a Jira Cloud site and enables a closed-loop QA workflow:

  • Create Jira issues directly from failed test executions on the run review page.
  • Receive real-time status updates via webhook when a Jira issue is resolved or closed.
  • Automatically flag the linked test case for fix verification.
  • Surface flagged cases in the Fix Verification panel on your project dashboard.
  • Launch a targeted re-run session with one click and confirm the fix is working.

Prerequisites

  • Jira Cloud site URL — e.g. https://your-domain.atlassian.net
  • Your Jira account email address
  • An Atlassian API token (see next section)
  • Jira project key — e.g. KAN
  • Admin access to Jira to register a webhook

Create a Jira API token

API tokens are used instead of your password. Create one in your Atlassian account settings:

  1. 1Go to id.atlassian.com → Security → API tokens.
  2. 2Click Create API token, give it a label like "SynthQA".
  3. 3Copy the token immediately — it will not be shown again.
  4. 4Paste it into SynthQA when connecting the integration.

Note: This guide assumes Jira Cloud. Jira Server / Data Center uses different authentication.

Connect in SynthQA

  1. 1Navigate to your project → Settings → Integrations → Jira.
  2. 2Enter your Jira site URL, account email, API token, and project key.
  3. 3Enable Auto Sync if you want SynthQA to poll Jira for status changes hourly as a fallback.
  4. 4Click Save. SynthQA will validate the credentials immediately.
Required for real-time sync

Set up the webhook

The webhook allows Jira to notify SynthQA instantly when an issue is resolved or closed, triggering the fix verification flow. Without it, SynthQA falls back to hourly polling.

Your webhook URL

Found in SynthQA → Project Settings → Integrations → Jira → Webhook URL. It looks like:

https://your-app.synthqa.app/api/integrations/jira/webhook?integration_id=YOUR_ID
  1. 1In Jira, go to Admin settings → System → WebHooks.
  2. 2Click Create a WebHook.
  3. 3Paste the SynthQA webhook URL into the URL field.
  4. 4Optionally paste your webhook secret from SynthQA into the Secret field.
  5. 5Under Issue related events, check Issue: updated. The JQL filter can be left as All issues.
  6. 6Click Create. The webhook status should show Enabled.

SynthQA listens for jira:issue_updated events. The webhook fires on every issue update — SynthQA ignores events for issues it is not tracking.

Test the connection

After saving your credentials, use the Test button in the integration settings to verify SynthQA can reach your Jira site and authenticate correctly. A successful test confirms:

  • The site URL is reachable
  • The email and API token are valid
  • The project key exists and is accessible
Step 1 of the loop

Creating issues from failures

After completing a test run, go to the Run Review page. For each failed test case:

  1. 1Check the Issue checkbox next to the failed test case.
  2. 2Optionally add a review note describing what went wrong.
  3. 3Select your Jira integration from the integration dropdown, then click Create Issues.
  4. 4SynthQA creates a Jira bug with the test title, failure reason, and any attached screenshots as evidence.
  5. 5The Jira issue key (e.g. KAN-3) appears on the card and links directly to the Jira issue.
Step 2 of the loop — closing the cycle

Fix verification (re-run)

When a developer marks the Jira issue as Done (or any resolved status), SynthQA detects the change via webhook and automatically queues the linked test case for re-verification.

How it works
1

Jira issue closed

Developer marks the issue Done. Jira fires a webhook to SynthQA within seconds.

2

SynthQA flags the test case

The linked test case is marked needs_rerun and the linked execution is marked pending_rerun.

3

Fix Verification panel appears

On your project dashboard, the Fix Verification panel surfaces all flagged cases with their Jira issue keys.

4

Launch re-run session

Select the cases, pick a suite, and click Start re-run. A new test session is created pre-populated with the flagged cases only.

5

Execute and confirm

Run the cases. Passed → test case returns to active and disappears from the panel. Failed → stays flagged so the cycle continues.

Jira statuses that trigger re-verification

SynthQA maps Jira statuses to internal states using the status category and resolution field:

Done (any resolution)

resolved → queues re-run

Done (Won't Fix / Duplicate)

wont_fix → blocked

In Progress / In Review

in_progress → no action

To Do / Open

open → no action

If the user doesn't execute the re-run

The test case stays flagged in the panel indefinitely — it will not disappear until the case is actually executed and passes. If a re-run session was created but never started, the panel shows a Session pending badge on the case. Clicking it navigates directly to that session so you don't create a duplicate.

Sync behavior

SynthQA uses two complementary mechanisms to stay in sync with Jira:

Webhook (real-time)
Jira pushes status changes to SynthQA within seconds of a transition. Requires the webhook to be registered in Jira admin settings. Recommended.
Polling (fallback)
When Auto Sync is enabled, SynthQA polls Jira hourly for status changes on all tracked issues. Acts as a safety net if the webhook misses an event.

Troubleshooting

Host URL parse error

Ensure your Jira URL starts with https:// and has no trailing slash.

401 / 403 on connection test

Confirm the email and API token are correct. Check that the token has not been revoked in Atlassian account settings.

404 on connection test

Validate the site URL and project key. The project key is case-sensitive.

Webhook fires but test case is not flagged

Check that the Jira issue was created via SynthQA's Create Issues button. Issues created manually in Jira are not tracked.

Fix Verification panel shows nothing after Jira issue is closed

The most common causes are: the webhook URL has the wrong integration_id, or the integration_issues row has no execution_id linked.

Session pending badge not showing

Refresh the panel using the refresh button. The badge appears when a planned or in_progress re-run session already exists for that case.

Security notes

  • Treat API tokens like passwords — rotate them if you suspect exposure.
  • The webhook secret is used to verify that requests to your webhook URL are genuinely from Jira. Set it in both Jira and SynthQA integration settings.
  • SynthQA stores your API token encrypted at rest and never exposes it after saving.
  • The webhook endpoint requires a valid integration_id query param — requests without it are rejected with 400.
Last updated: March 2026 · Guide version: 1.1