Skip to main content

ADR-001 — Desktop release channel: Velopack + GitLab generic package registry

Status: ACCEPTED · Date: 2026-09-16 · Decided by: Chris (operator direction, 2026-09-15/16) Recorded by: CTO office · Supersedes: doc 07 open candidates A–D

Context

Desktop products need reliable auto-update. Deployment doc 07 left four framework candidates open. The operator has directed Velopack. The DEV-45 CTO decision (comment 12776, 2026-09-15) already fixed the CI posture this ADR builds on: CI stops at build + push to the GitLab Container Registry / package feeds; deployment and distribution never receive Kubernetes or deploy credentials from CI.

Decision

  1. MANDATORY (CTO standard, 2026-09-16): every desktop-distributed app — Windows .exe or Linux binary — ships with the Velopack auto-update lane from its first released build. Intake captures the desktop question (PM-T01 “Delivery targets”); TL-T22 carries the Desktop row; TL-SOP-40 owns execution. Exceptions only via a CTO-approved ADR naming the constraint (e.g. air-gapped fleet).
  2. Framework: Velopack (vpk CLI) for desktop auto-update packaging.
  3. Feed: GitLab generic package registry on code.naudecoreventures.com — the desktop analog of the container registry. vpk upload has no GitLab target: the CI job runs vpk pack, then pushes the release files (full, delta, portable, setup) via the generic-package API with a short-lived job token.
  4. Signing: JSign (cross-platform) via vpk --signTemplate; certificate enters the job only as a GitLab Secure File on protected refs — never a repo file, never a runner-level credential.
  5. Immutability: semantic versions are immutable. Duplicate version pushes are rejected; overwrites are forbidden in CI. One build = one version (SHA traceable through the package metadata).
  6. Channels ↔ refs: win (stable) publishes only from protected tags; win-beta publishes from development branches. Channel promotion is promote-without-rebuild (re-publish the same version, same SHA).
  7. No new runner: the Velopack lane is a job type on the existing Build Runner class (Docker executor, dotnet-SDK image for that job). Zero deploy credentials.

Consequences

  • Desktop clients pull updates directly from the registry over HTTPS; CI holds no distribution credentials beyond the short-lived job token.
  • Delta generation requires the previous release to be readable from the registry at pack time (read-scoped token).
  • Positron alternative frameworks (doc 07 candidates A–D) are closed.

Verification

  • Pilot lane acceptance recorded against doc 07’s update matrix before any product uses it (WS6 acceptance on DEV-49).