Release, Package, Channel and Desktop Update Guide
1. Purpose
This guide defines how NCV management and engineering will:- see all product versions and release notes;
- store Windows/Linux/macOS packages;
- distinguish Experimental, Beta and Stable;
- promote the same tested binary without rebuilding;
- make packages available to installed customer applications;
- support Download, Restart now, Later, mandatory updates and rollback;
- scale release downloads without adding JFrog, Gitea or a mandatory Velopack server.
2. Ownership boundary
3. Product project model
For every distributed product create:- proprietary source code;
- customer databases/logs;
- internal credentials;
- CI signing keys;
- unsanitized support data;
- debug symbols that expose sensitive implementation unless access is intentionally restricted.
4. Storage model
Initial storage is on the NCV GitLab RAID-1 server:5. Generic Package naming
Use:6. Immutable release identity
A release is identified by all of:7. Channel model
Channels are pointers, not rebuild types.
A newer Experimental may coexist with an older Stable:
8. Channel manifest
The supplied schema is:9. Public versus authenticated release access
9.1 Recommended initial model
- Source project: Private.
- Release-only project: Public or explicitly configured for anonymous package pull.
- Release-only repository contains sanitized data only.
- Package downloads use project-level Generic Package endpoints.
- Channel manifest uses a public raw-file or dedicated release API URL.
9.2 Private customer-specific release model
Where public access is unacceptable, put a small NCV update API in front:10. Package publication
Pipeline uses:.sha256 companion.
Before upload:
- native build completed;
- package/installer completed;
- platform signature applied;
- signature verification passed;
- SHA-256 calculated;
- version/file name validated;
- release notes present.
- download the package into a clean verification job;
- compare SHA-256;
- verify signature again;
- create/update GitLab Release asset link.
11. Cross-project publication authentication
Preferred:12. GitLab Release record
Each release-only project has Deploy > Releases entries such as:13. Internal versus customer release notes
Maintain two levels when required:Internal source-project evidence
May include:- pipeline/job links;
- technical migration detail;
- internal Jira references;
- known operational risks;
- support diagnostics.
Public release-project notes
Contain:- customer-visible outcome;
- fixes/features;
- support/compatibility statement;
- known limitations safe to disclose;
- download/package links.
14. Promotion workflow
Experimental
May be automatic after a protected semantic tag release succeeds, or manual by policy.Beta
Manual job:- Experimental verification complete;
- QA/pilot scope identified;
- no unresolved release-blocking defect;
- exact SHA recorded.
Stable
Manual job:- Beta/pilot evidence;
- management/customer release notes approved;
- support prepared;
- rollback known;
- code signatures valid;
- rollout policy selected.
15. Rollout rings
A single Stable channel can roll out gradually:- use a stable non-secret device identifier;
- never expose customer data in the public manifest;
- preserve the same salt while increasing percentage for the same release;
- generate a new random salt for a different release;
- do not use
random()on every check; - record rollout changes in Git history/pipeline audit.
16. Device/channel assignment
Small initial model:- build default channel into configuration;
- internal builds use Experimental;
- pilot builds/devices use Beta;
- customers use Stable.
17. Endpoint updater contract
The updater or helper must implement this state machine:- compare semantic versions safely;
- prevent downgrade unless rollback is explicitly authorized;
- validate product/platform/architecture identity;
- require HTTPS;
- verify metadata authenticity where supported;
- verify exact byte length and SHA-256;
- verify Authenticode/Apple/Minisign trust;
- download atomically to temporary storage;
- never overwrite the running executable directly from the app process;
- preserve app data/config;
- handle locked files;
- coordinate process exit;
- support restart now/later;
- record pending-install marker;
- verify new version on next launch;
- recover from power loss/interrupted download;
- report update status without exposing credentials.
18. User interface behaviour
Optional update:- download in background;
- wait for no active transaction/user activity;
- obey maintenance window;
- warn/count down;
- install/restart;
- report success;
- never interrupt an active transaction merely because an update exists.
19. Updater framework decision for Flutter desktop
There is no need to lock GitLab architecture to one framework. The release contract remains updater-agnostic until the production proof of concept passes.Candidate A: desktop_updater
Current package line as checked on 2026-08-11: 3.1.x.
Strengths described by its publisher:
- Flutter Windows/macOS/Linux API;
- signed update index and signed release descriptor;
- artifact length/SHA-256 verification;
- release CLI;
- built-in UI;
- optional/mandatory/support-policy modes;
- release notes;
- restart/recovery flow;
- Windows Inno and macOS signing/notarization paths.
- it is changing rapidly;
- Linux direct-ZIP support is described as preview/candidate-only, not production-ready;
- some native Windows/Linux production evidence remains separately gated;
- NCV still owns platform trust, production tests and key custody.
Candidate B: auto_updater
Uses Sparkle/WinSparkle and supports Windows/macOS, but not Linux. It may be considered when those two platforms are sufficient or Linux uses a separate native packaging route.
Candidate C: velopack_flutter
Current package line as checked on 2026-08-11: 0.3.x.
It is a third-party Flutter/Rust bridge to Velopack. It exposes Velopack concepts, but is new and must be treated as an integration candidate, not equivalent to a first-party mature Flutter SDK. Linux and API completeness require specific verification.
Candidate D: NCV-maintained native helper/adapter
A small Rust/C++/.NET helper can consume the NCV manifest and own atomic replacement/restart. This provides the most control and Linux flexibility but creates long-term engineering/security ownership.20. Updater POC acceptance matrix
Test in clean VMs/real targets:
No updater receives Stable approval until every applicable row has recorded evidence.
21. Metadata signing versus platform signing
Both are required where available:Metadata/release-feed signing
Proves that the update policy and artifact pointer came from NCV. A SHA in an unsigned manifest protects against accidental corruption but not a compromised download host that can replace both file and hash.Platform artifact signing
- Windows: Authenticode verifies publisher/integrity and improves trust/reputation.
- macOS: Developer ID/App Store signing, hardened runtime, notarization/stapling as applicable.
- Linux: use a signed descriptor/Minisign or native repository/package signatures according to delivery method.
22. Rollback
Channel rollback
Point Stable back to prior known-good immutable package:Client rollback
Whether the endpoint can automatically revert depends on the chosen updater. NCV acceptance requires either:- automatic restore of prior executable bundle; or
- reliable reinstall of prior package through the helper/installer;
- plus clear handling of incompatible data/schema migrations.
Bad release procedure
- pause rollout at current percentage;
- stop further Stable checks/downloads if possible;
- assess whether already-installed devices must rollback or hotfix;
- point channel to prior version where safe;
- notify support/affected customers;
- preserve failed package/evidence;
- create new corrected version—never replace bytes under old version;
- complete incident/RCA.
23. Management visibility
23.1 Native GitLab view
For each release project, management opens:- release versions and dates;
- release notes;
- package links;
- evidence links;
- who/what pipeline released;
- current channel files and history.
23.2 Portfolio view
Phase 2 may add a read-only release dashboard using:- current versions by platform/architecture/channel;
- release notes;
- Jira scope;
- source pipeline;
- package SHA/signature;
- rollout percentage;
- known issues;
- rollback target.
24. Release retention
Keep:- current Stable;
- prior known-good Stable;
- every version still supported in the field;
- versions required for regulated/customer evidence;
- active Beta/Experimental under investigation;
- installers needed for recovery.
- superseded experimental candidates after the approved investigation window;
- temporary job artifacts after 7–14 days;
- abandoned unsigned candidates;
- unreferenced container tags under policy.
25. Scale and CDN transition
Move public packages off local GitLab serving when one or more occur:- release downloads materially affect GitLab response time;
- one release creates large multi-terabyte egress;
- root filesystem growth threatens 70/80% thresholds;
- geographic download performance is poor;
- signed short-lived URLs/per-device authorization are required.
26. Release implementation checklist
- Private source project exists.
- Release-only project exists and contains no source/secrets.
- Generic Package Registry enabled.
- Public/anonymous download policy explicitly chosen.
- Package naming/version rules documented.
- Release notes template installed.
- Channel schema committed.
- Channel folder/branch protected.
- Cross-project job-token access configured or narrow token created.
- Package publication tested.
- Download/SHA verification tested.
- Detached metadata/release-feed signing and client verification are implemented before customer auto-update go-live.
- Metadata signing private key is kept off public storage and ordinary merge-request runners.
- GitLab Release asset link tested.
- Experimental/Beta/Stable promotion tested with same SHA.
- Rollout salt preservation tested.
- Channel rollback tested.
- Updater POC acceptance completed.
- Windows/macOS/Linux signatures verified.
- No client-side GitLab permanent token exists.
- Management can see all release information.
- Support has update-failure procedure.
27. Official references
- GitLab Generic Packages: https://docs.gitlab.com/user/packages/generic_packages/
- GitLab Package Registry: https://docs.gitlab.com/user/packages/package_registry/
- GitLab Releases: https://docs.gitlab.com/user/project/releases/
- GitLab Release links API: https://docs.gitlab.com/api/releases/links/
- GitLab Group Releases API: https://docs.gitlab.com/api/group_releases/
desktop_updater: https://pub.dev/packages/desktop_updaterauto_updater: https://pub.dev/packages/auto_updatervelopack_flutter: https://pub.dev/packages/velopack_flutter- Velopack core: https://docs.velopack.io/