ForgeFlow/README.md

ForgeFlow

ForgeFlow is a desktop release cockpit that turns the complete path from a local code change to a verified server deployment into one guided flow:

Local working tree -> Gitea repository -> exact deployed server version

It is not an IDE and it does not replace Gitea Actions. ForgeFlow coordinates local Git, a private Gitea instance and fixed deployment workflows while keeping credentials on the user's own computer.

Current status: v0.4.2 integrated desktop test release

v0.4.2 workflow and deployment expansion

• large changed-file sets scroll independently;
• commit actions explain the missing prerequisite and auto-stage selected files;
• ITWorx.tech branding is integrated;
• the app can update itself from Jens/ForgeFlow in the configured Gitea instance;
• SSH / Unraid servers can be configured once with pinned host identity;
• exact commits can be deployed to /mnt/user/appdata/<project>;
• existing Compose definitions and untracked runtime data are preserved;
• a basic Unraid-compatible Compose file can be generated for simple new projects.

Read SSH / Unraid deployment and the LumaOps audit.

v0.4.2 automatic clone workflow

Clone from Gitea now uses the first configured project root and creates the repository-named subfolder automatically. The native folder picker is reserved for the explicit Choose another location action. Existing matching checkouts are linked; conflicting folders are never overwritten.

The Windows environment doctor retains the v0.3.1 npm command-shim correction.

Version 0.3.2 is designed so the user does not need to give a developer any Gitea token, SSH key, server password or other credential. The application now includes:

• a five-step setup wizard;
• computer, Gitea and deployment preflights;
• protected local token entry;
• structured local diagnostics with aggressive secret redaction;
• standard and strict privacy support bundles;
• fail-closed bundle safety auditing;
• request IDs that correlate desktop, Actions and server events;
• root-owned allowlisted server target configuration;
• a complete setup guide from fresh checkout to first rollback test.

Start with START_HERE.md. The full installation and acceptance procedure is in docs/SETUP_GUIDE.md.

What ForgeFlow can do

Repository workflow

• Connect to a private Gitea instance and validate the account locally.
• Discover Git working trees beneath one or more project roots.
• Use the first project root as the automatic clone destination.
• Match local folders to Gitea repositories using normalized origin identity.
• Link existing repositories or clone directly into the default project root.
• Read real Git status through porcelain v2 and NUL-delimited output.
• Inspect diffs and select files.
• Stage and unstage changes.
• Commit locally or commit and push in one action.
• Push, fetch and use fast-forward-only pull.
• Review recent history.
• Create, switch and publish branches.
• Stash, list and restore local work.
• Mark favorites and prioritize repositories requiring attention.
• Refresh repository state automatically while the application is open.

Deployment workflow

• Configure multiple environments per repository.
• Bind each environment to a fixed branch and fixed Gitea Actions workflows.
• Run a visible deployment preflight before confirmation.
• Re-run mandatory checks in the privileged backend before dispatch.
• Verify a clean tree, correct branch, upstream and ahead/behind state.
• Verify that the exact full SHA exists on the allowed remote branch.
• Verify local and remote workflow files and Gitea Actions availability.
• Dispatch a unique request ID with the exact commit SHA.
• Poll Gitea Actions runs and jobs.
• Correlate the workflow with the server status endpoint.
• Verify that the requested SHA is actually live.
• Run an independent application healthcheck.
• Roll back through a separate fixed workflow to the previous exact SHA.
• Preserve a bounded local operation history.

Safe diagnostics

ForgeFlow stores structured JSONL diagnostics in the application-data folder. They are intended to make development and troubleshooting possible without requesting credentials.

The logger records useful operational facts such as:

• timestamps, stable event names and duration;
• Git action outcomes and repository state;
• Gitea endpoint paths and HTTP status, but not authorization headers;
• deployment request IDs, workflow stages and health states;
• preflight results;
• sanitized error names, codes, messages and stacks.

It excludes or redacts:

• Gitea tokens and encrypted token blobs;
• passwords, authorization headers and credential-bearing URLs;
• private keys and common token patterns;
• arbitrary environment-variable dumps;
• local source contents and Git diffs;
• raw Gitea runner logs from support bundles;
• user-home paths.

Support bundles are audited before writing. If a known runtime secret, private key marker or URL credential remains, ForgeFlow aborts the export instead of creating the ZIP. Strict privacy mode also hashes repository and user identifiers while keeping related events correlatable.

Read docs/DIAGNOSTICS.md for the exact policy and its limitations.

Security model

• Electron main/preload/renderer separation.
• Sandboxed renderer with context isolation and no direct Node.js access.
• Narrow, frozen preload API.
• Trusted renderer-origin checks on privileged IPC.
• No arbitrary shell command field in the interface.
• Gitea token stored using Electron safeStorage when available.
• Blank token updates preserve the existing protected token.
• Atomic local configuration writes and schema migration.
• Repository-relative path validation for file actions.
• Supported-protocol and credential-in-URL validation.
• Fixed workflow, branch and environment allowlists.
• Root-owned server target configuration.
• Exact-SHA deployment and rollback.
• Server-side locking, health validation and status records.
• Local diagnostic retention, rotation and clear/export controls.

