When Does Evolver Trigger Automatic GitHub Issue Reporting for Persistent Failures?

Evolver automatically files a GitHub issue only when auto-reporting is enabled via environment variables, specific failure signals indicate a persistent problem, a configurable minimum failure streak is reached, and both cooldown and deduplication checks confirm no recent duplicate reports exist.

The EvoMap/evolver repository includes an intelligent pipeline for automatic GitHub issue reporting that identifies stubborn, recurring failures without generating noise. Understanding the precise conditions that trigger this mechanism ensures operators capture critical bugs while avoiding duplicate or premature reports.

Prerequisites: Enabling Auto-Reporting

Before any issue creation occurs, the feature must be explicitly activated and authenticated. In src/gep/issueReporter.js, the getConfig() function (lines 20‑23) validates that the EVOLVER_AUTO_ISSUE environment variable is truthy. If set to "false" or "0", the pipeline short‑circuits immediately and returns null.

Additionally, the getGithubToken function (lines 30‑32) requires a valid GitHub personal access token present in one of three environment variables: GITHUB_TOKEN, GH_TOKEN, or GITHUB_PAT. Without this token, maybeReportIssue logs an authentication failure and aborts before evaluating failure signals.

Detecting Persistent Failure Signatures

The core logic resides in the shouldReport function (lines 75‑78), which enforces strict signature requirements. An issue is only created when the signal array contains either:

• A failure_loop_detected signal, or
• Both recurring_error and high_failure_ratio signals simultaneously

These specific combinations in the signals array represent the minimal signatures that distinguish transient glitches from genuine persistent problems requiring intervention.

Streak Thresholds and Rate Limiting

Even with valid failure signals, Evolver imposes quantitative guards to prevent premature reporting. The extractStreakCount function (lines 86‑93) parses consecutive_failure_streak_<N> entries to extract the numeric streak count N. Per the shouldReport logic (line 81), this value must meet or exceed config.minStreak (default: 5, configurable via EVOLVER_ISSUE_MIN_STREAK).

The system also implements a cooldown mechanism. After creating an issue, Evolver writes a timestamp to issue_reporter_state.json in the evolution directory (managed by src/gep/paths.js). The shouldReport function (lines 83‑94) checks state.lastReportedAt against config.cooldownMs (default: 24 hours, configurable via EVOLVER_ISSUE_COOLDOWN_MS). Reports are suppressed if the elapsed time is below this threshold unless the error represents a completely new failure type.

Duplicate Detection and Deduplication

Within the cooldown window, Evolver maintains a list of recent error hashes in recentIssueKeys. The computeErrorKey(signals) function generates a deterministic hash of the current failure. If this key appears in the recent list, shouldReport returns false (lines 86‑93), preventing duplicate issues for the same recurring error during the cooldown period.

The Issue Creation Pipeline

When all validations pass, maybeReportIssue executes the findExistingIssue function (lines 75‑82) to query the GitHub API for open issues matching the generated title. If an open issue already exists, Evolver records the skip silently without creating noise.

Only after confirming no existing open issue does the pipeline invoke createGithubIssue. This function assembles the report using:

• Environment fingerprints from src/gep/envFingerprint.js (capturing Evolver version, Node version, platform)
• Sanitized logs via src/gep/sanitize.js (redacting secrets with redactString)
• The truncated session log and recent events

Practical Example: Triggering the Reporter

const { maybeReportIssue } = require('./src/gep/issueReporter');

// Simulated signal array from a failing Evolver session
const signals = [
  'failure_loop_detected',
  'recurring_error',
  'high_failure_ratio',
  'consecutive_failure_streak_7',
  'recurring_errsig(3x): timeout on /api/v1/checkout',
];

const opts = {
  signals,
  recentEvents: [],
  sessionLog: '...full log...'
};

// Requires EVOLVER_AUTO_ISSUE=true and GITHUB_TOKEN set
maybeReportIssue(opts).catch(console.error);

Under the hood, the validation logic in src/gep/issueReporter.js follows this flow:

// Inside maybeReportIssue → shouldReport
if (!config) return;                         // auto-report disabled
if (!hasFailureLoop && !hasRecurringAndHigh) return; // missing critical signals
if (streakCount && streakCount < config.minStreak) return; // streak too short
// cooldown & duplicate-hash check
if (state.lastReportedAt && elapsed < config.cooldownMs && recentKeys.includes(errorKey)) return;

Configuration Reference

Environment Variable	Purpose	Default
EVOLVER_AUTO_ISSUE	Master switch to enable automatic GitHub issue reporting	None (disabled)
EVOLVER_ISSUE_MIN_STREAK	Minimum consecutive failures required	5
EVOLVER_ISSUE_COOLDOWN_MS	Milliseconds between duplicate reports	86400000 (24h)
GITHUB_TOKEN / GH_TOKEN / GITHUB_PAT	Authentication for GitHub API	None

Summary

• Auto-reporting requires explicit opt-in via the EVOLVER_AUTO_ISSUE environment variable and a valid GitHub token from getGithubToken.
• Specific failure signatures (failure_loop_detected or the combination of recurring_error and high_failure_ratio) must be present in the signal array evaluated by shouldReport.
• Minimum streak threshold of 5 consecutive failures prevents premature reports, configurable via EVOLVER_ISSUE_MIN_STREAK.
• 24-hour cooldown and error-hash deduplication via computeErrorKey prevent duplicate issues for the same recurring problem.
• Existing issue checks via findExistingIssue ensure open tickets are not duplicated, with state tracked in issue_reporter_state.json.

Frequently Asked Questions

How do I disable automatic issue reporting in Evolver?

Set the environment variable EVOLVER_AUTO_ISSUE to "false" or "0". This causes getConfig() to return null, and the maybeReportIssue function will exit immediately without evaluating signals or creating issues, regardless of how many failures occur.

Why didn't Evolver create a GitHub issue despite multiple failures?

Check three common blockers in src/gep/issueReporter.js: First, verify that EVOLVER_AUTO_ISSUE is enabled and a token is available. Second, confirm the signals include either failure_loop_detected or both recurring_error and high_failure_ratio. Third, check if the consecutive failure streak meets minStreak (default 5) and whether the 24-hour cooldown period is active from a previous report stored in issue_reporter_state.json.

Where does Evolver store reporting state between runs?

Evolver persists the lastReportedAt timestamp and recent error keys in issue_reporter_state.json, located in the directory returned by getEvolutionDir() from src/gep/paths.js. This file enables the cooldown and deduplication logic across process restarts, ensuring the shouldReport function respects temporal boundaries even after Evolver restarts.

What happens if a GitHub issue already exists for this error?

Before creating a new issue, maybeReportIssue calls findExistingIssue (lines 75‑82) to search for open issues matching the generated title. If a match exists, Evolver skips creation silently to avoid duplicates, though it still updates internal state regarding the failure occurrence in issue_reporter_state.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}