151 lines
4.5 KiB
Markdown
151 lines
4.5 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|