70 lines
4.3 KiB
Markdown
70 lines
4.3 KiB
Markdown
# Updating ForgeFlow on Windows
|
|
|
|
ForgeFlow stores credentials, repository mappings, preferences, deployment profiles, diagnostics and operation history outside the source directory.
|
|
|
|
## Source checkouts
|
|
|
|
Integrated source replacement is disabled until source archives are covered by the same independent publisher signature as packaged releases. A server-provided commit SHA and a checksum calculated from the downloaded archive do not independently authenticate its publisher, while dependency installation can execute package lifecycle scripts.
|
|
|
|
Update a source checkout through Git instead:
|
|
|
|
1. fetch the configured upstream;
|
|
2. review the exact commit and release notes;
|
|
3. switch to the intended release commit or tag;
|
|
4. run `npm ci --ignore-scripts` and review the dependency lifecycle allowlist;
|
|
5. run `npm run check` before starting ForgeFlow.
|
|
|
|
The in-app updater remains available for signed packaged Windows releases.
|
|
|
|
## 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\your-name\Downloads\ForgeFlow-<version>\ForgeFlow\package.json
|
|
```
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
cd C:\Users\your-name\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.
|