Skip to main content

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

GitLab is the server-side release system. GitLab does not replace the endpoint update engine. Conversely, an updater framework does not replace GitLab’s governance, CI/CD, release notes and management UI.

3. Product project model

For every distributed product create:
Example:
The release-only project contains:
It also contains GitLab Generic Packages and GitLab Releases. It must never contain:
  • 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:
No separate Velopack server is required. Static updater metadata and packages can be served directly from GitLab over HTTPS. At larger scale:
The endpoint client should depend on a stable URL/manifest contract, not the physical disk location.

5. Generic Package naming

Use:
Examples:
Allowed naming rules should be conservative:

6. Immutable release identity

A release is identified by all of:
Example:
Once published, the bytes under that version/file name must never change. A correction receives a new version/build identity.

7. Channel model

Channels are pointers, not rebuild types.
Definitions: A newer Experimental may coexist with an older Stable:

8. Channel manifest

The supplied schema is:
Example:
The manifest is machine-readable policy. GitLab Release is the human-readable record.

9. Public versus authenticated release access

  • 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.
This avoids installing a permanent GitLab token on customer machines.

9.2 Private customer-specific release model

Where public access is unacceptable, put a small NCV update API in front:
Do not put a long-lived project/personal access token in the executable. Extracted desktop binaries can be inspected.

10. Package publication

Pipeline uses:
The script uploads each file and its .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.
After upload:
  • 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:
Fallback:
Do not use a developer’s personal token for routine release automation.

12. GitLab Release record

Each release-only project has Deploy > Releases entries such as:
GitLab Release asset links point to Generic Packages and are marked as package links.

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.
Do not copy secrets, exploit detail, customer identities or internal infrastructure into a public release.

14. Promotion workflow

Experimental

May be automatic after a protected semantic tag release succeeds, or manual by policy.

Beta

Manual job:
Preconditions:
  • Experimental verification complete;
  • QA/pilot scope identified;
  • no unresolved release-blocking defect;
  • exact SHA recorded.

Stable

Manual job:
Preconditions:
  • Beta/pilot evidence;
  • management/customer release notes approved;
  • support prepared;
  • rollback known;
  • code signatures valid;
  • rollout policy selected.
The promotion script commits only the manifest change. It never invokes Flutter, Java, installer or signing tools.

15. Rollout rings

A single Stable channel can roll out gradually:
Deterministic selection:
Requirements:
  • 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.
Controlled estate model:
Response concept:
The application then retrieves the appropriate public/signed manifest. This allows per-customer/device holdbacks without exposing private policy in public GitLab files.

17. Endpoint updater contract

The updater or helper must implement this state machine:
Required behaviours:
  • 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:
After download:
Mandatory update:
Unattended POS mode:
  • 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.
Important cautions from its own current documentation:
  • 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.
Use: first controlled POC candidate, especially for Flutter-native integration; do not authorize customer rollout solely from the package feature list.

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.
Keys must be separate from public download storage and ordinary CI jobs.

22. Rollback

Channel rollback

Point Stable back to prior known-good immutable package:
Use a promotion/rollback pipeline or revert the manifest commit. Do not delete the failed package while investigating.

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.
A binary rollback cannot undo a destructive server/database migration. Release design must maintain backward compatibility or document coordinated recovery.

Bad release procedure

  1. pause rollout at current percentage;
  2. stop further Stable checks/downloads if possible;
  3. assess whether already-installed devices must rollback or hotfix;
  4. point channel to prior version where safe;
  5. notify support/affected customers;
  6. preserve failed package/evidence;
  7. create new corrected version—never replace bytes under old version;
  8. complete incident/RCA.

23. Management visibility

23.1 Native GitLab view

For each release project, management opens:
They see:
  • 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:
Example:
Clicking a product opens:
  • current versions by platform/architecture/channel;
  • release notes;
  • Jira scope;
  • source pipeline;
  • package SHA/signature;
  • rollout percentage;
  • known issues;
  • rollback target.
The dashboard is read-only. GitLab remains the source of truth.

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.
Expire/delete:
  • superseded experimental candidates after the approved investigation window;
  • temporary job artifacts after 7–14 days;
  • abandoned unsigned candidates;
  • unreferenced container tags under policy.
Deletion requires checking that no channel, active customer hold or support plan points to the package.

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.
Migration pattern:
Preserve version, SHA, signature and audit evidence.

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