Skip to content

Issues Command

The aetheris issues command creates GitHub issues from analysis reports.

Prerequisites

GitHub CLI Version

GitHub CLI (gh) version 2.4.0 or higher is required. This version introduced stable support for OAuth scopes management used by this command.

Check your installed version:

gh --version

To install or upgrade, visit: https://cli.github.com/ or use your package manager:

# macOS
brew upgrade gh

# Windows (winget)
winget upgrade GitHub.cli

# Linux (apt)
sudo apt update && sudo apt upgrade gh

Authentication

GitHub CLI must be authenticated with the required scopes:

gh auth login --scopes repo

Required Scopes

Scope Purpose
repo Full control of private repositories (includes issues)

For public repositories only, you can use the more limited scope:

gh auth login --scopes public_repo

Verify Authentication

Check your current authentication status and scopes:

gh auth status

If you need to add scopes to an existing authentication:

gh auth refresh --scopes repo

Usage

aetheris issues [options]

Options

Option Description
--dry-run Preview issues without creating them
--labels LABELS Additional labels (comma-separated)
--assignee USER GitHub username to assign issues
--repo REPO Target repository (owner/repo format). If omitted, automatically detected from the current directory's .git configuration
--from-report FILE Process only this specific report file (Markdown format, see Report Format)

Examples

Create Issues from All Reports

aetheris issues

Preview Without Creating

aetheris issues --dry-run

With Custom Labels

aetheris issues --labels security,sprint-42

Assign to User

aetheris issues --assignee username

Target Specific Repository

aetheris issues --repo owner/repo

From Specific Report

aetheris issues --from-report docs/analyses/analyzer.md

Report Format

The --from-report option expects a Markdown file generated by Aetheris analysis (typically found in docs/analyses/).

Required Structure

The report file must contain bug entries in the following format:

### Bug ID: BUG-XXXXXXXX
**Type**: <bug_type>
**Severity**: <critical|high|medium|low>
**Line**: <line_number>
**Description**: <description>
**Recommendation**: <fix_recommendation>

Supported File Types

Format Extension Status
Aetheris Markdown Report .md ✅ Supported
JSON .json ❌ Not supported
Plain text .txt ❌ Not supported

Error Handling

Scenario Behavior
File not found Command exits with error message
Empty file No issues created, warning displayed
Invalid format (no bugs found) No issues created, info message displayed
Malformed bug entry Entry skipped, warning logged

Example Valid Report

# Analysis Report: src/core/analyzer.py

## Summary
- Total bugs: 2
- Critical: 1
- High: 1

## Bugs

### Bug ID: BUG-12345678
**Type**: security
**Severity**: critical
**Line**: 42
**Description**: SQL injection vulnerability in query builder
**Recommendation**: Use parameterized queries instead of string concatenation

### Bug ID: BUG-87654321
**Type**: performance
**Severity**: high
**Line**: 108
**Description**: N+1 query pattern in loop
**Recommendation**: Use batch fetching or eager loading

Issue Format

Each created issue includes:

Title

[BugType] in filename - brief description

Body Sections

  • File: Path to the affected file
  • Bug Description: What the issue is
  • Issue Details: Severity, line number, context
  • Recommended Solution: How to fix it
  • Code Context: Relevant code snippet

Labels

  • bug - Issue type
  • aetheris-analysis - Source identifier
  • Severity level (critical, high, medium, low)
  • Custom labels via --labels

Deduplication

The command automatically skips issues that already exist (matched by title).

Rate Limiting

GitHub API rate limits are handled automatically with progress feedback.

Workflow

  1. Run analysis: aetheris analysis
  2. Preview issues: aetheris issues --dry-run
  3. Create issues: aetheris issues
  4. Generate fix PRs: aetheris pr-gen --link-issues