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

> Evolver triggers automatic GitHub issue reporting for persistent failures when configured, a minimum failure streak is met, and no duplicate reports exist. Learn the exact conditions.

- Repository: [EvoMap/evolver](https://github.com/EvoMap/evolver)
- Tags: how-to-guide
- Published: 2026-04-17

---

**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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/issue_reporter_state.json)** in the evolution directory (managed by [`src/gep/paths.js`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/src/gep/envFingerprint.js) (capturing Evolver version, Node version, platform)
- Sanitized logs via [`src/gep/sanitize.js`](https://github.com/EvoMap/evolver/blob/main/src/gep/sanitize.js) (redacting secrets with `redactString`)
- The truncated session log and recent events

## Practical Example: Triggering the Reporter

```javascript
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`](https://github.com/EvoMap/evolver/blob/main/src/gep/issueReporter.js) follows this flow:

```javascript
// 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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/issue_reporter_state.json)**, located in the directory returned by `getEvolutionDir()` from [`src/gep/paths.js`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/issue_reporter_state.json).