# 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: ```text 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. ![ForgeFlow overview](docs/screenshots/overview.png) ## 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/`; - 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](docs/SSH_UNRAID_DEPLOYMENT.md) and the [LumaOps audit](docs/LUMAOPS_SERVER_AUDIT.md). ### 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](START_HERE.md). The full installation and acceptance procedure is in [docs/SETUP_GUIDE.md](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](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](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: ```powershell 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: ```bash 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](START_HERE.md) 2. [docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md) 3. [docs/UPDATING.md](docs/UPDATING.md) 4. [docs/DEPLOYMENT_SETUP.md](docs/DEPLOYMENT_SETUP.md) 5. [docs/STATUS_ENDPOINT.md](docs/STATUS_ENDPOINT.md) 6. [docs/DIAGNOSTICS.md](docs/DIAGNOSTICS.md) The recommended first test uses a non-critical staging deployment and validates: ```text 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: ```powershell 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](docs/UPDATING.md). ## Browser demo The standalone visual demo requires no Gitea connection or credentials: ```bash 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 ```bash 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](docs/TEST_MATRIX.md). ## Development packages ```bash npm run dist:win npm run dist:linux npm run dist:mac ``` Windows users can run: ```powershell .\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: ```json { "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 ```text 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](LICENSE).