Skip to content
TruthVouch Docs

Jira Integration

Automatically create and track Jira issues for AI governance alerts. TruthVouch can sync hallucinations, policy violations, and verification failures as actionable Jira tickets with automatic status updates.

Setup

1. Generate Jira API Token

In Jira Cloud:

  1. Go to account.atlassian.com → Security
  2. Create API token
  3. Copy token (store securely)

For Jira Server/Data Center:

  • Use username and password or personal access token

2. Configure TruthVouch

Configure via the TruthVouch web dashboard or REST API:

For Jira Cloud:

Terminal window
curl -X POST https://api.truthvouch.com/api/v1/integrations/jira \
  -H "Authorization: Bearer tv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cloud",
    "cloud_url": "https://your-domain.atlassian.net",
    "email": "[email protected]",
    "api_token": "your-api-token",
    "project_key": "OPS"
  }'

For Jira Server/Data Center:

Terminal window
curl -X POST https://api.truthvouch.com/api/v1/integrations/jira \
  -H "Authorization: Bearer tv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "server",
    "server_url": "https://jira.company.com",
    "username": "admin",
    "password": "your-password",
    "project_key": "OPS"
  }'

Auto-Create Issues

Basic Alert to Ticket

Create issues via REST API:

Terminal window
curl -X POST https://api.truthvouch.com/api/v1/integrations/jira/issues \
  -H "Authorization: Bearer tv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "project_key": "OPS",
    "issue_type": "Bug",
    "summary": "Hallucination Detected",
    "description": "Query: Is the Earth flat?\nConfidence: 5%",
    "priority": "High"
  }'

SDK integration coming Q2 2026. See SDKs Overview for details.

Custom Issue Mapping

# Map alert fields to Jira fields
issue = handler.create_issue(
    project_key="OPS",
    issue_type="Task",
    fields={
        "summary": "Verify: Earth is flat claim",
        "description": "Hallucination detected with 5% confidence",
        "priority": "High",
        "labels": ["hallucination", "science"],
        "assignee": {"emailAddress": "[email protected]"},
        "components": [{"name": "AI-Firewall"}],
        "customfield_10000": "critical"  # Custom field
    }
)

Bi-Directional Sync

Sync Alert to Ticket

from truthvouch.client import TruthVouchClient


# Initialize TruthVouch client for Jira integration
tv_client = TruthVouchClient(api_key="your-api-key")


# Configure Jira integration via the TruthVouch dashboard
# or use the REST API to set up the integration endpoint

Sync Ticket Update to TruthVouch

@app.route("/jira/webhook", methods=["POST"])
def handle_jira_event():
    """Handle Jira webhook events."""


    event = request.get_json()


    # When ticket status changes
    if event["webhookEvent"] == "jira:issue_updated":
        issue = event["issue"]


        # Update TruthVouch alert status
        if issue["fields"]["status"]["name"] == "Done":
            tv_client.alerts.acknowledge(
                alert_id=issue["key"],
                status="resolved"
            )


        elif issue["fields"]["status"]["name"] == "In Progress":
            tv_client.alerts.acknowledge(
                alert_id=issue["key"],
                status="in_progress"
            )


    return {"status": "ok"}, 200

Automated Rules

Create Issues for Specific Alerts

# Create a Jira issue for every critical hallucination
handler.configure_rule(
    name="Critical Hallucinations → Jira",
    trigger="confidence < 0.5",
    action={
        "type": "create_jira_issue",
        "project_key": "OPS",
        "issue_type": "Bug",
        "priority": "Highest",
        "assignee": "on-call-rotation",
        "template": "hallucination_bug"
    }
)


# Create Jira for policy violations with auto-assign
handler.configure_rule(
    name="Policy Violation → Jira",
    trigger="policy_violation = true",
    action={
        "type": "create_jira_issue",
        "project_key": "COMPLIANCE",
        "issue_type": "Task",
        "priority": "High",
        "assignee": "compliance-team",
        "due_date": "+2d"  # Due in 2 days
    }
)

Issue Templates

Configure issue templates via the TruthVouch platform to automate Jira issue creation with consistent fields. Define mappings for alert fields to Jira ticket fields, including summary, description, priority, and labels.

Querying and Reporting

