85 lines
5.2 KiB
Markdown
85 lines
5.2 KiB
Markdown
# ForgeFlow
|
|
|
|
<p align="center"><strong>From a local change to a verified server revision.</strong></p>
|
|
<p align="center"><a href="#see-the-workflow">Product tour</a> · <a href="#key-capabilities">Features</a> · <a href="#get-started">Get started</a> · <a href="#deployment-model">Deployment model</a></p>
|
|
|
|
ForgeFlow is a Windows desktop application for teams that use Git, Gitea and self-hosted Docker or Unraid servers. It brings local changes, remote commits and the exact revision running on a server into one workspace, then guides review, commit, push, deployment and verification.
|
|
|
|
**Downloads:** Existing signed Windows releases remain at [the legacy ForgeFlow release page](https://gitea.itworx.tech/Jens/ForgeFlow/releases/latest) during the public-repository transition. The [curated public source](https://gitea.itworx.tech/Jens/ForgeFlow-Public) is separate; it will become the release destination only after signing and update compatibility are verified.
|
|
|
|
## See the workflow
|
|
|
|
|
|
|
|
| Review local work | Reconcile deployments |
|
|
| --- | --- |
|
|
|  |  |
|
|
|
|
*The captures use example repositories and demo state; they are not a live infrastructure dashboard.*
|
|
|
|
## Key capabilities
|
|
|
|
| Area | What ForgeFlow helps you do |
|
|
| --- | --- |
|
|
| Action queue | See which repositories need review, a push, deployment or health attention. |
|
|
| Git review | Inspect diffs, stage files or hunks, commit, push and recover from common sync problems. |
|
|
| Gitea awareness | Compare local and remote revisions, review branch protection and open a pull request. |
|
|
| Server inventory | Discover Docker, Compose and DockerMan workloads and link them only when repository evidence matches. |
|
|
| Exact-commit deployment | Dispatch a reviewed revision and compare the full local, Gitea and live commit SHAs. |
|
|
| Git Validator | Inspect repository identity, protection, documentation, secret hygiene and oversized files. |
|
|
| Diagnostics | Keep configuration local and redact sensitive values in support exports. |
|
|
|
|
ForgeFlow distinguishes a matching commit from a healthy deployment. It keeps incomplete evidence visible instead of claiming that a server is current when its live SHA is unknown.
|
|
|
|
## Get started
|
|
|
|
### Install the Windows app
|
|
|
|
1. Download an installer or portable executable from the [published release page](https://gitea.itworx.tech/Jens/ForgeFlow/releases/latest).
|
|
2. Launch ForgeFlow and complete the setup wizard.
|
|
3. Add your Gitea URL, a token with the required repository permissions, and the local folders to scan.
|
|
4. Optionally add a Docker or Unraid host, then use **Scan servers** to review detected workloads.
|
|
|
|
The packaged updater checks a release against the exact remote commit, its SHA-256 checksum and the embedded Ed25519 publisher key. Existing installations continue to use the legacy release endpoint until the migration is qualified.
|
|
|
|
### Explore with example data
|
|
|
|
Requirements: Node.js 22, npm and Git.
|
|
|
|
```powershell
|
|
npm ci
|
|
npm run demo
|
|
```
|
|
|
|
Open <http://127.0.0.1:41737>. The browser demo uses example repositories and server state; it does not mutate your Git checkouts or deploy a workload. To run the full desktop application from source, use `npm start` after `npm ci`.
|
|
|
|
## Deployment model
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Desktop[ForgeFlow desktop] --> Git[Local Git worktree]
|
|
Desktop --> Gitea[Gitea repository and Actions]
|
|
Gitea --> Runner[Approved deployment workflow]
|
|
Runner --> Server[Docker or Unraid host]
|
|
Server --> Evidence[Live revision and health evidence]
|
|
Evidence --> Desktop
|
|
```
|
|
|
|
For server-pull deployments, the host fetches the **exact approved commit** with a repository-scoped read-only deploy key and a pinned SSH host key. ForgeFlow validates Compose configuration and checks post-deployment health. A direct copy remains an explicit fallback, never an implicit replacement for the verified pull path.
|
|
|
|
Start with the [setup guide](docs/SETUP_GUIDE.md), [deployment setup](docs/DEPLOYMENT_SETUP.md), [SSH and Unraid deployment](docs/SSH_UNRAID_DEPLOYMENT.md), and [migration example](docs/DEPLOYMENT_MIGRATION_EXAMPLE.md). Keep runtime data and credentials outside Git. The [diagnostics guide](docs/DIAGNOSTICS.md) explains safe support bundles.
|
|
|
|
## Develop and verify
|
|
|
|
```powershell
|
|
npm ci
|
|
npm run check
|
|
npm run acceptance
|
|
```
|
|
|
|
`npm run check` performs source verification, linting and tests. Browser acceptance and Windows packaging are separate release gates. `src/main/` contains desktop services and IPC, `src/renderer/` contains the UI, `src/shared/` holds shared policies, `scripts/` contains validation and release tooling, and `tests/` covers core behavior.
|
|
|
|
This repository remains the download and update endpoint for existing Windows installations during the migration. The curated, content-only source is published at [ForgeFlow-Public](https://gitea.itworx.tech/Jens/ForgeFlow-Public). New binary publication there remains manual until signing and updater compatibility are verified.
|
|
|
|
ForgeFlow is available under the [MIT License](LICENSE). Report security issues through [SECURITY.md](SECURITY.md).
|