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

# Adr 001 velopack release channel

# 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

0. **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).
1. **Framework: Velopack** (`vpk` CLI) for desktop auto-update packaging.
2. **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.
3. **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.
4. **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).
5. **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).
6. **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).


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