/health-check-jiras

Name

teams:health-check-jiras

Synopsis

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

Description

The teams:health-check-jiras command queries JIRA bugs for a specified project and generates summary statistics. It leverages the list-jiras command to fetch raw JIRA data and then calculates counts by status, priority, and component to help understand the bug backlog at a glance.

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:

• Getting a quick count of open bugs in a JIRA project
• Analyzing bug distribution by status, priority, or component
• Tracking recent bug flow (opened vs closed in last 30 days)
• Generating summary reports for bug backlog
• Monitoring bug velocity and closure rates by component or team
• Comparing bug counts across different components
• Getting team-level bug summaries across all team components

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://redhat.atlassian.net")
     • JIRA_USERNAME: Your JIRA username (email address) for Basic auth
     • JIRA_API_TOKEN: Your JIRA API token

   • Verify with:

     echo "JIRA_URL: ${JIRA_URL}"
     echo "JIRA_USERNAME: ${JIRA_USERNAME}"
     echo "JIRA_API_TOKEN: ${JIRA_API_TOKEN:+***set***}"
     

   • If missing, guide the user to set them:

     export JIRA_URL="https://redhat.atlassian.net"
     export JIRA_USERNAME="[email protected]"
     export JIRA_API_TOKEN="your-api-token-here"
     

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

   • Project key: Required --project flag (e.g., "OCPBUGS", "OCPSTRAT")
   • Optional filters:
     • --component: Space-separated list of component search strings (fuzzy match)
     • --team: Team name (looks up all components for that team)
     • --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)
   • Note: --component and --team are mutually exclusive

4. Resolve Component Names: Use fuzzy matching or team lookup to find actual component names

   • If --team was provided:
     • The script will handle team component lookup internally via get_team_components()
     • If team not found, display available teams and exit
   • Else if --component was provided:
     • Extract release from context or ask user for release version
     • Run list_components.py to get all available components:

       python3 plugins/teams/skills/list-components/list_components.py
       

     • 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 summarize_jiras.py script

   • Script location: plugins/teams/skills/summarize-jiras/summarize_jiras.py
   • The script internally calls list_jiras.py to fetch raw data and handles all components in one invocation
   • If --team was provided:
     • Execute: python3 summarize_jiras.py --project <project> --team "<team>" [other args]
     • Script automatically looks up all team components and queries them
     • Returns team-level summary and per-component breakdowns
   • Else if --component was provided:
     • Execute: python3 summarize_jiras.py --project <project> --component <components> [other args]
     • Script handles all components in one invocation
     • Returns overall summary and per-component breakdowns
   • Else:
     • Execute: python3 summarize_jiras.py --project <project> [other args]
     • Queries all bugs in the project
   • Capture JSON output from stdout

6. Parse Output: Process the aggregated JSON response

   • Extract summary statistics:
     • total_count: Total matching issues in JIRA
     • fetched_count: Number of issues actually fetched
     • summary.by_status: Count of issues per status
     • summary.by_priority: Count of issues per priority
     • summary.by_component: Count of issues per component
   • Extract per-component breakdowns:
     • Each component has its own counts by status and priority
     • Includes opened/closed in last 30 days per component

7. Present Results: Display summary in a clear format

   • Show which components were matched (if fuzzy search was used)
   • Show total bug count across all components
   • Display status breakdown (e.g., New, In Progress, Verified, etc.)
   • Display priority breakdown (Critical, Major, Normal, Minor, etc.)
   • Display component distribution
   • Show per-component breakdowns with status and priority counts
   • 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 a JIRA Bug Summary with the following information:

Project Overview

• Project: JIRA project key
• Total Count: Total number of matching bugs (open + recently closed)
• Query: JQL query that was executed (includes 30-day closed bug filter)
• Fetched Count: Number of bugs actually fetched (may be less than total if limited)

Summary Statistics

Overall Metrics:

