Packages & manifests

Where packages come from

Two ways to add a package to the catalogue:

• Import from the upstream catalogue — Packages → Import, search the synced upstream index, pick a version, import it.
• Author it yourself — create the package and upload manifest YAML directly, for internal-only software that has no upstream entry.

The upstream index mirrors the community winget-pkgs repository on GitHub. Set GITHUB_TOKEN (see Deployment) to raise the import rate limit against GitHub's API; CATALOG_SYNC_ENABLED keeps the searchable index itself refreshed on the interval set in CATALOG_SYNC_INTERVAL_HOURS.

Validation

Every manifest is parsed and validated against the official winget JSON schemas — versions 1.0.0 through 1.12.0 ship with the application. A manifest that doesn't validate is rejected before it's stored, with the schema violation reported back — the missing field, wrong type, or invalid enum value — so clients never receive a manifest winget itself can't read.

Overlays

The imported upstream manifest is kept exactly as received. Any edit you make — repointing an InstallerUrl, changing installer scope, correcting metadata — is stored as an overlay on top of it. You can view the diff against upstream at any time, or reset a version back to the untouched upstream manifest.

Overlay templates

Repeating the same overlay on every new release is tedious, so an overlay can be generalized into a template: write the edit once with $VERSION/$ARCH placeholders, and it's applied automatically to every future version of that package.

InstallerUrl: https://files.example.internal/$ARCH/App-$VERSION.msi

Import App 2.3.0 today, write that template once, and version 2.4.0 six months from now already has the right overlay applied when it lands.

Version history and approval

Every change to a version is recorded and diffable, and lands in the audit log with the account that made it. A version reaches clients only after a reviewer or admin approves it — the dashboard shows what's waiting. This is enforced in the API, not only reflected in the UI.

Installer storage

Two ways for a manifest to point at an installer, and you choose per package:

1. Store it on the origin. The file lives on the origin's own storage volume and is served directly from there. Its SHA-256 is recomputed on every delivery, so a file that changed unexpectedly on disk fails winget's hash check instead of silently installing.
2. Point at a URL. The manifest keeps the upstream vendor URL, or an internal one — including a location-specific share resolved through site placeholders. kvellman resolves the URL per site; it does not copy the file anywhere on your behalf.

kvellman does not mirror installers to S3, MinIO, or an SMB share on its own — if you want that shape, put the URL for it in the manifest and let the placeholder resolve it.