JIRA

Connect QDrant Loader to JIRA to index project tickets, issues, requirements, and project management data. This guide covers setup for both JIRA Cloud and JIRA Data Center.

🎯 What Gets Processed

When you connect to JIRA, QDrant Loader can process:

Issue content - Summaries, descriptions, and comments
Issue metadata - Status, priority, assignee, labels, components
Attachments - Files attached to issues (when enabled)
Project information - Project descriptions and metadata

🔧 Authentication Setup

JIRA Cloud

API Token (Recommended)

Create an API Token:
Go to Atlassian Account Settings
Click "Create API token"
Give it a descriptive name like "QDrant Loader"
Copy the token
Set environment variables:

bash export JIRA_TOKEN=your_api_token_here export JIRA_EMAIL=your-email@company.com

JIRA Data Center

Personal Access Token

Create a Personal Access Token:
Go to JIRA → Settings → Personal Access Tokens
Click "Create token"
Set appropriate permissions: READ for projects and issues
Copy the token
Set environment variables:

bash export JIRA_TOKEN=your_personal_access_token

⚙️ Configuration

Basic Configuration

global_config:
  qdrant:
    url: "http://localhost:6333"
    collection_name: "documents"
  openai:
    api_key: "${OPENAI_API_KEY}"

projects:
  my-project:
    sources:
      jira:
        my-jira:
          base_url: "https://your-domain.atlassian.net"
          deployment_type: "cloud"
          project_key: "PROJ"
          token: "${JIRA_TOKEN}"
          email: "${JIRA_EMAIL}"
          download_attachments: true

Advanced Configuration

global_config:
  qdrant:
    url: "http://localhost:6333"
    collection_name: "documents"
  openai:
    api_key: "${OPENAI_API_KEY}"

projects:
  my-project:
    sources:
      jira:
        my-jira:
          base_url: "https://your-domain.atlassian.net"
          deployment_type: "cloud"
          project_key: "PROJ"
          token: "${JIRA_TOKEN}"
          email: "${JIRA_EMAIL}"

          # Rate limiting
          requests_per_minute: 60
          page_size: 50

          # Attachment handling
          download_attachments: true

          # Issue filtering
          issue_types:
            - "Story"
            - "Epic"
            - "Bug"
            - "Task"
          include_statuses:
            - "To Do"
            - "In Progress"
            - "Done"

          # File conversion (requires global file_conversion config)
          enable_file_conversion: true

Multiple JIRA Instances

global_config:
  qdrant:
    url: "http://localhost:6333"
    collection_name: "documents"
  openai:
    api_key: "${OPENAI_API_KEY}"

projects:
  my-project:
    sources:
      jira:
        # Production JIRA Cloud
        prod-jira:
          base_url: "https://company.atlassian.net"
          deployment_type: "cloud"
          project_key: "PROD"
          token: "${JIRA_TOKEN}"
          email: "${JIRA_EMAIL}"

        # Development JIRA Data Center
        dev-jira:
          base_url: "https://dev-jira.company.com"
          deployment_type: "datacenter"
          project_key: "DEV"
          token: "${DEV_JIRA_TOKEN}"

🎯 Configuration Options

Connection Settings

Option	Type	Description	Default
`base_url`	string	JIRA base URL	Required
`deployment_type`	string	Deployment type: "cloud", "datacenter", or "server"	`"cloud"`
`project_key`	string	Project key to process	Required
`token`	string	API token or Personal Access Token	Required
`email`	string	Email (required for Cloud)	Required for Cloud

Processing Settings

Option	Type	Description	Default
`requests_per_minute`	int	Rate limit for API calls	`60`
`page_size`	int	Number of issues per API request	`100`
`download_attachments`	bool	Download and process issue attachments	`false`
`enable_file_conversion`	bool	Enable file conversion for attachments	`false`

Issue Filtering

Option	Type	Description	Default
`issue_types`	list	Issue types to include	All types
`include_statuses`	list	Issue statuses to include	All statuses

🚀 Usage Examples

Software Development Team

global_config:
  qdrant:
    url: "http://localhost:6333"
    collection_name: "dev-docs"
  openai:
    api_key: "${OPENAI_API_KEY}"

projects:
  development:
    sources:
      jira:
        dev-project:
          base_url: "https://company.atlassian.net"
          deployment_type: "cloud"
          project_key: "DEV"
          token: "${JIRA_TOKEN}"
          email: "${JIRA_EMAIL}"

          # Focus on active work
          issue_types:
            - "Story"
            - "Epic"
            - "Bug"
            - "Task"
          include_statuses:
            - "To Do"
            - "In Progress"
            - "In Review"
            - "Done"

          # Include attachments for documentation
          download_attachments: true
          enable_file_conversion: true

Product Management

global_config:
  qdrant:
    url: "http://localhost:6333"
    collection_name: "product-docs"
  openai:
    api_key: "${OPENAI_API_KEY}"

projects:
  product:
    sources:
      jira:
        product-backlog:
          base_url: "https://company.atlassian.net"
          deployment_type: "cloud"
          project_key: "PROD"
          token: "${JIRA_TOKEN}"
          email: "${JIRA_EMAIL}"

          # Focus on planning items
          issue_types:
            - "Epic"
            - "Story"
            - "Initiative"

          # Include all content for context
          download_attachments: true
          enable_file_conversion: true

Support Team

global_config:
  qdrant:
    url: "http://localhost:6333"
    collection_name: "support-docs"
  openai:
    api_key: "${OPENAI_API_KEY}"

