386 lines
11 KiB
Markdown
386 lines
11 KiB
Markdown
---
|
|
name: List JIRAs
|
|
description: Query and return raw JIRA bug data for a specific project
|
|
---
|
|
|
|
# List JIRAs
|
|
|
|
This skill provides functionality to query JIRA bugs for a specified project and return raw issue data. It uses the JIRA REST API to fetch complete bug information with all fields and metadata, without performing any summarization.
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when you need to:
|
|
|
|
- Fetch raw JIRA issue data for further processing
|
|
- Access complete issue details including all fields
|
|
- Build custom analysis workflows
|
|
- Provide data to other commands (like `summarize-jiras`)
|
|
- Export JIRA data for offline analysis
|
|
|
|
## Prerequisites
|
|
|
|
1. **Python 3 Installation**
|
|
|
|
- Check if installed: `which python3`
|
|
- Python 3.6 or later is required
|
|
- Comes pre-installed on most systems
|
|
|
|
2. **JIRA Authentication**
|
|
|
|
- Requires environment variables to be 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
|
|
- 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**
|
|
- The script requires network access to reach your JIRA instance
|
|
- Ensure you can make HTTPS requests to the JIRA URL
|
|
|
|
## Implementation Steps
|
|
|
|
### Step 1: Verify Prerequisites
|
|
|
|
First, ensure Python 3 is available:
|
|
|
|
```bash
|
|
python3 --version
|
|
```
|
|
|
|
If Python 3 is not installed, guide the user through installation for their platform.
|
|
|
|
### Step 2: Verify Environment Variables
|
|
|
|
Check that required environment variables are set:
|
|
|
|
```bash
|
|
# Verify JIRA credentials are configured
|
|
echo "JIRA_URL: ${JIRA_URL}"
|
|
echo "JIRA_PERSONAL_TOKEN: ${JIRA_PERSONAL_TOKEN:+***set***}"
|
|
```
|
|
|
|
If any are missing, guide the user to set them:
|
|
|
|
```bash
|
|
export JIRA_URL="https://issues.redhat.com"
|
|
export JIRA_PERSONAL_TOKEN="your-token-here"
|
|
```
|
|
|
|
### Step 3: Locate the Script
|
|
|
|
The script is located at:
|
|
|
|
```
|
|
plugins/component-health/skills/list-jiras/list_jiras.py
|
|
```
|
|
|
|
### Step 4: Run the Script
|
|
|
|
Execute the script with appropriate arguments:
|
|
|
|
```bash
|
|
# Basic usage - all open bugs in a project
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS
|
|
|
|
# Filter by component
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS \
|
|
--component "kube-apiserver"
|
|
|
|
# Filter by multiple components
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS \
|
|
--component "kube-apiserver" "Management Console"
|
|
|
|
# Include closed bugs
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS \
|
|
--include-closed
|
|
|
|
# Filter by status
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS \
|
|
--status New "In Progress"
|
|
|
|
# Set maximum results limit (default 100)
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS \
|
|
--limit 500
|
|
```
|
|
|
|
### Step 5: Process the Output
|
|
|
|
The script outputs JSON data with the following 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
|
|
},
|
|
"issues": [
|
|
{
|
|
"key": "OCPBUGS-12345",
|
|
"fields": {
|
|
"summary": "Bug title here",
|
|
"status": {
|
|
"name": "New",
|
|
"id": "1"
|
|
},
|
|
"priority": {
|
|
"name": "Major",
|
|
"id": "3"
|
|
},
|
|
"components": [
|
|
{"name": "kube-apiserver", "id": "12345"}
|
|
],
|
|
"assignee": {
|
|
"displayName": "John Doe",
|
|
"emailAddress": "jdoe@example.com"
|
|
},
|
|
"created": "2025-11-01T10:30:00.000+0000",
|
|
"updated": "2025-11-05T14:20:00.000+0000",
|
|
"resolutiondate": null,
|
|
"versions": [
|
|
{"name": "4.21"}
|
|
],
|
|
"fixVersions": [
|
|
{"name": "4.22"}
|
|
],
|
|
"customfield_12319940": "4.22.0"
|
|
}
|
|
},
|
|
...more issues...
|
|
],
|
|
"note": "Showing first 100 of 1500 total results. Increase --limit for more data."
|
|
}
|
|
```
|
|
|
|
**Field Descriptions**:
|
|
|
|
- `project`: The JIRA project queried
|
|
- `total_count`: Total number of matching issues in JIRA (from search results)
|
|
- `fetched_count`: Number of issues actually fetched (limited by --limit parameter)
|
|
- `query`: The JQL query executed (includes filter for recently closed bugs)
|
|
- `filters`: Applied filters (components, statuses, include_closed, limit)
|
|
- `issues`: Array of raw JIRA issue objects, each containing:
|
|
- `key`: Issue key (e.g., "OCPBUGS-12345")
|
|
- `fields`: Object containing all JIRA fields for the issue:
|
|
- `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 (null if not closed)
|
|
- `versions`: Affects Version/s array
|
|
- `fixVersions`: Fix Version/s array
|
|
- `customfield_12319940`: Target Version (custom field)
|
|
- And many other JIRA fields as applicable
|
|
- `note`: Informational message if results are truncated
|
|
|
|
**Important Notes**:
|
|
|
|
- **By default, the query includes**: Open bugs + bugs closed in the last 30 days
|
|
- This allows tracking of recent closure activity alongside current open bugs
|
|
- The script fetches a maximum number of issues (default 1000, configurable with `--limit`)
|
|
- The `total_count` represents all matching issues in JIRA
|
|
- The returned data includes ALL fields for each issue, providing complete information
|
|
- For large datasets, increase the `--limit` parameter to fetch more issues
|
|
- Issues can have multiple components
|
|
- All JIRA field data is preserved in the raw format
|
|
|
|
### Step 6: Present Results
|
|
|
|
Based on the raw JIRA data:
|
|
|
|
1. Inform the user about the total count vs fetched count
|
|
2. Explain that the raw data includes all JIRA fields
|
|
3. Suggest using `/component-health:summarize-jiras` if they need summary statistics
|
|
4. The raw issue data can be passed to other commands for further processing
|
|
5. Highlight any truncation and suggest increasing --limit if needed
|
|
|
|
## Error Handling
|
|
|
|
### Common Errors
|
|
|
|
1. **Authentication Errors**
|
|
|
|
- **Symptom**: HTTP 401 Unauthorized
|
|
- **Solution**: Verify JIRA_PERSONAL_TOKEN is correct
|
|
- **Check**: Ensure token has not expired
|
|
|
|
2. **Network Errors**
|
|
|
|
- **Symptom**: `URLError` or connection timeout
|
|
- **Solution**: Check network connectivity and JIRA_URL is accessible
|
|
- **Retry**: The script has a 30-second timeout, consider retrying
|
|
|
|
3. **Invalid Project**
|
|
|
|
- **Symptom**: HTTP 400 or empty results
|
|
- **Solution**: Verify the project key is correct (e.g., "OCPBUGS", not "ocpbugs")
|
|
|
|
4. **Missing Environment Variables**
|
|
|
|
- **Symptom**: Error message about missing credentials
|
|
- **Solution**: Set required environment variables (JIRA_URL, JIRA_USERNAME, JIRA_PERSONAL_TOKEN)
|
|
|
|
5. **Rate Limiting**
|
|
- **Symptom**: HTTP 429 Too Many Requests
|
|
- **Solution**: Wait before retrying, reduce query frequency
|
|
|
|
### Debugging
|
|
|
|
Enable verbose output by examining stderr:
|
|
|
|
```bash
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS 2>&1 | tee debug.log
|
|
```
|
|
|
|
## Script Arguments
|
|
|
|
### Required Arguments
|
|
|
|
- `--project`: JIRA project key to query
|
|
- Format: Project key (e.g., "OCPBUGS", "OCPSTRAT")
|
|
- Must be a valid JIRA project
|
|
|
|
### Optional Arguments
|
|
|
|
- `--component`: Filter by component names
|
|
|
|
- Values: Space-separated list of component names
|
|
- Default: None (returns all components)
|
|
- Case-sensitive matching
|
|
- Examples: `--component "kube-apiserver" "Management Console"`
|
|
|
|
- `--status`: Filter by status values
|
|
|
|
- Values: Space-separated list of status names
|
|
- Default: None (returns all statuses except Closed)
|
|
- Examples: `--status New "In Progress" Verified`
|
|
|
|
- `--include-closed`: Include closed bugs in the results
|
|
|
|
- Default: false (only open bugs)
|
|
- When specified, includes bugs in "Closed" status
|
|
|
|
- `--limit`: Maximum number of issues to fetch
|
|
- Default: 100
|
|
- Maximum: 1000 (JIRA API limit per request)
|
|
- Higher values provide more accurate statistics but slower performance
|
|
|
|
## Output Format
|
|
|
|
The script outputs JSON with metadata and raw issue data:
|
|
|
|
```json
|
|
{
|
|
"project": "OCPBUGS",
|
|
"total_count": 5430,
|
|
"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
|
|
},
|
|
"issues": [
|
|
{
|
|
"key": "OCPBUGS-12345",
|
|
"fields": {
|
|
"summary": "Example bug",
|
|
"status": {"name": "New"},
|
|
"priority": {"name": "Major"},
|
|
"components": [{"name": "kube-apiserver"}],
|
|
"created": "2025-11-01T10:30:00.000+0000",
|
|
...
|
|
}
|
|
},
|
|
...
|
|
],
|
|
"note": "Showing first 100 of 5430 total results. Increase --limit for more data."
|
|
}
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Example 1: List All Open Bugs
|
|
|
|
```bash
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS
|
|
```
|
|
|
|
**Expected Output**: JSON containing raw issue data for all open bugs in OCPBUGS project
|
|
|
|
### Example 2: Filter by Component
|
|
|
|
```bash
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS \
|
|
--component "kube-apiserver"
|
|
```
|
|
|
|
**Expected Output**: JSON containing raw issue data for the kube-apiserver component only
|
|
|
|
### Example 3: Include Closed Bugs
|
|
|
|
```bash
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS \
|
|
--include-closed \
|
|
--limit 500
|
|
```
|
|
|
|
**Expected Output**: JSON containing raw issue data for both open and closed bugs (up to 500 issues)
|
|
|
|
### Example 4: Filter by Multiple Components
|
|
|
|
```bash
|
|
python3 plugins/component-health/skills/list-jiras/list_jiras.py \
|
|
--project OCPBUGS \
|
|
--component "kube-apiserver" "etcd" "Networking"
|
|
```
|
|
|
|
**Expected Output**: JSON containing raw issue data for bugs in specified components
|
|
|
|
## Integration with Commands
|
|
|
|
This skill is designed to:
|
|
|
|
- Provide raw JIRA data to other commands (like `summarize-jiras`)
|
|
- Be used directly for ad-hoc JIRA queries
|
|
- Serve as a data source for custom analysis workflows
|
|
- Export JIRA data for offline processing
|
|
|
|
## Related Skills
|
|
|
|
- `summarize-jiras`: Calculate summary statistics from JIRA data
|
|
- `list-regressions`: Fetch regression data for releases
|
|
- `analyze-regressions`: Grade component health based on regressions
|
|
- `get-release-dates`: Fetch OpenShift release dates
|
|
|
|
## Notes
|
|
|
|
- The script uses Python's `urllib` and `json` modules (no external dependencies)
|
|
- Output is always 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 complete information
|
|
- Use `/component-health:summarize-jiras` if you need summary statistics instead of raw data
|