Skip to content

Latest commit

 

History

History
214 lines (164 loc) · 7.72 KB

jira_data_flow.md

File metadata and controls

214 lines (164 loc) · 7.72 KB

Jira Data Flow Chart

This document describes the data flow between the AI Workflows system and Jira service.

System Architecture

graph TD
    JIRA[("Jira Service<br/>issues.redhat.com")]

    JIRA -->|"Direct API<br/>Search Issues"| FETCHER
    JIRA <-->|"API Calls via<br/>MCP Tools"| MCP

    FETCHER["Jira Issue Fetcher<br/>(Cron Job)<br/>jira_issue_fetcher.py<br/><br/>Direct API Access"]

    FETCHER -->|"Push Tasks"| REDIS_IN

    subgraph Redis["Redis Queues"]
        direction TB
        REDIS_IN["Input Queues:<br/>triage_queue"]
        REDIS_OUT["Output Queues:<br/>rebase_queue_*<br/>backport_queue_*<br/>clarification_needed_queue<br/>error_list<br/>open_ended_analysis_list"]
    end

    REDIS_IN -->|"Consume"| AGENTS

    AGENTS["AI Agents:<br/>Triage Agent<br/>Rebase Agent<br/>Backport Agent<br/><br/>Use MCP Tools Only"]

    AGENTS -->|"Call Tools"| MCP
    AGENTS -->|"Push Results"| REDIS_OUT

    MCP["MCP Server<br/>(FastMCP Tools)<br/>jira_tools.py<br/><br/>For AI Agents Only"]

    style FETCHER fill:#e8f4f8,stroke:#0277bd,stroke-width:3px
    style MCP fill:#fff4e6,stroke:#f57c00,stroke-width:3px
    style AGENTS fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
    style JIRA fill:#ffebee,stroke:#c62828,stroke-width:3px
Loading

Key Distinctions:

  • AI Agents - Use MCP Server tools to access Jira indirectly
  • Python Services - Direct HTTP API calls to Jira using requests library
  • MCP Server - Provides controlled FastMCP tools for AI agents only

Component Types

AI Agents (Use MCP Server)

These are AI-powered agents that use the MCP Server tools to interact with Jira:

  • Triage Agent - Analyzes issues, determines resolution type (rebase/backport/clarification/open-ended-analysis)
  • Rebase Agent - Updates packages to new upstream versions
  • Backport Agent - Applies specific patches to packages

These agents access Jira ONLY through MCP tools like get_jira_details(), add_jira_comment(), etc.

CVE extraction from summary text lives in ymir/common/cve.py. Agents import this shared parser directly so parsing does not load the privileged Jira client or its MOCK_JIRA implementation and flexmock dependency.

Python Services (Direct Jira API Access)

Traditional Python services that make direct HTTP calls to Jira:

  • Jira Issue Fetcher - Two CronJobs querying Jira on a schedule and pushing matches to the Redis triage queue: a main sweep against a saved Jira filter (query maintained in the separate cve-scope repo) and a ymir_todo-label sweep. Uses requests library for direct API calls.

The fetcher does NOT use the MCP Server; it calls Jira directly. QE agents use the MCP tools for Jira operations.

MCP Server

FastMCP server that provides controlled tools for AI agents:

  • Exposes 7 Jira-related tools (see MCP Server Tool Summary below)
  • Uses aiohttp for async HTTP calls to Jira
  • Only used by AI agents, not by Python services

Data Flow Overview

1. Jira Issue Fetcher → Jira (READ)

sequenceDiagram
    participant Fetcher as Jira Issue Fetcher
    participant Jira as Jira API
    participant Redis as Redis Queue

    Fetcher->>Jira: POST /rest/api/2/search<br/>JQL: saved filter "CVE work to do"<br/>(query maintained in cve-scope repo)
    Jira-->>Fetcher: Issues [{key, labels}]
    Fetcher->>Fetcher: Deduplicate & Filter<br/>(skip if Ymir labels exist)
    Fetcher->>Redis: Push Task to triage_queue<br/>{metadata: {issue: "RHEL-12345"}}
Loading

Key Features:

  • Pagination: 500 issues/page
  • Rate limiting: 5 calls/second
  • Exponential backoff on failures
  • Deduplication across all Redis queues