projects:
  support:
    sources:
      jira:
        support-tickets:
          base_url: "https://company.atlassian.net"
          deployment_type: "cloud"
          project_key: "SUP"
          token: "${JIRA_TOKEN}"
          email: "${JIRA_EMAIL}"

          # Support-focused issue types
          issue_types:
            - "Bug"
            - "Support Request"
            - "Incident"
            - "Problem"

          # Include customer communications
          download_attachments: true

🧪 Testing and Validation

Initialize and Configure

# Initialize workspace
qdrant-loader --workspace . init

# Configure the project
qdrant-loader --workspace . config

Validate Configuration

# Validate project configuration
qdrant-loader --workspace . project validate

# Check project status
qdrant-loader --workspace . project status

# List all projects
qdrant-loader --workspace . project list

Process JIRA Data

# Process all configured sources
qdrant-loader --workspace . ingest

# Process specific project
qdrant-loader --workspace . ingest --project my-project

# Process with verbose logging
qdrant-loader --workspace . --log-level debug ingest

🔧 Troubleshooting

Common Issues

Authentication Failures

Problem: 401 Unauthorized or 403 Forbidden

Solutions:

# Test API token manually
curl -u "your-email@company.com:your-api-token" \
  "https://your-domain.atlassian.net/rest/api/2/myself"

# Check project permissions
curl -u "your-email@company.com:your-api-token" \
  "https://your-domain.atlassian.net/rest/api/2/project"

# For Data Center, test with Personal Access Token
curl -H "Authorization: Bearer your-token" \
  "https://jira.company.com/rest/api/2/myself"

Project Access Issues

Problem: Project not found or No permission to access project

Solutions:

# List accessible projects
curl -u "your-email:your-token" \
  "https://your-domain.atlassian.net/rest/api/2/project" | jq '.[].key'

# Check specific project permissions
curl -u "your-email:your-token" \
  "https://your-domain.atlassian.net/rest/api/2/project/PROJ"

Rate Limiting

Problem: 429 Too Many Requests

Solutions:

projects:
  my-project:
    sources:
      jira:
        my-jira:
          base_url: "https://company.atlassian.net"
          deployment_type: "cloud"
          project_key: "PROJ"
          token: "${JIRA_TOKEN}"
          email: "${JIRA_EMAIL}"

          # Reduce request rate
          requests_per_minute: 30
          page_size: 25

Large Project Performance

Problem: Processing takes too long or times out

Solutions:

projects:
  my-project:
    sources:
      jira:
        my-jira:
          base_url: "https://company.atlassian.net"
          deployment_type: "cloud"
          project_key: "PROJ"
          token: "${JIRA_TOKEN}"
          email: "${JIRA_EMAIL}"

          # Optimize processing
          download_attachments: false
          page_size: 25
          requests_per_minute: 30

          # Filter to reduce scope
          issue_types: ["Story", "Bug"]
          include_statuses: ["Open", "In Progress"]

Debugging Commands

# Check JIRA API version
curl -u "email:token" "https://domain.atlassian.net/rest/api/2/serverInfo"

# List issues in a project
curl -u "email:token" \
  "https://domain.atlassian.net/rest/api/2/search?jql=project=PROJ&maxResults=5" | \
  jq '.issues[].key'

# Check issue details
curl -u "email:token" \
  "https://domain.atlassian.net/rest/api/2/issue/PROJ-123"

📊 Monitoring and Performance

Check Processing Status

# Check project status
qdrant-loader --workspace . project status

# Check specific project
qdrant-loader --workspace . project status --project-id my-project

# List all projects
qdrant-loader --workspace . project list

Performance Optimization

Monitor these aspects for JIRA processing:

Issues processed per minute - Processing throughput
API request rate - Requests per second to JIRA
Error rate - Percentage of failed issue requests
Attachment download time - Time to download and process files
Memory usage - Peak memory during processing

🔄 Best Practices

Project Organization

Use descriptive project keys - Make projects easy to identify
Organize with components - Use components for categorization
Apply consistent labeling - Use labels for cross-project categorization
Archive completed projects - Move old projects to archive status

Performance Optimization

Filter issue types - Process only relevant issue types
Limit attachment processing - Set download_attachments: false for large projects
Use appropriate page sizes - Balance between API calls and memory usage
Respect rate limits - Configure requests_per_minute appropriately

Security Considerations

Use API tokens - Prefer tokens over passwords
Limit token scope - Grant minimal necessary permissions
Rotate tokens regularly - Update tokens periodically
Monitor access - Track which projects are being accessed

Data Quality

Maintain consistent issue types - Use standard issue type schemes
Use structured descriptions - Follow description templates
Regular data cleanup - Archive or close old issues

File Conversion - Processing JIRA attachments
Configuration Reference - Complete configuration options
Troubleshooting - Common issues and solutions
MCP Server - Using processed JIRA content with AI tools

Ready to connect your JIRA instance? Start with the basic configuration above and customize based on your project structure and workflow needs.

Back to Documentation

Generated from jira.md

JIRA

🎯 What Gets Processed

🔧 Authentication Setup

JIRA Cloud

API Token (Recommended)

JIRA Data Center

Personal Access Token

⚙️ Configuration

Basic Configuration

Advanced Configuration

Multiple JIRA Instances

🎯 Configuration Options

Connection Settings

Processing Settings

Issue Filtering

🚀 Usage Examples

Software Development Team

Product Management

Support Team

🧪 Testing and Validation

Initialize and Configure

Validate Configuration

Process JIRA Data

🔧 Troubleshooting

Common Issues

Authentication Failures

Project Access Issues

Rate Limiting

Large Project Performance

Debugging Commands

📊 Monitoring and Performance

Check Processing Status

Performance Optimization

🔄 Best Practices

Project Organization

Performance Optimization

Security Considerations

Data Quality

📚 Related Documentation