/list-jiras

Name

component-health:list-jiras

Synopsis

/component-health:list-jiras <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]

Description

The component-health:list-jiras command queries JIRA bugs for a specified project and returns raw issue data. It fetches JIRA issues with all their fields and metadata without performing any summarization or aggregation.

By default, the command includes:

• All currently open bugs
• Bugs closed in the last 30 days (to track recent closure activity)

This command is useful for:

• Fetching raw JIRA issue data for further processing
• Accessing complete issue details including all fields
• Building custom analysis workflows
• Providing data to other commands (like summarize-jiras)
• Exporting JIRA data for offline analysis

Implementation

1. Verify Prerequisites: Check that Python 3 is installed

   • Run: python3 --version
   • Verify version 3.6 or later is available

2. Verify Environment Variables: Ensure JIRA authentication is configured

   • Check that the following environment variables are set:

     • JIRA_URL: Base URL for JIRA instance (e.g., "https://issues.redhat.com")
     • JIRA_PERSONAL_TOKEN: Your JIRA bearer token or personal access token

   • Verify with:

     echo "JIRA_URL: ${JIRA_URL}"
     echo "JIRA_PERSONAL_TOKEN: ${JIRA_PERSONAL_TOKEN:+***set***}"
     

   • If missing, guide the user to set them:

     export JIRA_URL="https://issues.redhat.com"
     export JIRA_PERSONAL_TOKEN="your-token-here"
     

3. Parse Arguments: Extract project key and optional filters from arguments

   • Project key: Required first argument (e.g., "OCPBUGS", "OCPSTRAT")
   • Optional filters:
     • --component: Space-separated list of component search strings (fuzzy match)
     • --status: Space-separated list of status values
     • --include-closed: Flag to include closed bugs
     • --limit: Maximum number of issues to fetch per component (default: 1000, max: 1000)

4. Resolve Component Names (if component filter provided): Use fuzzy matching to find actual component names

   • Extract release from context or ask user for release version
   • Run list_components.py to get all available components:

     python3 plugins/component-health/skills/list-components/list_components.py --release <release>
     

   • For each search string in --component:
     • Find all components containing that string (case-insensitive)
     • Combine all matches into a single list
     • Remove duplicates
     • If no matches found for a search string, warn the user and show available components

5. Execute Python Script: Run the list_jiras.py script for each component

   • Script location: plugins/component-health/skills/list-jiras/list_jiras.py
   • Important: Iterate over each resolved component separately to avoid overly large queries
   • For each component:
     • Build command with project, single component, and other filters
     • Execute: python3 list_jiras.py --project <project> --component "<component>" [other args]
     • Capture JSON output from stdout
   • Aggregate results from all components into a combined response

6. Parse Output: Process the aggregated JSON response

   • Extract metadata:
     • project: Project key queried
     • total_count: Total matching issues in JIRA
     • fetched_count: Number of issues actually fetched
     • query: JQL query that was executed
     • filters: Applied filters
   • Extract raw issues array:
     • issues: Array of complete JIRA issue objects with all fields

7. Present Results: Display or store the raw JIRA data

   • Show which components were matched (if fuzzy search was used)
   • The command returns the aggregated JSON response with metadata and raw issues from all components
   • Inform the user about total count vs fetched count per component
   • The raw issue data can be passed to other commands for analysis
   • Suggest using /component-health:summarize-jiras for summary statistics
   • Highlight any truncation (if fetched_count < total_count for any component)
   • Suggest increasing --limit if results are truncated

8. Error Handling: Handle common error scenarios

   • Network connectivity issues
   • Invalid JIRA credentials
   • Invalid project key
   • HTTP errors (401, 404, 500, etc.)
   • Rate limiting (429)

Return Value

The command outputs raw JIRA issue data in JSON format with the following structure:

Metadata

• project: JIRA project key that was queried
• total_count: Total number of matching issues in JIRA
• fetched_count: Number of issues actually fetched (may be less than total if limited)
• query: JQL query that was executed (includes filters)
• filters: Object containing applied filters:
  • components: List of component filters or null
  • statuses: List of status filters or null
  • include_closed: Boolean indicating if closed bugs were included
  • limit: Maximum number of issues fetched

Issues Array

• issues: Array of raw JIRA issue objects, each containing:
  • key: Issue key (e.g., "OCPBUGS-12345")
  • fields: Object containing all issue fields:
    • summary: Issue title/summary
    • status: Status object with name and ID
    • priority: Priority object with name and ID
    • components: Array of component objects
    • assignee: Assignee object with user details
    • created: Creation timestamp
    • updated: Last updated timestamp
    • resolutiondate: Resolution timestamp (if closed)
    • versions: Affects Version/s array
    • fixVersions: Fix Version/s array
    • customfield_12319940: Target Version (custom field)
    • And other JIRA fields as applicable

Additional Information

• note: (Optional) If results are truncated, includes a note suggesting to increase the limit
• component_queries: (Optional) When multiple components are queried, this array shows the individual query executed for each component. Each entry contains:
  • component: The component name
  • query: The JQL query executed for this component
  • total_count: Total matching issues for this component
  • fetched_count: Number of issues fetched for this component

