Skip to content

Issue Reporting

NØMAD includes an integrated issue reporting system that lets you submit bug reports, feature requests, and questions directly from the CLI, dashboard, or Console without leaving your workflow.

Overview

The issue system operates in three tiers:

  • CLI (nomad issue): Interactive form with duplicate detection
  • Dashboard: "Report Issue" tab with structured fields
  • Console (paid): Direct API submission + private support channel

All tiers auto-populate system information (NØMAD version, Python version, OS, active collectors, active alerts, cluster count) for better diagnostics.

CLI Commands

Report an Issue

nomad issue report                     # Interactive form
nomad issue report -c bug -m alerts    # Pre-select category and component
nomad issue report --email             # Send via email
nomad issue report --json              # Output as JSON (no submission)

The interactive form walks you through:

  1. Category: bug, feature, or question
  2. Component: collectors, alerts, dashboard, tessera, cli, console, dynamics, insights, reference, other
  3. Title: brief description
  4. Category-specific fields: steps to reproduce, expected/actual behavior (bugs), problem statement (features), question details (questions)
  5. Duplicate check: searches existing open issues for similar reports
  6. Submission: via GitHub API (with token) or browser link (without token)

Search Existing Issues

nomad issue search disk collector
nomad issue search gpu memory --max 10

Preview System Info

nomad issue info
nomad issue info --db /var/lib/nomad/cluster.db
nomad issue info --json

Dashboard Integration

The dashboard includes a "Report Issue" tab with:

  • Category selection (Bug Report / Feature Request / Question)
  • Component dropdown
  • Structured input fields that adapt to the selected category
  • Duplicate detection that warns about similar open issues
  • Auto-populated system info preview
  • "Submit Issue" and "Open in GitHub" buttons

Configuration

Configure direct API submission in nomad.toml:

[issue_reporting]
enabled = true
github_token = "ghp_xxxxxxxxxxxx"    # Fine-grained PAT, issue-creation only
institution_name = "University of Richmond"
contact_email = "hpc-team@richmond.edu"
support_email = "nomad-support@richmond.edu"

The GitHub token should be a fine-grained Personal Access Token scoped only to issue creation on the jtonini/nomad-hpc repository.

Without a Token

Without a token configured, nomad issue report and the dashboard both fall back to opening a pre-filled GitHub issue form in your browser. The --email flag provides an additional fallback for users without GitHub accounts.

Auto-Labeling

Issues submitted via the API are automatically labeled with:

  • Source: source:cli, source:dashboard, or source:console
  • Category: bug, enhancement, or question
  • Component: component:alerts, component:collectors, etc.
  • Version: v1.3.1
  • Institution: inst:university-of-richmond

GitHub Issue Templates

The repository includes structured YAML form templates for:

  • Bug Report (bug_report.yml): component, version, description, steps to reproduce, expected/actual behavior
  • Feature Request (feature_request.yml): component, problem statement, proposed solution
  • Question (question.yml): topic area, question, what you have already tried

These templates are used both by the GitHub web interface and by the pre-filled URLs generated by nomad issue report.

Noise Reduction

The system includes several mechanisms to keep the issue tracker clean:

  • Duplicate detection: searches open issues before submission
  • Structured templates: required fields produce consistent, useful reports
  • Auto-labeling: enables fast triage by component, version, and institution
  • Institutional token as quality gate: direct API submission comes from production deployments
  • Acknowledgment bot: auto-responds with triage timeline and nomad ref hints