> ## Documentation Index
> Fetch the complete documentation index at: https://deployment.naudecoreventures.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Release, Package, Channel and Desktop Update Guide

> Package storage, release notes, immutable promotion, channels and endpoint updater integration

# 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

```text theme={null}
Jira
  └─ why the release exists, scope, acceptance and approval

GitLab source project
  └─ private code, tests, build pipeline and internal evidence

GitLab release-only project
  └─ public/sanitized release notes, immutable packages, releases and channels

Endpoint updater
  └─ checks, downloads, verifies, stages, restarts, installs and reports result
```

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:

```text theme={null}
ncv/products/<product>          private source project
ncv-releases/<product>          release-only project
```

Example:

```text theme={null}
ncv/products/lyt-soft
ncv-releases/lyt-soft
```

The release-only project contains:

```text theme={null}
README.md
release-notes/
  7.2.0.md
channels/
  lyt-soft/
    windows/
      x64/
        experimental.json
        beta.json
        stable.json
    linux/
      x64/
        experimental.json
        beta.json
        stable.json
```

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:

```text theme={null}
GitLab Package Registry
  └─ immutable EXE/MSIX/ZIP/AppImage/TAR/DEB/RPM packages

GitLab repositories
  └─ release notes and channel manifests

GitLab Releases
  └─ human-readable release record and package links
```

No separate Velopack server is required. Static updater metadata and packages can be served directly from GitLab over HTTPS.

At larger scale:

```text theme={null}
GitLab release pipeline
  -> S3-compatible object storage/CDN
  -> same public update hostname/contract
```

The endpoint client should depend on a stable URL/manifest contract, not the physical disk location.

## 5. Generic Package naming

Use:

```text theme={null}
package name: <product-id>
version:      <semantic-version-or-immutable-build-version>
file:         <product>-<version>-<platform>-<arch>.<extension>
```

Examples:

```text theme={null}
lyt-soft / 7.2.0+pipeline.1842 / LytSoft-7.2.0-windows-x64-Setup.exe
lyt-soft / 7.2.0+pipeline.1842 / LytSoft-7.2.0-linux-x64.tar.gz
lyt-soft / 7.2.0+pipeline.1842 / LytSoft-7.2.0-windows-x64-Setup.exe.sha256
```

Allowed naming rules should be conservative:

```text theme={null}
product: lowercase letters/numbers/dot/underscore/hyphen
version: valid controlled release identity
file: no spaces, slashes, secrets or customer names
```

## 6. Immutable release identity

A release is identified by all of:

```text theme={null}
product
version
source commit
pipeline ID
platform
architecture
artifact file
artifact size
SHA-256
code signature
```

Example:

```text theme={null}
Product:        lyt-soft
Version:        7.2.0
Build identity: 7.2.0+pipeline.1842
Commit:         8d29d733...
Platform:       windows
Architecture:   x64
File:           LytSoft-7.2.0-windows-x64-Setup.exe
SHA-256:        915f...64 hex chars
Signature:      Authenticode valid
```

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.

```text theme={null}
Experimental -> exact immutable artifact A
Beta         -> exact immutable artifact A
Stable       -> exact immutable artifact A
```

Definitions:

| Channel | Intended audience | Promotion evidence |
| - | - | - |
| Experimental | NCV engineering/internal devices | build, automated tests, signature and basic smoke test |
| Beta | QA/pilot devices/customers | Experimental evidence plus internal/pilot verification |
| Stable | normal production estate | approved release notes, UAT/pilot, rollback, support readiness |

A newer Experimental may coexist with an older Stable:

```text theme={null}
Experimental: 7.4.0+pipeline.1990
Beta:         7.3.0+pipeline.1931
Stable:       7.2.1+pipeline.1888
```

## 8. Channel manifest

The supplied schema is:

```text theme={null}
templates/channel-manifest.schema.json
```

Example:

```json theme={null}
{
  "schema_version": 1,
  "product": "lyt-soft",
  "channel": "stable",
  "version": "7.2.0",
  "build_id": "gitlab-pipeline-1842",
  "platform": "windows",
  "architecture": "x64",
  "published_at": "2026-08-11T08:00:00Z",
  "mandatory": false,
  "minimum_supported_version": "7.0.0",
  "support_deadline": null,
  "release_notes_url": "https://code.naudecoreventures.com/ncv-releases/lyt-soft/-/releases/v7.2.0",
  "rollout": {
    "percentage": 100,
    "salt": "per-release-stable-random-value"
  },
  "artifact": {
    "url": "https://code.naudecoreventures.com/api/v4/projects/123/packages/generic/lyt-soft/7.2.0/LytSoft-7.2.0-windows-x64-Setup.exe",
    "file_name": "LytSoft-7.2.0-windows-x64-Setup.exe",
    "size": 157286400,
    "sha256": "<64 lowercase hex characters>",
    "signature_url": null,
    "signature_type": "authenticode"
  }
}
```

The manifest is machine-readable policy. GitLab Release is the human-readable record.

## 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.

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:

```text theme={null}
application/device
  -> authenticates to NCV Update API
  -> receives short-lived signed/download URL and authorized channel
  -> downloads from GitLab/object storage
```

Do not put a long-lived project/personal access token in the executable. Extracted desktop binaries can be inspected.

## 10. Package publication

Pipeline uses:

```bash theme={null}
./scripts/publish-generic-package.sh \
  "$RELEASE_PROJECT_ID" \
  "$PACKAGE_NAME" \
  "$PACKAGE_VERSION" \
  .release/<files...>
```

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:

