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