Update
This commit is contained in:
NuklearRabbit
@@ -0,0 +1,150 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user