2. MCP Server Tools → Jira (READ/WRITE)

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Jira as Jira API

    rect rgb(200, 220, 240)
        Note over Agent,Jira: READ Operations
        Agent->>MCP: get_jira_details(issue_key)
        MCP->>Jira: GET /rest/api/2/issue/{key}?expand=comments
        MCP->>Jira: GET /rest/api/2/issue/{key}/remotelink
        Jira-->>MCP: Issue data + comments + links
        MCP-->>Agent: Complete issue details

        Agent->>MCP: check_cve_triage_eligibility(issue_key)
        MCP->>Jira: GET /rest/api/2/issue/{key}
        Jira-->>MCP: Issue fields (labels, fixVersions, severity)
        MCP-->>Agent: CVEEligibilityResult
    end

    rect rgb(240, 220, 200)
        Note over Agent,Jira: WRITE Operations
        Agent->>MCP: add_jira_comment(issue_key, comment)
        MCP->>Jira: POST /rest/api/2/issue/{key}/comment
        Jira-->>MCP: Success

        Agent->>MCP: edit_jira_labels(issue_key, add, remove)
        MCP->>Jira: PUT /rest/api/2/issue/{key}<br/>{update: {labels: [...]}}
        Jira-->>MCP: Success

        Agent->>MCP: change_jira_status(issue_key, status)
        MCP->>Jira: GET /rest/api/2/issue/{key}/transitions
        Jira-->>MCP: Available transitions
        MCP->>Jira: POST /rest/api/2/issue/{key}/transitions
        Jira-->>MCP: Success
    end
Loading

For an exactly Important or Critical Y-stream CVE, CVEEligibilityResult also contains shipped clones from each RHEL major's configured current Z-stream that have a non-empty Fixed in Build value. upcoming_z_streams and older Z-stream clones are ignored for inheritance. Each source retains its Jira key, NVR, and fixVersions. This metadata travels in Task.metadata to the backport queue, which uses only the single source matching the target Y-stream major. Old tasks without the field remain valid and use the normal backport path. A shipped clone without an NVR still satisfies the existing dependency decision but cannot be inherited.

Complete Workflow

flowchart TD
    START([Jira Issue Created])
    FETCH[Jira Issue Fetcher<br/>Queries Jira]
    FILTER{Has Ymir<br/>labels?}
    REDIS[(Redis<br/>triage_queue)]
    TRIAGE[Triage Agent]
    DECIDE{Resolution<br/>Type?}

    REBASE[Rebase Queue]
    BACKPORT[Backport Queue]
    CLARIFY[Clarification Queue]
    ANALYSIS[Open-Ended Analysis List]
    ERROR[Error List]

    PROCESS[Rebase/Backport<br/>Agents]
    UPDATE[Update Jira]

    START --> FETCH
    FETCH --> FILTER
    FILTER -->|No or retry_needed| REDIS
    FILTER -->|Yes| START
    REDIS --> TRIAGE
    TRIAGE --> DECIDE

    DECIDE -->|Rebase| REBASE
    DECIDE -->|Backport| BACKPORT
    DECIDE -->|Needs Info| CLARIFY
    DECIDE -->|Open-Ended Analysis| ANALYSIS
    DECIDE -->|Error| ERROR

    REBASE --> PROCESS
    BACKPORT --> PROCESS
    PROCESS --> UPDATE

    PROCESS -->|"Use MCP tools"| UPDATE
    UPDATE --> |Labels, Comments,<br/>Status, Fields| START
Loading

MCP Server Tool Summary

Tool Method Endpoint Purpose
get_jira_details GET /rest/api/2/issue/{key} Fetch issue details, comments, remote links
check_cve_triage_eligibility GET /rest/api/2/issue/{key} Analyze CVE eligibility for triage
verify_issue_author GET /rest/api/2/user Check if author is Red Hat employee
set_jira_fields PUT /rest/api/2/issue/{key} Update fixVersions, severity, target_end
add_jira_comment POST /rest/api/2/issue/{key}/comment Add public/private comment
change_jira_status POST /rest/api/2/issue/{key}/transitions Transition issue status
edit_jira_labels PUT /rest/api/2/issue/{key} Add/remove labels

Authentication & Configuration

All components authenticate using:

  • Bearer Token: JIRA_TOKEN environment variable
  • Base URL: JIRA_URL (default: https://issues.redhat.com)
  • Headers:
    {
      "Authorization": "Bearer {JIRA_TOKEN}",
      "Content-Type": "application/json",
      "Accept": "application/json"
    }

Last Updated: 2026-03-03