# Find all open hallucination issues
issues = handler.search(
    jql='project = OPS AND type = Bug AND labels = hallucination AND status != Done'
)


print(f"Open hallucination issues: {len(issues)}")


for issue in issues:
    print(f"- {issue.key}: {issue.fields.summary}")
    print(f"  Created: {issue.fields.created}")
    print(f"  Assignee: {issue.fields.assignee.displayName}")

Report Generation

# Generate report on verification issues
def generate_jira_verification_report(days: int = 7):
    issues = handler.search(
        jql=f'project = OPS AND created >= -{days}d AND labels = verification'
    )


    report = {
        "period": f"Last {days} days",
        "total_issues": len(issues),
        "by_status": {},
        "by_priority": {},
        "by_assignee": {}
    }


    for issue in issues:
        status = issue.fields.status.name
        priority = issue.fields.priority.name if issue.fields.priority else "Unknown"
        assignee = issue.fields.assignee.displayName if issue.fields.assignee else "Unassigned"


        report["by_status"][status] = report["by_status"].get(status, 0) + 1
        report["by_priority"][priority] = report["by_priority"].get(priority, 0) + 1
        report["by_assignee"][assignee] = report["by_assignee"].get(assignee, 0) + 1


    return report

Field Mapping

Common Field Patterns

field_mapping = {
    # TruthVouch Alert → Jira Issue
    "alert.severity": "priority",
    "alert.title": "summary",
    "alert.description": "description",
    "alert.category": "labels",
    "alert.affected_system": "components",
    "alert.created": "created",
    "on_call_user": "assignee"
}


# Custom mapping for healthcare
healthcare_mapping = {
    **field_mapping,
    "alert.patient_impact": "customfield_10001",
    "alert.regulatory_requirement": "customfield_10002"
}

Automation and Escalation

Jira Automation Rule

In Jira Automation:

Rule: "Escalate to On-Call"
When: Issue created AND project = OPS AND priority >= High
Then:
  - Assign to: On-call rotation
  - Set due date: Now + 2 hours
  - Add label: urgent
  - Send notification: #on-call Slack channel

Escalation Handler

@app.route("/escalate", methods=["POST"])
def escalate_issue():
    """Escalate Jira issue to on-call."""


    issue_key = request.get_json()["issue_key"]
    issue = handler.get_issue(issue_key)


    # Update priority
    handler.update_issue(issue_key, {
        "priority": {"name": "Highest"},
        "labels": ["escalated", "urgent"]
    })


    # Notify on-call via Slack
    slack_client.chat_postMessage(
        channel="#on-call",
        text=f"Escalated: <https://jira.company.com/browse/{issue_key}|{issue.fields.summary}>"
    )


    return {"status": "escalated"}, 200

Integration with Webhooks

Bidirectional Flow

TruthVouch Alert
    ↓
Webhook to Jira Integration
    ↓
Create/Update Jira Issue
    ↓
Jira Automation Rules Trigger
    ↓
Notify Team
    ↓
Issue Resolution
    ↓
Webhook back to TruthVouch
    ↓
Update Alert Status

Webhook Handler

Configure webhook endpoints via the TruthVouch dashboard to receive alerts and trigger Jira issue creation. Use standard Flask or FastAPI endpoints to handle webhook POST requests with alert payloads.

Best Practices

Issue Quality

  • Include context from TruthVouch (confidence, citations)
  • Add deep links to dashboard for review
  • Use templates for consistency
  • Assign to appropriate team members

Ticket Management

  • Don’t create duplicate issues for same alert
  • Batch related alerts into single epic
  • Link related issues with “blocks” relationship
  • Archive resolved issues after 30 days

Automation

  • Use automation rules to reduce manual steps
  • Set appropriate SLAs per severity
  • Auto-escalate if not updated in 24h
  • Close resolved issues automatically

Troubleshooting

Q: Issues not creating

  • Verify API token is valid
  • Check project key exists
  • Ensure issue type is available in project
  • Check custom fields exist

Q: Field mapping issues

  • Validate custom field IDs
  • Check field is visible in screen
  • Verify field is in issue type
  • Test manually in Jira first

Q: Webhook sync failing

  • Verify webhook URL is correct
  • Check TruthVouch can reach Jira
  • Implement idempotency (same request twice = same result)
  • Add request logging

Next Steps