More detail is available in docs/SECURITY.md.

Prerequisites

For a Windows source setup:

• Windows 10 or 11;
• Node.js 22 or newer;
• npm;
• Git on PATH;
• a normal signed-in desktop session;
• access to your own Gitea instance.

For deployment:

• Gitea Actions enabled;
• a trusted Gitea runner with an environment-specific label;
• a Linux target server reachable by that runner;
• Git, Docker Compose, curl and flock on the target server;
• an existing non-interactive server checkout of the application.

Fastest Windows start

Extract the release, open PowerShell in the folder and run:

Set-ExecutionPolicy -Scope Process Bypass
.\setup-windows.ps1

The script:

1. checks Node.js, npm and Git;
2. installs the exact dependency versions from package-lock.json when present;
3. runs the environment doctor;
4. validates the source tree;
5. runs all automated tests;
6. starts ForgeFlow.

No Gitea or server credential is requested by the PowerShell script. Tokens are entered later in the local desktop wizard.

Manual equivalent:

npm install --no-audit --no-fund
npm run doctor
npm run check
npm start

Setup and first acceptance test

Follow these documents in order:

1. START_HERE.md
2. docs/SETUP_GUIDE.md
3. docs/UPDATING.md
4. docs/DEPLOYMENT_SETUP.md
5. docs/STATUS_ENDPOINT.md
6. docs/DIAGNOSTICS.md

The recommended first test uses a non-critical staging deployment and validates:

preflight -> commit -> push -> deploy -> Actions -> server SHA -> healthcheck -> rollback

Updating an existing source installation

Close ForgeFlow, copy the v0.4.2 update overlay over the existing source folder and run:

Set-ExecutionPolicy -Scope Process Bypass
.\update-windows.ps1

Application configuration and protected credentials are stored outside the source folder and are not reset. See docs/UPDATING.md.

Browser demo

The standalone visual demo requires no Gitea connection or credentials:

npm run demo

Open the printed local URL. The demo uses src/renderer/mock-bridge.js; the packaged desktop application uses the privileged preload.cjs bridge.

Quality checks

npm run verify
npm test
npm run check
npm run doctor -- --json

Version 0.3.2 contains 45 automated tests. Two integration suites create real temporary bare Git remotes and exercise commit, push, branch, stash and exact remote-SHA behavior. Detailed coverage is listed in docs/TEST_MATRIX.md.

Development packages

npm run dist:win
npm run dist:linux
npm run dist:mac

Windows users can run:

.\build-windows.ps1

These commands create unsigned development packages. Public distribution still requires platform code signing and platform-specific release acceptance.

Server-side deployment model

ForgeFlow never sends a free-form deployment command. It dispatches a fixed workflow with controlled inputs:

{
  "ref": "main",
  "inputs": {
    "environment": "staging",
    "commit_sha": "0123456789abcdef0123456789abcdef01234567",
    "request_id": "generated-by-forgeflow"
  }
}

The workflow calls a root-owned allowlisted server script. Deployment targets are defined in /etc/forgeflow/targets.conf, not supplied by the desktop app. The server checks repository, environment, paths, branch, exact remote ancestry, locking, Docker Compose result and health before it updates the public status JSON.

Project structure

main.cjs                         Electron lifecycle and service composition
preload.cjs                      Whitelisted renderer API and event bridge
src/main/config-store.cjs        State, migration and protected token storage
src/main/git-service.cjs         Real Git CLI adapter
src/main/gitea-service.cjs       Gitea REST and Actions adapter
src/main/repository-service.cjs  Discovery, matching and repository aggregation
src/main/repository-monitor.cjs  Background working-tree awareness
src/main/deployment-service.cjs  Dispatch, polling, SHA checks and rollback
src/main/preflight-service.cjs   Computer and deployment readiness checks
src/main/diagnostics-service.cjs Safe JSONL diagnostics and support bundles
src/main/log-redaction.cjs       Recursive secret and privacy sanitizer
src/main/ipc.cjs                 Validated privileged operation boundary
src/shared/clone-target.cjs      Safe automatic clone target planning
src/shared/zip-writer.cjs        Dependency-free diagnostic ZIP writer
src/renderer/                    Desktop UI and browser demo
examples/gitea-actions/          Fixed deploy and rollback workflow templates
examples/server/                 Allowlisted Linux deployment implementation
tests/                           Unit and real Git integration tests
docs/                            Setup, diagnostics, security and architecture

Scope and remaining acceptance

The v0.4.2 logic is prepared for self-service configuration and testing, but no source release can prove compatibility with a private environment it has never connected to. The remaining acceptance is deliberately local to the user:

• validate the exact Gitea version and Actions API;
• validate the runner label and runner permissions;
• adapt one target line in the root-owned server configuration;
• verify the application-specific Docker Compose and health endpoint;
• execute the documented staging deployment and rollback test;
• export a Strict support bundle if a failure occurs.

No credential needs to be shared for that process.

License

MIT. See LICENSE.