82 lines
4.9 KiB
Markdown
82 lines
4.9 KiB
Markdown
# Updating ForgeFlow on Windows
|
|
|
|
ForgeFlow stores credentials, repository mappings, preferences, deployment profiles, diagnostics and operation history outside the source directory.
|
|
|
|
## Built-in source update
|
|
|
|
Open **Settings → ForgeFlow updates** and choose:
|
|
|
|
1. **Check now**
|
|
2. **Download update**
|
|
3. **Apply & restart**
|
|
|
|
The default update source is the configured Gitea instance, repository `Jens/ForgeFlow`, branch `main`.
|
|
|
|
The updater pins the download to the exact remote commit, checks the archive SHA-256, starts an external PowerShell helper and waits for a structured `started` marker. ForgeFlow closes only after that marker exists. The helper then:
|
|
|
|
1. waits for the old process to exit;
|
|
2. backs up the current source;
|
|
3. extracts and validates the requested semantic version;
|
|
4. mirrors the incoming source;
|
|
5. runs `npm ci --no-audit --no-fund` when the published release contains `package-lock.json`, otherwise a pinned direct-dependency `npm install`;
|
|
6. runs `npm run check`;
|
|
7. writes the successful installation result before restart;
|
|
8. launches the installed Electron executable directly;
|
|
9. persists `success`, `failed` or `rolled-back` state for the next launch.
|
|
|
|
A failed validation restores the previous source. A successful installation is not rolled back merely because automatic restart fails; start ForgeFlow manually and the persisted result is shown.
|
|
|
|
Update logs and status files are stored beneath ForgeFlow's local user-data `updates` folder and exclude the Gitea token.
|
|
|
|
## Packaged Windows updates
|
|
|
|
ForgeFlow uses authenticated Gitea release assets when running from the installer or portable executable. The updater selects the artifact that matches the current installation mode and requires its `.sha256` sidecar. From version 0.10.13 onward it also requires an Ed25519-signed release manifest. The embedded public key verifies that manifest before ForgeFlow trusts the artifact name, byte length, exact source commit or SHA-256 digest. The digest is checked again immediately before applying the update.
|
|
|
|
`Publish-ForgeFlow-Release.ps1` treats source and binaries as one release transaction. It pushes the validated source, builds the exact published commit and uploads eight required assets:
|
|
|
|
- `ForgeFlow-Setup-<version>-win-x64.exe`
|
|
- `ForgeFlow-Setup-<version>-win-x64.exe.sha256`
|
|
- `ForgeFlow-Portable-<version>-win-x64.exe`
|
|
- `ForgeFlow-Portable-<version>-win-x64.exe.sha256`
|
|
- `ForgeFlow-<version>-provenance.json`
|
|
- `ForgeFlow-<version>-sbom.cdx.json`
|
|
- `ForgeFlow-<version>-release-manifest.json`
|
|
- `ForgeFlow-<version>-release-manifest.json.sig`
|
|
|
|
Run `npm run signing:setup` once on the release workstation. The private Ed25519 key stays outside the repository in ForgeFlow's user-data folder. This independent publisher signature is free; optional Authenticode can still be added later for Windows reputation.
|
|
|
|
Use `-SkipBinaryRelease` only when intentionally publishing source without enabling packaged auto-update.
|
|
|
|
When the source was already pushed without a binary release, run the recovery publisher from Windows:
|
|
|
|
```powershell
|
|
Set-ExecutionPolicy -Scope Process Bypass
|
|
.\Publish-Missing-Binary-Release.ps1 -ExpectedVersion 0.9.1
|
|
```
|
|
|
|
The recovery script clones the current Gitea branch into a temporary directory, verifies the exact branch commit, runs the complete quality gate, builds both Windows artifacts and creates or repairs the matching Gitea release. It uses the encrypted Gitea token already stored by ForgeFlow.
|
|
|
|
Every platform build finishes by removing ForgeFlow artifacts for older versions from `dist`. The unpacked application directory and builder diagnostics are kept.
|
|
|
|
The binary publisher refuses to upload when local `HEAD` differs from the configured Gitea branch. ForgeFlow 0.8.9 and 0.9.0 queried Gitea attachment metadata as though it were the executable. Those versions require one manual 0.9.1 installer run. From 0.9.1 onward, the updater follows the release asset browser download URL and in-app updates work normally.
|
|
|
|
## Publishing a release from Downloads
|
|
|
|
Extract the complete source ZIP so this file exists:
|
|
|
|
```text
|
|
C:\Users\Jens\Downloads\ForgeFlow-<version>\ForgeFlow\package.json
|
|
```
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
cd C:\Users\Jens\Downloads\ForgeFlow-<version>\ForgeFlow
|
|
Set-ExecutionPolicy -Scope Process Bypass
|
|
.\Publish-ForgeFlow-Release.ps1
|
|
```
|
|
|
|
The script installs dependencies, runs the complete quality gate, clones `git@gitea.itworx.tech:Jens/ForgeFlow.git` into a temporary folder, mirrors the validated source without `.git`, `node_modules`, `dist` or release archives, commits it and pushes `main`. It then compares local `HEAD` with `git ls-remote`, builds the exact published checkout and uploads all binaries, checksums and signed release evidence to the matching Gitea release. Publication fails when either the source commit, publisher signature or any required asset cannot be verified.
|
|
|
|
Keep the currently installed older ForgeFlow source folder untouched until the built-in updater test is complete.
|