ForgeFlow/docs/DIAGNOSTICS.md

Diagnostics, privacy and support bundles

ForgeFlow v0.3.2 records development-oriented diagnostics locally so failures can be investigated without requesting the user's Gitea token, SSH key or server password.

Storage

Diagnostic events are stored beneath the Electron application-data directory in:

diagnostics/forgeflow-YYYY-MM-DD.jsonl

The Diagnostics page displays an aliased path such as <HOME> rather than the Windows account name. Files use restrictive permissions where the operating system supports them.

Defaults:

• enabled;
• minimum level info;
• 14-day retention;
• 8 MB maximum per log segment;
• daily filenames with numbered rotation;
• ordered asynchronous writes;
• no application crash when diagnostic storage itself fails.

These values can be changed in Diagnostics -> Recording policy.

What an event can contain

Useful fields include:

• UTC timestamp;
• level and stable event name;
• per-launch session identifier;
• operation or deployment request identifier;
• Git/Gitea operation outcome;
• HTTP status, duration and endpoint path without request headers;
• repository state and branch/SHA metadata;
• preflight result;
• sanitized exception name, code, message and stack;
• renderer crash or unhandled-rejection metadata.

ForgeFlow does not log IPC payloads, request authorization headers or Gitea response bodies merely because a request was made.

Redaction

Every event passes through a recursive sanitizer before it is written. Redaction covers:

• the currently active Gitea token;
• token, password, authorization, credential, API-key, client-secret and encrypted-token object fields, including camelCase variants;
• bearer/token/basic authorization values in strings;
• common token query parameters;
• credentials embedded in URLs;
• PEM private-key blocks;
• known Gitea/Git hosting token patterns;
• Windows, macOS and Linux home-directory paths;
• application source path aliases;
• circular data structures and oversized strings.

Credential values are replaced with [REDACTED]; user paths use aliases such as <HOME>.

Support bundle

Create diagnostic ZIP exports a local archive containing:

manifest.json
safety-audit.json
README.txt
system.json
diagnostics-status.json
configuration-sanitized.json
repositories-sanitized.json
operations-sanitized.json
preflight.json
context.json
logs/*.jsonl

The application returns the SHA-256 of the generated archive so a shared file can be identified exactly.

Excluded data

The bundle intentionally excludes:

• plaintext Gitea access tokens;
• Electron safeStorage encrypted-token blobs;
• request authorization headers;
• passwords and private keys;
• raw Gitea runner logs;
• arbitrary environment-variable dumps;
• full local file contents and Git diffs.

ForgeFlow does not automatically ingest or persist raw runner output. Job names, statuses and safe operation summaries are stored locally; full runner output remains available only in the trusted Gitea Actions interface when deeper server-side investigation is necessary.

Privacy modes

Standard

Preserves repository names and user-facing identifiers. Local home paths and credentials are still redacted. Use when the recipient already knows the project context.

Strict

Additionally replaces repository and user identifiers with deterministic SHA-256-based aliases. Related events remain correlatable without revealing the original names.

Fail-closed bundle audit

Immediately before writing the archive, ForgeFlow scans every prepared entry for:

• the known active runtime secret values;
• private-key begin markers;
• unredacted credentials embedded in HTTP(S) URLs.

The result is stored as safety-audit.json. When a finding remains, archive creation is aborted and the unsafe ZIP is not written.

Practical limitation

No generic logger can mathematically identify every unknown secret if a third- party process prints an arbitrary value without a label or recognizable format. ForgeFlow reduces this risk by not including raw runner logs, not recording IPC payloads and applying both structured and textual redaction. Always inspect a support bundle before sharing it, particularly when custom integrations have been added.

Development workflow after a failure

1. Reproduce the issue once when safe.
2. Note the approximate time and repository/environment.
3. Run the relevant preflight.
4. Export a Strict diagnostic bundle.
5. Keep the returned SHA-256 with the bug report.
6. Describe the visible action that failed.
7. Share no separate token, key or password.