Winget Registration

Goal

Users can winget install / winget upgrade your app.

Why

Distribution; Automatic updates.

Prerequisites

  • Public, versioned, HTTPS installer or portable archive URL (GitHub Releases work well; no login wall)

  • Stable PackageIdentifier in the form Publisher.App (usually GitHubUser.AppName)

  • Artifact that winget can install: MSI/EXE installer, MSIX, or a zip with a nested portable .exe

  • Preferably Authenticode-signed (unsigned packages still get accepted, but expect extra review)

Portable zips are valid for winget (InstallerType: zip + nested portable). Prefer a real installer when you can—see installer packaging.

One-time publisher setup

  1. Create a classic GitHub Personal Access Token with the public_repo scope.

    Fine-grained tokens do not work with the common publish bots.

  2. Optionally store it locally for wingetcreate:

    winget install Microsoft.WingetCreate
wingetcreate token

  3. In the app repo: Settings → Secrets and variables → Actions → New repository secret

    Name: WINGET_TOKEN
    Value: the classic PAT

  4. Fork microsoft/winget-pkgs once under the same GitHub account that owns the PAT (bots reuse that fork).

First submission (manual)

winget-releaser / komac update only update packages that already exist in microsoft/winget-pkgs. Bootstrap the first version yourself:

Option A — WingetCreate (Windows)

wingetcreate new https://github.com/OWNER/REPO/releases/download/TAG/YourApp.1.2.3.zip

Follow the prompts: package identifier, publisher, locale strings, nested installer path for zips (often just YourApp.exe at the zip root). Submit the generated PR when asked.

Option B — Hand-authored PR

  1. Fork microsoft/winget-pkgs

  2. Add manifests under manifests/<letter>/<Publisher>/<App>/<version>/

  3. Validate (winget validate / upstream tools)

  4. Open a PR; respond to package moderator feedback

After the first PR merges, winget show Publisher.App should resolve.

CI-assisted updates

On each stable GitHub Release:

  1. Attach the same style of installer/zip you used in the first submission

  2. Run a workflow that opens a version-bump PR to winget-pkgs

Example using vedantmgoyal9/winget-releaser:

name: Publish to WinGet
on:
  release:
    types: [released]
  workflow_dispatch:
    inputs:
      release-tag:
        description: Existing release tag to publish
        required: true

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Check for WINGET_TOKEN
        id: gate
        env:
          WINGET_TOKEN: ${{ secrets.WINGET_TOKEN }}
        run: |
          if [ -n "$WINGET_TOKEN" ]; then
            echo "ok=true" >> "$GITHUB_OUTPUT"
          else
            echo "::warning::WINGET_TOKEN not set — skipping winget submission"
            echo "ok=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Submit to winget-pkgs
        if: steps.gate.outputs.ok == 'true'
        uses: vedantmgoyal9/winget-releaser@v2
        with:
          identifier: Publisher.App
          # Default regex is exe/msi/msix — override for portable zips:
          installers-regex: '\.zip$'
          release-tag: ${{ inputs.release-tag || github.event.release.tag_name }}
          token: ${{ secrets.WINGET_TOKEN }}

Keep the same PackageIdentifier across versions. Match installers-regex to the release asset you want winget to ship (avoid picking debug symbols or source archives).

wingetcreate / WinGet CLI need a Windows environment. GitHub Actions that only call winget-releaser can stay on ubuntu-latest; that action drives Linux-side tooling (komac) against your PAT.

Discoverability tips

  • Put the install command in the GitHub repo About description, or set the homepage URL to the README install heading (…/blob/BRANCH/README.md#install).

  • Document winget install Publisher.App near the top of the README.

Verify

winget show Publisher.App
winget install Publisher.App
winget upgrade Publisher.App

Related