Example Output Structure

{
  "project": "OCPBUGS",
  "total_count": 1500,
  "fetched_count": 100,
  "query": "project = OCPBUGS AND (status != Closed OR (status = Closed AND resolved >= \"2025-10-11\"))",
  "filters": {
    "components": null,
    "statuses": null,
    "include_closed": false,
    "limit": 100
  },
  "component_queries": [
    {
      "component": "kube-apiserver",
      "query": "project = OCPBUGS AND component = \"kube-apiserver\" AND ...",
      "total_count": 800,
      "fetched_count": 50
    },
    {
      "component": "kube-controller-manager",
      "query": "project = OCPBUGS AND component = \"kube-controller-manager\" AND ...",
      "total_count": 700,
      "fetched_count": 50
    }
  ],
  "issues": [
    {
      "key": "OCPBUGS-12345",
      "fields": {
        "summary": "Bug title here",
        "status": {"name": "New", "id": "1"},
        "priority": {"name": "Major", "id": "3"},
        "components": [{"name": "kube-apiserver"}],
        "created": "2025-11-01T10:30:00.000+0000",
        ...
      }
    },
    ...
  ],
  "note": "Showing first 100 of 1500 total results. Increase --limit for more data."
}

Examples

1. List all open bugs for a project:

   /component-health:list-jiras OCPBUGS
   

   Fetches all open bugs in the OCPBUGS project (up to default limit of 1000) and returns raw issue data.

2. Filter by specific component (exact match):

   /component-health:list-jiras OCPBUGS --component "kube-apiserver"
   

   Returns raw data for bugs in the kube-apiserver component only.

3. Filter by fuzzy search:

   /component-health:list-jiras OCPBUGS --component network
   

   Finds all components containing "network" (case-insensitive) and returns bugs for all matches (e.g., "Networking / ovn-kubernetes", "Networking / DNS", etc.). Makes separate JIRA queries for each component and aggregates results.

4. Filter by multiple search strings:

   /component-health:list-jiras OCPBUGS --component etcd kube-
   

   Finds all components containing "etcd" OR "kube-" and returns combined bug data. Iterates over each component separately to avoid overly large queries.

5. Include closed bugs:

   /component-health:list-jiras OCPBUGS --include-closed --limit 500
   

   Returns both open and closed bugs, fetching up to 500 issues per component.

6. Filter by status:

   /component-health:list-jiras OCPBUGS --status New "In Progress" Verified
   

   Returns only bugs in New, In Progress, or Verified status.

7. Combine fuzzy search with other filters:

   /component-health:list-jiras OCPBUGS --component network --status New Assigned --limit 200
   

   Returns bugs for all networking components that are in New or Assigned status.

Arguments

• $1 (required): JIRA project key

  • Format: Project key in uppercase (e.g., "OCPBUGS", "OCPSTRAT")
  • Must be a valid JIRA project you have access to

• $2+ (optional): Filter flags

  • --component <search1> [search2 ...]: Filter by component names using fuzzy search

    • Space-separated list of component search strings
    • Case-insensitive substring matching
    • Each search string matches all components containing that substring
    • Makes separate JIRA queries for each matched component to avoid overly large results
    • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
    • Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
    • Note: Requires release context (inferred from recent commands or specified by user)

  • --status <status1> [status2 ...]: Filter by status values

    • Space-separated list of status names
    • Examples: New, "In Progress", Verified, Modified, ON_QA

  • --include-closed: Include closed bugs in results

    • By default, only open bugs are returned
    • When specified, closed bugs are included

  • --limit <N>: Maximum number of issues to fetch per component

    • Default: 1000
    • Range: 1-1000
    • When using component filters, this limit applies to each component separately
    • Higher values provide more accurate statistics but slower performance

Prerequisites

1. Python 3: Required to run the data fetching script

   • Check: which python3
   • Version: 3.6 or later

2. JIRA Authentication: Environment variables must be configured

   • JIRA_URL: Your JIRA instance URL
   • JIRA_PERSONAL_TOKEN: Your JIRA bearer token or personal access token

   How to get a JIRA token:

   • Navigate to JIRA → Profile → Personal Access Tokens
   • Generate a new token with appropriate permissions
   • Export it as an environment variable

3. Network Access: Must be able to reach your JIRA instance

   • Ensure HTTPS requests can be made to JIRA_URL
   • Check firewall and VPN settings if needed

Notes

• The script uses Python's standard library only (no external dependencies)
• Output is JSON format for easy parsing and further processing
• Diagnostic messages are written to stderr, data to stdout
• The script has a 30-second timeout for HTTP requests
• For large projects, consider using component filters to reduce query size
• The returned data includes ALL JIRA fields for each issue, providing complete information
• If you need summary statistics, use /component-health:summarize-jiras instead
• If results show truncation, increase the --limit parameter to fetch more issues

See Also

• Skill Documentation: plugins/component-health/skills/list-jiras/SKILL.md
• Script: plugins/component-health/skills/list-jiras/list_jiras.py
• Related Command: /component-health:summarize-jiras (for summary statistics)
• Related Command: /component-health:analyze