• Total bugs fetched
• Bugs opened in last 30 days
• Bugs closed in last 30 days

By Status: Count of bugs in each status (includes recently closed)

Status	Count
New	X
In Progress	X
Verified	X
Closed	X
...	...

By Priority: Count of bugs by priority level

Priority	Count
Critical	X
Major	X
Normal	X
Minor	X
Undefined	X

By Component: Count of bugs per component

Component	Count
kube-apiserver	X
Management Console	X
Networking	X
...	...

Per-Component Breakdown

For each component:

• Total: Number of bugs assigned to this component
• Opened (30d): Bugs created in the last 30 days
• Closed (30d): Bugs closed in the last 30 days
• By Status: Status distribution for this component
• By Priority: Priority distribution for this component

Additional Information

• Filters Applied: Lists any component, status, or other filters used
• Note: If results are truncated, suggests increasing the limit
• Query Scope: By default includes open bugs and bugs closed in the last 30 days

Examples

1. Summarize all open bugs for a project:

   /teams:health-check-jiras --project OCPBUGS
   

   Fetches all open bugs in the OCPBUGS project (up to default limit of 1000) and displays summary statistics.

2. Filter by specific component:

   /teams:health-check-jiras --project OCPBUGS --component "kube-apiserver"
   

   Shows bug counts for only the kube-apiserver component.

3. Filter by multiple components:

   /teams:health-check-jiras --project OCPBUGS --component "kube-apiserver" "etcd" "Networking"
   

   Shows bug counts for kube-apiserver, etcd, and Networking components.

4. Include closed bugs:

   /teams:health-check-jiras --project OCPBUGS --include-closed --limit 500
   

   Includes both open and closed bugs, fetching up to 500 issues.

5. Filter by status:

   /teams:health-check-jiras --project OCPBUGS --status New "In Progress" Verified
   

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

6. Filter by team:

   /teams:health-check-jiras --project OCPBUGS --team "API Server"
   

   Automatically looks up all components for the "API Server" team and shows bug counts:

   • Queries all team components in one invocation
   • Returns overall team summary
   • Includes per-component breakdowns
   • Use /teams:list-teams to see available team names

7. Combine multiple filters:

   /teams:health-check-jiras --project OCPBUGS --component "Management Console" --status New Assigned --limit 200
   

   Shows bugs for Management Console component that are in New or Assigned status.

Arguments

• --project <project> (required): JIRA project key

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

• Additional optional 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
    • Handles all components in one invocation
    • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
    • Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
    • Mutually exclusive with --team

  • --team <team-name>: Filter by team name

    • Looks up all components for the team from team_component_map.json
    • Handles all team components in one invocation
    • Returns overall team summary and per-component breakdowns
    • Use /teams:list-teams to see available team names
    • Team names are case-sensitive
    • Mutually exclusive with --component

  • --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 and summarization scripts

   • Check: which python3
   • Version: 3.6 or later

2. JIRA Authentication: Environment variables must be configured

   • JIRA_URL: Your JIRA instance URL
   • JIRA_USERNAME: Your JIRA username (email address) for Basic auth
   • JIRA_API_TOKEN: Your JIRA API token

   How to get a JIRA API token:

   • Navigate to https://id.atlassian.com/manage-profile/security/api-tokens
   • Generate a new API token
   • 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
• Diagnostic messages are written to stderr, data to stdout
• The script has a 30-second timeout for HTTP requests
• For large projects, use component filters to reduce query size
• Summary statistics are based on fetched issues (controlled by --limit), not total matching issues
• If results show truncation, increase the --limit parameter for more accurate statistics
• This command internally uses /teams:list-jiras to fetch raw data

See Also

• Skill Documentation: plugins/teams/skills/summarize-jiras/SKILL.md
• Script: plugins/teams/skills/summarize-jiras/summarize_jiras.py
• Related Command: /teams:list-jiras (for raw JIRA data)
• Related Command: /teams:health-check (for combined health analysis)