```text theme={null}
source project CI_JOB_TOKEN
  -> release project job-token allowlist
  -> package/release API
```

Fallback:

```text theme={null}
release project access token
  scopes: minimum required API/package/repository
  expiry: mandatory
  stored: protected masked variable
```

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:

```text theme={null}
Lyt-Soft 7.2.0
Status at publication: Experimental
Build identity: 7.2.0+pipeline.1842
Source: private source project/tag/pipeline reference

Management summary
- Improved Smart Invoice retry handling.
- Reduced receipt-printing failures.

Jira
- SYN-264
- SYN-281

Verification
- Unit tests passed.
- Integration tests passed.
- Windows signature verified.
- Pilot record linked.

Packages
- Windows x64 Setup.exe
- Linux x64 tar.gz
- Checksums/signatures

Rollback
- Previous known-good Stable: 7.1.4
```

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.

```text theme={null}
Build/test/sign/package
  -> publish immutable package
  -> create GitLab Release
  -> set Experimental manifest
```

### Beta

Manual job:

```text theme={null}
[ Promote to Beta ]
```

Preconditions:

* Experimental verification complete;
* QA/pilot scope identified;
* no unresolved release-blocking defect;
* exact SHA recorded.

### Stable

Manual job:

```text theme={null}
[ Promote to Stable ]
```

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:

```text theme={null}
5% -> 20% -> 50% -> 100%
```

Deterministic selection:

```text theme={null}
bucket = hash(device_id + release_rollout_salt) mod 100
eligible when bucket < percentage
```

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:

```text theme={null}
GET /api/v1/update-policy?product=lyt-soft&device=<id>
```

Response concept:

```json theme={null}
{
  "channel": "beta",
  "rollout_override": null,
  "hold_version": null
}
```

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:

```text theme={null}
Idle
  -> Checking
  -> No update
  -> Update available
  -> Downloading
  -> Verifying
  -> Ready to install
  -> Waiting for restart/idle window
  -> Installing
  -> Restarting
  -> Verifying new launch
  -> Success
or
  -> Failed/recovered/rolled back
```

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:

```text theme={null}
Lyt-Soft 7.2.0 is available
- Faster Smart Invoice retries
- Receipt printing fixes

[Download] [Later] [View release notes]
```

After download:

```text theme={null}
Update 7.2.0 is ready
[Restart now] [Later]
```

Mandatory update:

```text theme={null}
An update is required to continue
Save your work, then restart to install 7.2.0.
[Save first] [Restart and 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:

| Test | Windows | Linux | macOS |
| - | -: | -: | -: |
| First install | required | required | required if distributed |
| Optional update | required | required | required |
| Mandatory update | required | required | required |
| Restart now/later | required | required | required |
| App running/locked files | required | required | required |
| Power/network interruption | required | required | required |
| Corrupt/truncated package | required | required | required |
| Wrong SHA | required | required | required |
| Invalid metadata signature | required | required | required |
| Invalid platform signature | required | required | required |
| Disk full | required | required | required |
| Antivirus/EDR | required | n/a/as applicable | Gatekeeper |
| Non-admin user | required | required | required |
| Upgrade from oldest supported | required | required | required |
| Rollback/recovery | required | required | required |
| Unicode/long paths | required | required | required |
| Multiple app instances | required | required | required |
| Active POS transaction | required | required | as applicable |
| Telemetry/status reporting | required | required | required |

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:

```text theme={null}
Stable 7.2.0 -> Stable 7.1.4
```

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:

```text theme={null}
Deploy > Releases
Deploy > Package Registry
Repository > channels/
```

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:

```text theme={null}
GitLab Group Releases API
+ channel manifests
```

Example:

```text theme={null}
PRODUCT             STABLE        BETA           EXPERIMENTAL
Lyt-Soft             7.2.0         7.3.0-b2       7.4.0-e6
Kazang POS           4.8.1         4.9.0-b1       5.0.0-e3
Smart Invoice API    3.12.4        3.13.0-b2      3.14.0-e1
```

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:

```text theme={null}
GitLab CI publishes immutable package
  -> object storage
  -> CDN/custom updates hostname
  -> channel manifest points to new URL
```

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

* GitLab Generic Packages: [https://docs.gitlab.com/user/packages/generic\_packages/](https://docs.gitlab.com/user/packages/generic_packages/)
* GitLab Package Registry: [https://docs.gitlab.com/user/packages/package\_registry/](https://docs.gitlab.com/user/packages/package_registry/)
* GitLab Releases: [https://docs.gitlab.com/user/project/releases/](https://docs.gitlab.com/user/project/releases/)
* GitLab Release links API: [https://docs.gitlab.com/api/releases/links/](https://docs.gitlab.com/api/releases/links/)
* GitLab Group Releases API: [https://docs.gitlab.com/api/group\_releases/](https://docs.gitlab.com/api/group_releases/)
* `desktop_updater`: [https://pub.dev/packages/desktop\_updater](https://pub.dev/packages/desktop_updater)
* `auto_updater`: [https://pub.dev/packages/auto\_updater](https://pub.dev/packages/auto_updater)
* `velopack_flutter`: [https://pub.dev/packages/velopack\_flutter](https://pub.dev/packages/velopack_flutter)
* Velopack core: [https://docs.velopack.io/](https://docs.velopack.io/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.