358 lines
13 KiB
Markdown
358 lines
13 KiB
Markdown
# ForgeFlow
|
|
|
|
## Publish this release to the built-in updater repository
|
|
|
|
Extract the full source ZIP to a folder under Downloads and run:
|
|
|
|
```powershell
|
|
Set-ExecutionPolicy -Scope Process Bypass
|
|
.\Publish-ForgeFlow-Release.ps1
|
|
```
|
|
|
|
The script runs the complete quality gate, clones `git@gitea.itworx.tech:Jens/ForgeFlow.git` into a temporary folder, mirrors the verified source without `.git`, `node_modules` or release ZIPs, commits it on `main` and pushes it. A running older ForgeFlow source installation can then update through **Settings → Updates**.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
## Current status: v0.6.0 self-healing Git and Unraid operations
|
|
|
|
### Git recovery and repository truth
|
|
|
|
- serializes every mutating Git action per repository;
|
|
- waits through a short grace period and automatically retries after safely removing a proven stale lock;
|
|
- detects `HEAD.lock`, `index.lock`, ref locks and worktree locks while skipping object storage;
|
|
- provides repository-specific actions for fetch, fast-forward, push and backed-up divergence reset;
|
|
- creates a `forgeflow/backup-*` safety branch before any reset to upstream.
|
|
|
|
### SSH / Unraid and DockerMan
|
|
|
|
- reconciles interrupted deployments against the live SHA, container state and health;
|
|
- applies DockerMan WebUI, icon and shell labels through an override and writes a persistent XML template fallback;
|
|
- keeps the visible container name such as `Portfolio` while enforcing lowercase internal service/image identities;
|
|
- includes a built-in high-contrast ITWorx icon, local PNG upload, persistent DockerMan image storage and cache refresh;
|
|
- exposes **Open Web UI**, **Repair DockerMan integration** and **Reconcile** directly on deployment cards.
|
|
|
|
### Update reliability
|
|
|
|
- confirms the external updater handshake before closing ForgeFlow;
|
|
- rejects malformed PowerShell update helpers before publication;
|
|
- validates the replacement source and keeps rollback/success status for the next launch;
|
|
- verifies that Gitea reports the exact published release commit.
|
|
|
|
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).
|