Jira Integration

Sync test results directly to Atlassian Jira Cloud. Link failing tests to issues, file new bugs in a single click, and keep Jira issues synced in real-time.

Cloud only: Jira Data Center is not currently supported. Deferred for future phases. See Limitations for details.

Overview

Jira integration enriches your test results with live issue metadata. When you run tests:

1. Link existing issues — attach a Jira issue key (PROJ-123) to a test result defect
2. Enrich automatically — issue status, summary, and link are displayed directly in Sulu
3. File new bugs — click "File bug in Jira" from any failed test result to create a new issue without leaving Sulu
4. Stay synced — Jira updates propagate to Sulu in real-time via webhook (or every 15 minutes if webhook is unavailable)

Example: You're reviewing a failed test result in Sulu. You see it's already linked to QA-456. With Jira integration enabled, the link shows live metadata:

🔗 QA-456 — Login flow regression  [🟡 IN PROGRESS]

Without integration, you'd see:

🔗 QA-456

Configure

Step 1: Enable workspace Jira credentials

1. Go to Workspace Settings (top-right menu → Settings)
2. Click Integrations → Jira
3. Click Enable Jira integration
4. Enter your credentials:
   • Instance URL: https://your-company.atlassian.net (HTTPS required; no path or trailing slash)
   • API Token: Generate one here
     • Best practice: create a service account for Sulu with the minimum required permissions
5. Click Test Connection — Sulu will verify the token and instance are reachable
6. Click Save

On success, you'll receive a webhook secret key. Copy it immediately — you'll need it for the Jira webhook setup (next step).

Step 2: Register Sulu webhook in Jira

1. Log in to Jira Cloud as an instance admin
2. Go to Settings → System → WebHooks
3. Click Create webhook
4. Configure:
   • Name: Sulu Integration
   • URL: https://{your-sulu-domain}/api/webhooks/jira
   • Events: select
     • ✓ jira:issue_created
     • ✓ jira:issue_updated
     • ✓ jira:issue_deleted
   • Headers: Add one custom header
     • Name: X-Sulu-Webhook-Token
     • Value: paste the webhook secret from Step 1
5. Click Create
6. Click Test to verify the webhook works (you should see HTTP 200 in the delivery log)

Troubleshooting: If the test delivery fails, verify:

• Your Sulu instance is publicly reachable (Jira Cloud cannot reach private/localhost URLs)
• The webhook secret matches exactly (copy carefully, watch for trailing spaces)
• No firewall is blocking Jira's outbound requests to your Sulu domain

Step 3: Set project Jira key (per project)

For each project where you want to file bugs:

1. Go to Project Settings → Integrations
2. Enter the Jira project key (e.g., QA, PROJ, INFRA)
3. Click Save

You're done! Test results in this project can now file bugs to that Jira project.

Using File-bug

When viewing a failed test result:

1. Open the test result detail (click on a failed test row)
2. Scroll to Defect links section
3. Click + File bug in Jira
4. A modal appears with:
   • Issue Type — select Issue Type (e.g., Bug, Task, Story; custom types supported)
   • Summary — pre-filled with the test name, edit as needed
   • Description — auto-populated with test name, failed assertion, and error logs
   • Custom fields — any Jira custom fields for this issue type (rendered based on Jira's field schema)
5. Click Create

On success:

• New issue appears in Jira (e.g., QA-789)
• Sulu automatically links the test result to the new issue
• You're returned to the test result with the new link visible

Limits:

• Description is capped at 30 KB (excess is truncated)
• Custom field values must match Jira's validation rules (e.g., date fields must be YYYY-MM-DD format)
• Field types not yet supported (attachments, etc.) show an info banner; you can edit the issue in Jira after creation

Troubleshooting

"Test Connection" fails with 401

Issue: Invalid API token or instance URL.

Fix:

1. Verify the API token is correct: id.atlassian.com → API tokens
   • Copy the token again carefully (trailing spaces will cause 401)
2. Verify the Instance URL matches your Jira domain:
   • Correct: https://acme-corp.atlassian.net
   • Wrong: https://acme-corp.atlassian.net/ (trailing slash)
   • Wrong: https://jira.acme-corp.com (custom domain)
3. Check with your Jira admin that the token's user has permission to access the Jira instance
4. If the token is old, generate a new one and try again

Webhook is not receiving events

Issue: File-bug works, but issue updates in Jira don't show up in Sulu.

Fix:

1. Check the Jira webhook delivery log:
   • Settings → System → WebHooks → Sulu Integration → Delivery tab
   • Look for recent deliveries; check if they show HTTP 200 (success) or an error code
2. If deliveries are failing:
   • Verify the webhook URL is correct (must be HTTPS, publicly reachable)
   • Verify the X-Sulu-Webhook-Token header matches the secret shown in Sulu workspace settings
3. If deliveries show 200 but updates still don't appear in Sulu:
   • Jira may have a rate-limit or backlog (webhook events are eventually delivered within 24 hours)
   • Updates will also be fetched every 15 minutes by the scheduled sync job
   • Check Sulu's application logs (contact your Sulu admin) for any sync errors

File-bug fails with "unsupported issue type"

Issue: The Jira project doesn't have the issue type you selected, or the field configuration is incompatible.

Fix:

1. In Jira, go to Project settings → Issue types and confirm the selected type exists
2. If the issue type exists but Sulu still rejects it, the issue type may be missing required fields that Sulu's schema doesn't support (e.g., complex custom field cascaders)
   • Workaround: create the issue manually in Jira, then link it to the test result in Sulu
3. Contact your Jira admin to verify the issue type is fully configured

File-bug succeeds in Sulu but issue didn't appear in Jira

Rare: Network timeout between Sulu and Jira, or Jira accepted the request but returned an error.

Fix:

1. Check Sulu's application logs (ask your Sulu admin) for the error message
2. Go to your Jira project and search for recent issues matching the title you entered
3. If the issue was created, link it manually to the test result in Sulu (use the issue key)
4. If the issue was not created, the Jira admin can check the instance activity log for API errors

Limitations

Current

• Atlassian Cloud only — Data Center, Server, and Self-Hosted instances are not currently supported
• One-to-one project mapping — each Sulu project maps to exactly one Jira project
• No comment sync — Jira issue comments do not sync back to Sulu (deferred for future phases)
• Read-only issue metadata — only the issue key, summary, and status are displayed; editing Jira issues must be done in Jira itself

Deferred (Future Phases)

• Multi-workspace Jira instance (Cloud organization-level setup)
• Jira Data Center + Self-Hosted support
• Custom field sync (both directions)
• Issue comment and attachment sync
• Advanced field mapping (e.g., test result author → Jira issue reporter)
• Bidirectional status sync (close issue when test passes)
• Test case versioning integration (link test version to issue)

---

Need help? Contact your workspace owner. For admin procedures like token rotation and webhook troubleshooting, see the operations runbook (available in your Sulu deployment at /docs/operations/jira-integration-runbook.md).