336 lines
12 KiB
Markdown
336 lines
12 KiB
Markdown
---
|
|
description: Query and list raw JIRA bug data for a specific project
|
|
argument-hint: <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]
|
|
---
|
|
|
|
## 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:
|
|
```bash
|
|
echo "JIRA_URL: ${JIRA_URL}"
|
|
echo "JIRA_PERSONAL_TOKEN: ${JIRA_PERSONAL_TOKEN:+***set***}"
|
|
```
|
|
|
|
- If missing, guide the user to set them:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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`
|