DEV Community: Albert Hui

winget From Zero

Albert Hui — Tue, 28 Jul 2026 05:59:39 +0000

Part of the Shipping Large Rust Apps series — start with the map.

You have a Windows MSI. You built it earlier in this series with cargo-wix (that is The Windows MSI), and the one-tag workflow already attaches it to a GitHub Release every time you push a v* tag. Now you want a stranger on Windows to type winget install SecurityRonin.sqlite4n6 and have it just work.

This post gets you there from zero. It assumes you have never submitted to winget and have no idea what a manifest, a PackageIdentifier, a ProductCode, or an UpgradeCode is. We will define every one of those, hand-author the three files your first submission needs, walk the pull request by hand, then wire up the action that does it automatically for every release after.

There is one lesson that shapes everything else, so read it before anything: the automation cannot create a new package. It can only bump one that already exists. Your first version is manual. Internalize that and the rest is mechanical.

What winget actually is

winget is the Windows Package Manager — a command-line installer that ships with modern Windows. A user types winget install Microsoft.PowerToys and winget downloads the installer, runs it silently, and tracks the version so winget upgrade works later. It is the Windows answer to brew or apt.

Where does winget learn that Microsoft.PowerToys exists, where to download it, and what its SHA256 should be? From a giant public Git repository on GitHub: microsoft/winget-pkgs. Every package winget knows about is a folder of YAML files in that repo. To add your tool, you add files to that repo — by opening a pull request, exactly like contributing to any open-source project. Microsoft's bots and maintainers validate and merge it, and from then on your package is in the index that every winget client queries.

So "publishing to winget" means: get the right YAML files merged into microsoft/winget-pkgs. That is the whole game.

A package is three YAML manifests

winget does not describe a package in one file. It uses three, and they live together in one folder:

The version manifest — the smallest. It names the package and points at the other two. Filename: YourPublisher.YourTool.yaml.
The installer manifest — the meat. Architecture, installer type, the download URL, the SHA256, and (for MSIs) the ProductCode. Filename: YourPublisher.YourTool.installer.yaml.
The default-locale manifest — the human-readable metadata: publisher name, package name, description, license, homepage. Filename: YourPublisher.YourTool.locale.en-US.yaml.

All three sit in a path built from the identifier and version:

manifests/<first-letter>/<Publisher>/<Tool>/<Version>/

For a package identified as SecurityRonin.sqlite4n6 at version 0.1.0, that path is:

manifests/s/SecurityRonin/sqlite4n6/0.1.0/

The <first-letter> is the lowercased first letter of the publisher. Every new version gets its own version folder — 0.1.0/, 0.2.0/, … 0.10.1/ — each with its own three files.

The running example in this post is real: sqlite4n6, our read-only SQLite forensic CLI, published by SecurityRonin as SecurityRonin.sqlite4n6. (The package name and the repo name — sqlite-forensic — do not have to match; the identifier is its own namespace.) Every manifest, hash, and GUID below is from its actual first submission, and you can read the merged first-submission PR in winget-pkgs. Substitute your own values everywhere.

The PackageIdentifier

The PackageIdentifier is the unique name a user types: SecurityRonin.sqlite4n6. The convention is Publisher.PackageName — PascalCase is common, but keep your tool's natural casing (ours is lowercase, matching the crate and binary name) — and it must be globally unique across all of winget-pkgs. It is also the folder structure, the filename prefix, and the value the auto-update action keys off later. Pick it once and never change it — changing it later means a brand-new package, not a rename.

The four traps, named up front

The map flagged four traps for this leg. Here they are, so you know what each later step is defending against:

The action cannot create a package. winget-releaser (the GitHub Action) only updates a package that already exists in winget-pkgs. Your first version is a manual PR. Every version after that is automated.
Make the winget release job continue-on-error: true until that first PR merges. Before the package exists, the action fails — correctly, there is nothing to bump. Without the flag, that failure reds your whole release for no real reason.
UpgradeCode stable, ProductCode fresh. Two GUIDs in your MSI. winget decides "this is an upgrade of the thing already installed" by matching the UpgradeCode, so it must stay identical across every version. The ProductCode identifies one specific build and changes every time you rebuild — so you must read it out of each new MSI and put the fresh value in that version's installer manifest.
The action reads the .msi off your release — attach it, or it dies with an empty --urls. winget-releaser matches your installers-regex (\.msi$) against the assets on the GitHub Release for that tag, then feeds the matched download URLs to wingetcreate. If your release publishes only the portable .zip and not the built .msi, the regex matches nothing and the action fails with error: a value is required for '--urls' but none was supplied — even though the package exists in winget-pkgs and CI built the MSI. Building it isn't publishing it: the release's upload glob has to include *.msi, not just *.zip. (Lived case: a release whose files: listed *.tar.gz and *.zip but not *.msi — green build, silently no winget update.)

We will hit them in order.

Sign the MSI before you submit it

There is a step that belongs before the first PR, because it changes how both winget's moderators and the end user's machine treat your installer: Authenticode-sign the MSI. An unsigned .exe/.msi has no publisher identity, so Windows SmartScreen shows the blue "Windows protected your PC — unknown publisher" warning on first run, and winget's own moderation looks harder at an installer from a publisher it cannot verify. A signed installer from a validated organization shows a verified publisher instead, and the first submission moves more smoothly.

Authenticode is that identity. The old way to get a cert was an EV code-signing certificate on a USB HSM token — expensive, physically mailed, and impossible to plug into CI. The new way is Azure Trusted Signing (Microsoft rebranded it Azure Artifact Signing mid-flight, which matters — see the RBAC gotcha below): about $9.99/month, cloud-HSM-backed, short-lived certs, and CI-native via OIDC — no secret to store, no token to plug in.

One-time setup

Register the resource provider and deploy the account:

   az provider register --namespace Microsoft.CodeSigning
   az group create --name signing --location northeurope
   az deployment group create -g signing --template-uri \
     "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.codesigning/codesigning-create-account/azuredeploy.json" \
     --parameters accountName=securityronin skuName=Basic location=northeurope

Region gotcha: a brand-new tenant is blocked from capacity-constrained regions. West Europe rejected the account with RequestDisallowedByAzure: "The selected region is currently not accepting new customers." Deploy to North Europe (or a US region). Known-good: N.Europe, W.Europe, E.US, W.Central US, W.US3.

Public Trust identity validation. In the Trusted Signing account → Identity validations → Organization → Public — validated against Dun & Bradstreet. You must be a US / CA / EU / UK organization with a D-U-N-S number. Then create a Public Trust certificate profile.
Assign the RBAC roles — and mind the rebrand. The role names are Artifact Signing …, NOT "Trusted Signing …" — the rebrand desynced the docs from the actual role-definition strings. You want Artifact Signing Certificate Profile Signer on the CI identity (and Artifact Signing Identity Verifier for the human doing the validation). Discover the exact strings if in doubt:

   az role definition list --query "[?contains(roleName,'Signing')].roleName" -o tsv

Create the CI identity as an Entra app + federated (OIDC) credential — subject repo:SecurityRonin/sqlite-forensic:ref:refs/tags/v[0-9]*, holding the Certificate Profile Signer role. There's no client secret to rotate; the AZURE_TENANT_ID / AZURE_CLIENT_ID you store as "secrets" are just non-sensitive IDs.

The CI signing step

Sign on the Windows runner, after cargo build produces the .exe but before you feed it to cargo-wix — sign the bytes that ship, then package them. Then sign the built .msi as its own step, so the installer clears SmartScreen too, not just the exes inside it.

permissions:
  id-token: write        # OIDC → Azure (no stored client secret)
  contents: write

# … after the .exe is built, before cargo-wix builds the MSI:

# OIDC login FIRST. The signing action's DefaultAzureCredential does NOT do the
# GitHub-OIDC exchange itself — azure/login trades the id-token for an az session
# the signer then rides on.
- uses: azure/login@<sha>                    # v3.0.0 — SHA-pin
  with:
    client-id: ${{ secrets.AZURE_CLIENT_ID }}
    tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

- uses: azure/trusted-signing-action@<sha>   # SHA-pin
  with:                                      # NO azure-* auth inputs — auth = the login session
    endpoint: https://neu.codesigning.azure.net      # North Europe — region-specific!
    trusted-signing-account-name: securityronin
    certificate-profile-name: securityronin-public
    files-folder: target/${{ matrix.target }}/release
    files-folder-filter: exe
    file-digest: SHA256
    timestamp-rfc3161: http://timestamp.acs.microsoft.com
    timestamp-digest: SHA256

Run the same signing action a second time against the built .msi (filter msi).

The three gotchas that will cost you an afternoon:

azure/login before the signer is mandatory — it's the #1 CI failure. Without it, the action falls through to AzureCliCredential and dies Please run 'az login' — a maddeningly misleading error, because it's a missing step, not a local mistake. Run azure/login first, drop the azure-* inputs from the signing action, and remember to pass AZURE_SUBSCRIPTION_ID.
The endpoint is region-specific and must match the account's region — neu / weu / eus / … .codesigning.azure.net. Wrong endpoint = a confusing auth failure that looks like a permissions problem.
Sign before you package. Sign the .exe, then build the MSI, and sign the MSI as its own step. Signing the wrapper doesn't sign what's inside it.

With the MSI signed, the SHA256 you read out for the manifest (next section) is the hash of the signed installer — so sign first, then hash, then submit.

Part 1 — The manual first submission

Step 1: Get the SHA256 and the ProductCode from your MSI

Your installer manifest needs two values pulled out of the actual MSI file: its SHA256 hash, and its ProductCode.

The SHA256 is straightforward. On Windows PowerShell:

Get-FileHash .\sqlite4n6-0.1.0-x86_64-pc-windows-msvc.msi -Algorithm SHA256

For this MSI that prints 3BFD608862C6305BF9401930ED9608CD50B34CBFC0DAD18484116E0AE6DE93A7. Copy the hash. winget wants it uppercase; PowerShell already gives it to you that way.

The ProductCode is a GUID baked into the MSI. An MSI stores it in a Property table inside the file, under the property name ProductCode. Two ways to read it:

With msitools (the msiinfo command, available on Linux/macOS or via MSYS2 on Windows):

msiinfo export sqlite4n6-0.1.0-x86_64-pc-windows-msvc.msi Property | grep -E '^Product(Code|Version)|^UpgradeCode'

That dumps the Property table; for this MSI:

ProductCode {0EB6897B-0234-46DC-8810-EACA6E0BFDB9}
ProductVersion  0.1.0
UpgradeCode {070DCA3F-F901-4736-9C5D-12F7AA00F064}

Or natively in PowerShell, using the Windows Installer COM object:

$installer = New-Object -ComObject WindowsInstaller.Installer
$db = $installer.OpenDatabase(".\sqlite4n6-0.1.0-x86_64-pc-windows-msvc.msi", 0)
$view = $db.OpenView("SELECT Value FROM Property WHERE Property='ProductCode'")
$view.Execute()
$view.Fetch().StringData(1)

Either way you get a GUID in braces — {0EB6897B-0234-46DC-8810-EACA6E0BFDB9} for this build. That is your ProductCode. Write it down. It is wrong for the next build — you re-read it every release. (sqlite4n6 is living proof of both halves: ten versions later, at 0.10.1, the ProductCode has become {2F509EB7-EBBA-423D-958F-D399AAE971FA} while the UpgradeCode is still {070DCA3F-F901-4736-9C5D-12F7AA00F064} — fresh every build, stable forever, respectively.)

Where do these GUIDs come from? They are set in your wix/main.wxs, the WiX source The Windows MSI post covers. The UpgradeCode is an attribute you hardcode once and never touch. The ProductCode is the Product/@Id — and if you set it to * (the WiX convention for "autogenerate"), WiX mints a new one on every build. That is exactly why it is fresh each release.

Step 2: Write the version manifest

Create SecurityRonin.sqlite4n6.yaml:

# yaml-language-server: $schema=https://aka.ms/winget-manifest.version.1.12.0.schema.json

PackageIdentifier: SecurityRonin.sqlite4n6
PackageVersion: 0.1.0
DefaultLocale: en-US
ManifestType: version
ManifestVersion: 1.12.0

Every field:

The # yaml-language-server comment is optional but worth keeping — editors with a YAML language server validate the file against the schema as you type.
PackageIdentifier — the unique name, exactly as it appears in the folder path and the other two files.
PackageVersion — 0.1.0. This must match the version folder name and the version in the other manifests.
DefaultLocale — en-US, telling winget which locale manifest is the fallback. It must match the locale of your locale file.
ManifestType — version. This is what marks this file as the version manifest.
ManifestVersion — the schema version of the manifest format itself (not your app's version). Use a current one — 1.12.0 here; check the winget-pkgs manifest schemas for the latest.

Step 3: Write the installer manifest

Create SecurityRonin.sqlite4n6.installer.yaml:

# yaml-language-server: $schema=https://aka.ms/winget-manifest.installer.1.12.0.schema.json

PackageIdentifier: SecurityRonin.sqlite4n6
PackageVersion: 0.1.0
InstallerLocale: en-US
InstallerType: wix
Scope: machine
InstallModes:
- interactive
- silent
- silentWithProgress
Dependencies:
  PackageDependencies:
  - PackageIdentifier: Microsoft.VCRedist.2015+.x64
ProductCode: '{0EB6897B-0234-46DC-8810-EACA6E0BFDB9}'
ReleaseDate: 2026-06-18
AppsAndFeaturesEntries:
- Publisher: Security Ronin
  ProductCode: '{0EB6897B-0234-46DC-8810-EACA6E0BFDB9}'
  UpgradeCode: '{070DCA3F-F901-4736-9C5D-12F7AA00F064}'
InstallationMetadata:
  DefaultInstallLocation: '%ProgramFiles%\sqlite4n6\bin'
Installers:
- Architecture: x64
  InstallerUrl: https://github.com/SecurityRonin/sqlite-forensic/releases/download/v0.1.0/sqlite4n6-0.1.0-x86_64-pc-windows-msvc.msi
  InstallerSha256: 3BFD608862C6305BF9401930ED9608CD50B34CBFC0DAD18484116E0AE6DE93A7
ManifestType: installer
ManifestVersion: 1.12.0

Field by field:

PackageIdentifier, PackageVersion — same values as the version manifest. They tie the three files together.
InstallerType — wix for an MSI built by WiX (which cargo-wix is). The plain value msi also works; wix is the more specific type for a WiX-authored MSI and is what winget recommends for these. Both are valid InstallerType values.
Scope: machine — this MSI installs for all users under %ProgramFiles%, not per-user. Declare it so winget shows and handles the install correctly.
InstallModes — which of winget's install experiences the MSI supports. An MSI built by cargo-wix supports all three; listing them lets the user pick --interactive or (the default) silent.
Dependencies — packages winget should install first. A Rust binary built with the MSVC toolchain links the VC++ runtime, so declare Microsoft.VCRedist.2015+.x64 rather than hoping the target machine has it. This is the difference between "works on most machines" and "works on a fresh VM".
ProductCode — the GUID from Step 1, in braces, quoted because YAML otherwise tries to read {…} as a map. This is the value that changes every release.
ReleaseDate — the release's date, straight off the GitHub Release.
AppsAndFeaturesEntries — how the installed app appears in Windows' Apps & Features list: display publisher, and the ProductCode/UpgradeCode pair that lets winget match an already-installed copy to this package. This is the one place the UpgradeCode appears in a manifest — winget uses it to recognize "this installed thing is an older version of that package" even when every version's ProductCode differs. Your job is still to keep it stable in the wxs (see the box in Step 1).
InstallationMetadata.DefaultInstallLocation — where the MSI puts the files; lets winget find the install for repair/portable-alias purposes.
Installers — a list, one entry per architecture you ship. Most Rust CLIs ship one x64 MSI, so one entry.
- Architecture — x64 for x86_64. (Use arm64 if you also ship an ARM MSI; x86 for 32-bit.)
- InstallerUrl — the direct download URL of the MSI asset on your GitHub Release. This is the URL the one-tag workflow produces — …/releases/download/<tag>/<msi-filename>. It must be a stable, public, direct link, not a redirect page.
- InstallerSha256 — the hash from Step 1. winget refuses to install if the downloaded file's hash does not match this, which is how it guarantees the binary is the one you submitted.
ManifestType — installer.
ManifestVersion — same schema version as the other two files.

Strictly, only the identifier/version/type/URL/hash core is required — but the middle block (Scope, InstallModes, Dependencies, AppsAndFeaturesEntries, InstallationMetadata) is what makes the package behave like a first-class citizen on a stranger's machine, so write it in the first submission and the auto-update tooling will carry it forward.

Step 4: Write the default-locale manifest

Create SecurityRonin.sqlite4n6.locale.en-US.yaml:

# yaml-language-server: $schema=https://aka.ms/winget-manifest.defaultLocale.1.12.0.schema.json

PackageIdentifier: SecurityRonin.sqlite4n6
PackageVersion: 0.1.0
PackageLocale: en-US
Publisher: SecurityRonin
PublisherUrl: https://github.com/SecurityRonin
PublisherSupportUrl: https://github.com/SecurityRonin/sqlite-forensic/issues
PackageName: sqlite4n6
PackageUrl: https://github.com/SecurityRonin/sqlite-forensic
License: Apache-2.0
LicenseUrl: https://github.com/SecurityRonin/sqlite-forensic/blob/HEAD/LICENSE
Copyright: Copyright (c) SecurityRonin
ShortDescription: Read-only SQLite forensic CLI — carve deleted records, grade anomalies
Description: |-
  sqlite4n6 is a read-only SQLite forensic CLI. It carves deleted records out of
  a database's free (unallocated) space — freelist pages, in-page free blocks,
  dropped-table pages, and an uncheckpointed WAL overlay — recovering rows a live
  query cannot, and grades forensically-notable anomalies into severity-ranked
  findings. It opens the evidence file read-only and never writes the file or its
  sidecars.
Moniker: sqlite4n6
Tags:
- carving
- cli
- data-recovery
- deleted-records
- dfir
- forensics
- sqlite
- wal
ReleaseNotes: 'Full Changelog: https://github.com/SecurityRonin/sqlite-forensic/commits/v0.1.0'
ReleaseNotesUrl: https://github.com/SecurityRonin/sqlite-forensic/releases/tag/v0.1.0
ManifestType: defaultLocale
ManifestVersion: 1.12.0

The fields:

PackageIdentifier, PackageVersion — same as the others.
PackageLocale — en-US, and it must equal the DefaultLocale from the version manifest.
Publisher — the human-readable publisher name (the legal/brand name), distinct from the PackageIdentifier prefix.
PublisherUrl — the publisher's site or GitHub org. Optional but expected.
PackageName — the display name users see in winget search and winget show.
PackageUrl — the project homepage.
License — the SPDX license identifier (Apache-2.0, MIT, etc.).
LicenseUrl — link to the license text.
ShortDescription — one sentence. This shows up in search results, so make it say what the tool does.
Description — the long-form version, shown by winget show. Say what the tool actually does, concretely.
PublisherSupportUrl — where users report problems; the repo's issues page is the natural value.
Copyright — a one-line copyright string.
Moniker — an optional short alias users can install by (winget install sqlite4n6). Not unique like the identifier; treat it as a convenience.
Tags — search keywords.
ReleaseNotes / ReleaseNotesUrl — per-version notes; the auto-update tooling fills these from the GitHub Release on every bump.
ManifestType — defaultLocale.
ManifestVersion — same schema version.

Publisher, PackageName, License, ShortDescription are the required ones; the rest are strongly recommended and will make your winget show output look complete.

Step 5: Validate locally before you submit

You have three files. Before you fork anything, check that winget itself accepts them. On a Windows machine with winget installed, point winget validate at the folder:

winget validate --manifest .\manifests\s\SecurityRonin\sqlite4n6\0.1.0\

It parses all three files and reports schema errors — a wrong ManifestType, a mismatched version, a missing required field. Fix until it says the manifests are valid.

Then test that the package actually installs from your manifests, using a local install:

winget install --manifest .\manifests\s\SecurityRonin\sqlite4n6\0.1.0\

This is the real test. winget reads your installer manifest, downloads the MSI from InstallerUrl, checks the SHA256 against InstallerSha256, and runs the install silently. If the URL is wrong, the hash is stale, or the MSI is broken, you find out here — on your machine, before a single maintainer looks at it.

Checkpoint. Before moving on: winget validate passes, and winget install --manifest installs and runs your tool. If both hold, your manifests are correct and your URL/hash are live. Now, and only now, do you open the PR.

Step 6: Fork, place the files, open the PR

The submission is an ordinary GitHub pull request to microsoft/winget-pkgs.

Fork microsoft/winget-pkgs to your account or org. (The auto-update action later expects a fork to exist; forking now does double duty.)
Clone your fork, create a branch, and add your three files at the exact path:

   manifests/s/SecurityRonin/sqlite4n6/0.1.0/SecurityRonin.sqlite4n6.yaml
   manifests/s/SecurityRonin/sqlite4n6/0.1.0/SecurityRonin.sqlite4n6.installer.yaml
   manifests/s/SecurityRonin/sqlite4n6/0.1.0/SecurityRonin.sqlite4n6.locale.en-US.yaml

Commit, push to your fork, and open a PR against microsoft/winget-pkgs.

What happens next is automated on Microsoft's side. A validation bot runs the same schema checks (and an install/sandbox test), labels the PR, and either flags problems for you to fix or clears it for a maintainer. A first submission for a new package gets a closer human look than later bumps, so expect some back-and-forth and answer it promptly. When it merges, your package exists in winget-pkgs.

Checkpoint. The PR is merged — for sqlite4n6 that was winget-pkgs PR #390308. SecurityRonin.sqlite4n6 is now a real package. From here on, you never hand-author manifests again — the action does it.

Part 2 — Auto-updates for every release after

Now that the package exists, the winget-releaser action can bump it. It runs in your project repo (not winget-pkgs), reacts to a published GitHub Release, reads the MSI asset, and opens the bump PR to winget-pkgs for you — recomputing the SHA256 and pulling the fresh ProductCode itself.

This job belongs in the same release pipeline as everything else — it is one more fan-out target from the one-tag workflow. Add it as a job that runs after the GitHub Release is published:

This is the live job from sqlite4n6's release.yml, verbatim:

  winget:
    needs: release
    runs-on: windows-latest
    # First-time winget submission requires a manual PR; continue-on-error until registered
    continue-on-error: true
    steps:
      - uses: vedantmgoyal9/winget-releaser@4ffc7888bffd451b357355dc214d43bb9f23917e # v2
        with:
          identifier: SecurityRonin.sqlite4n6
          installers-regex: '\.msi$'
          token: ${{ secrets.WINGET_TOKEN }}
          fork-user: securityronin-bot

What each piece does:

needs: release — this job waits for the job that creates the GitHub Release and attaches the MSI. The action reads the MSI off the published Release, so the Release must exist first. (The action only works on a published, non-draft release, because the asset has to be publicly downloadable.)
continue-on-error: true — the second trap. Until your first manual PR has merged, the package does not exist, so the action fails. This flag stops that expected failure from failing the whole release run. The moment your bootstrap PR is merged, delete this line so a real winget failure becomes visible again. Leaving it forever means a genuinely broken winget bump passes silently.
identifier — the PackageIdentifier, exactly as registered. This is how the action finds the existing package to bump.
installers-regex — which Release assets are the installers. The default matches several installer extensions; narrowing it to \.msi$ makes sure it grabs your MSI and nothing else.
token — a Personal Access Token, stored as a repo or org secret. The action needs it to push a branch to your winget-pkgs fork and open the PR. It must be a classic PAT with public_repo scope — the action does not support fine-grained tokens. (Keep this token as an organization secret, like the rest of your publish tokens, per the secrets lesson in the map.)
fork-user — the account holding the winget-pkgs fork the action pushes to. The fleet uses a dedicated bot account (securityronin-bot) so the PR spam lands on a machine identity, not a human's fork; the token must belong to this account.

Under the hood the action uses Komac (a winget manifest tool) to regenerate all three manifests for the new version, with the new URL, the recomputed hash, and the fresh ProductCode read from the new MSI. You do nothing per release except push your v* tag — the same tag that drives every other channel.

The action is pinned to a full commit SHA (with the # v2 comment recording the human-readable version) — the supply-chain discipline from the map applied to one more third-party action. Check its releases when bumping the pin, and let Renovate or Dependabot keep the SHA current.

Verify it actually worked

A merged PR is not proof a user can install your tool. The winget client only sees a new package after the source index it queries is rebuilt and your client pulls it — usually a short wait after merge, plus a winget source update. Verify it for real:

winget source update
winget search SecurityRonin.sqlite4n6
winget install SecurityRonin.sqlite4n6

(These are live commands — the package is real, so you can run them on any Windows machine right now.)

winget search should list your package; winget install should download from your GitHub Release, check the hash, and install. Run the tool to confirm it works. That is a green install, not a green push.

For the next release, the upgrade path is the thing to verify: after the action's bump PR merges, a machine that already has the old version should get the new one with:

winget upgrade SecurityRonin.sqlite4n6

If winget upgrade does not see your new version as an upgrade of the installed one, the usual cause is an UpgradeCode that changed between builds — winget no longer recognizes the new MSI as the same product. That brings us to the recap.

No MSI? The portable-zip route — and the type-flip trap

Everything above assumes an MSI. winget also installs plain zips: our timeglyph shipped its first winget versions as SecurityRonin.timeglyph with nothing but the zip the release matrix already produced. The installer manifest swaps the MSI fields for three lines:

InstallerType: zip
NestedInstallerType: portable
NestedInstallerFiles:
- RelativeFilePath: timeglyph.exe
  PortableCommandAlias: timeglyph

winget downloads the zip, extracts timeglyph.exe, and shims it onto the user's PATH under the alias. No ProductCode, no UpgradeCode, no WiX — if your tool is a single CLI executable, this is the lowest-effort door into winget, and the same manual-first-PR-then-winget-releaser bootstrap applies unchanged.

The trade-offs are real, though: a portable install puts nothing in Apps & Features, runs no installer logic — no Start Menu shortcut, so a companion GUI binary in the zip has no launcher — and (unlike the MSI route) the extracted exe's Authenticode signature is the only publisher identity the user ever sees. timeglyph is outgrowing exactly these limits: its next release ships a signed MSI that installs both binaries and a Start Menu shortcut for its GUI. Which exposes one more trap for the table: winget-releaser bumps versions, it does not change a package's installer type. Moving a package from zip to msi is another one-time manual manifest PR — the same bootstrap ritual as the first submission, once per structural change.

What bit me, and the fix

What bit me	Why	The fix
The auto-update action failed on the very first release	The package did not exist yet; the action only bumps existing packages	Hand-author three manifests and open a manual PR to `microsoft/winget-pkgs` for the first version
Every release run went red because of winget	The action fails (correctly) until the first PR merges	Set `continue-on-error: true` on the winget job; remove it once the bootstrap PR is merged
`winget upgrade` stopped recognizing new versions	The MSI's `UpgradeCode` changed between builds	Hardcode the `UpgradeCode` once in `wix/main.wxs` and never change it
Validation rejected a stale `ProductCode`	The `ProductCode` changes every build; the manifest carried the old one	Re-read the `ProductCode` from each new MSI (`msiinfo export … Property` or the PowerShell COM call); the action does this for you on auto-bumps
The action could not open a PR (auth error)	A fine-grained PAT, or one without `public_repo`	Use a classic PAT with `public_repo` scope, stored as a secret
`winget install` failed on hash mismatch	The `InstallerSha256` did not match the actual MSI	Recompute the SHA256 from the exact file you uploaded; test with `winget install --manifest` before submitting
`InstallerUrl` 404'd during install	URL pointed at a release page or a moved asset	Use the direct `…/releases/download/<tag>/<file>.msi` link from the GitHub Release

The shape of it: one manual PR to bootstrap the package, one continue-on-error flag to survive the gap, one stable UpgradeCode and one fresh ProductCode per build. Past that, your v* tag carries winget along with everything else — the action regenerates the manifests, opens the PR, and a stranger on Windows types winget install SecurityRonin.sqlite4n6 and gets your tool.

Homebrew Without the Footguns

Albert Hui — Tue, 28 Jul 2026 05:40:54 +0000

Part of the Shipping Large Rust Apps series — start with the map.

You have a built binary attached to a GitHub Release. A Mac user wants to type brew install timeglyph and have it work — and if your tool has a desktop app, brew install --cask yourapp should work just as well. This post takes you from there, assuming you have never made a Homebrew formula, never made a tap, and have never heard the words "bottle" or "repository_dispatch", to a tap that installs your tool and updates itself on every new tag. The CLI formula comes first because it needs no signing at all; the GUI cask and its Gatekeeper paperwork build on the same tap at the end.

The map flagged three traps that cost an afternoon each: use one shared tap (not one per tool), give every project its own dispatch event type, and make sure the dispatching bot has write access. We'll build the whole thing around those three, from zero.

The vocabulary, in plain terms

Three words, and then nothing in this post is mysterious.

A tap is a GitHub repository. That's the whole secret. A "tap" is just a repo whose name starts with homebrew-. When you run brew install yourorg/tap/timeglyph, Homebrew expands that into "go to github.com/yourorg/homebrew-tap, find the formula named timeglyph, and install it." The yourorg/tap in the command is shorthand: the yourorg is the GitHub org or user, and tap is the part after homebrew- in the repo name homebrew-tap. So SecurityRonin/homebrew-tap is installed as SecurityRonin/tap.

A formula is a Ruby file. Inside the tap repo, formulas live in a Formula/ directory. Each one is a .rb file — Formula/timeglyph.rb — that tells Homebrew where to download your binary, how to verify it, and where to put it. You do not need to know Ruby. A formula is a fill-in-the-blanks template, and we'll fill in every blank below.

A bottle is a pre-compiled formula. You'll see the word in Homebrew docs. For a formula that downloads an already-built binary (which is what we're doing — we built it in the release workflow, we are not asking Homebrew to compile Rust on the user's machine), bottles don't apply. Ignore the word. We download a tarball that already contains the executable.

So the plan: one repo named homebrew-tap, with one Ruby file per tool inside Formula/, each pointing at a GitHub Release asset.

One tap for the whole fleet

The first instinct is one tap per tool: homebrew-timeglyph, homebrew-other-tool, and so on. Don't. Make one tap repo — homebrew-tap — and put every tool's formula inside it.

Why one tap:

The install command is cleaner and consistent. Every tool in the fleet is brew install yourorg/tap/<tool>. Users learn the prefix once.
brew tap yourorg/tap once gives them everything. After a single brew tap, every tool you ship is installable by bare name. A tap-per-tool forces a separate tap for each.
One place to wire auto-updates. The handler workflows that bump formulas all live in one repo. You set up the secret and the write access once, not N times.

The cost is that all formulas share one repo's commit history, which is a non-issue. Make the one tap.

Step 1 — create the tap repo

On GitHub, create a new public repository named exactly homebrew-tap under your org (here, SecurityRonin). Add a Formula/ directory. That's it — an empty Formula/ directory and a README is a valid tap.

Checkpoint: you should be able to run brew tap SecurityRonin/tap and have it succeed (it'll just find no formulas yet). If brew tap errors, the repo name is wrong — it must start with homebrew-.

Step 2 — write the first formula by hand

The auto-update workflow (Step 4) regenerates this file on every release, but you need a correct first version to seed it, and writing one by hand is how you'll understand what the automation is doing.

Here is a complete formula for a Rust binary distributed as a release tarball. The running example is real: timeglyph, our forensic timestamp decoder, whose release workflow (the one from one tag, every artifact) attached an asset named timeglyph-0.7.1-aarch64-apple-darwin.tar.gz to the v0.7.1 release. The tarball carries the timeglyph executable (plus a companion GUI binary we'll meet at the end). Start with the smallest thing that works — one architecture, one binary:

class Timeglyph < Formula
  desc "Forensic timestamp decipherment — scored, cited, ambiguity-first"
  homepage "https://github.com/SecurityRonin/timeglyph"
  version "0.7.1"
  url "https://github.com/SecurityRonin/timeglyph/releases/download/v0.7.1/timeglyph-0.7.1-aarch64-apple-darwin.tar.gz"
  sha256 "0000000000000000000000000000000000000000000000000000000000000000"
  license "Apache-2.0"

  def install
    bin.install "timeglyph"
  end

  test do
    assert_match "timeglyph", shell_output("#{bin}/timeglyph --version")
  end
end

Every line, top to bottom:

class Timeglyph < Formula — the class name is the formula name in CamelCase. File timeglyph.rb becomes class Timeglyph; a hyphenated name like report-cli would become ReportCli — hyphens drop and each word capitalizes. Homebrew enforces this mapping; get it wrong and brew audit complains.
desc — a one-line description. Keep it short; brew audit rejects descriptions that start with "A"/"An" or end with a period.
homepage — your project's URL. Required.
version "0.7.1" — the version string, no leading v. Homebrew can often infer this from the url, but stating it explicitly makes the auto-update rewrite (Step 4) a clean find-and-replace.
url — the direct download link to the release asset. This is the load-bearing line: it points at the exact file the release workflow attached. The pattern is .../releases/download/<tag>/<asset-name>.
sha256 — the SHA-256 of the file at url. Homebrew downloads the tarball and refuses to install if the hash doesn't match, which is what protects users from a corrupted or swapped asset. The 64 zeros above are a placeholder; the next section computes the real value.
license "Apache-2.0" — the SPDX license identifier. brew audit checks it.
def install ... end — the install block. bin.install "timeglyph" takes the file named timeglyph from the unpacked tarball and installs it into Homebrew's bin directory (which is on the user's PATH). If your tarball nests the binary in a subdirectory, give the path: bin.install "timeglyph-0.7.1-aarch64-apple-darwin/timeglyph".
test do ... end — runs on brew test timeglyph and during brew audit. shell_output runs the command and captures stdout; assert_match fails if the expected string isn't present. Here it confirms timeglyph --version runs and identifies itself. A formula with no real test is a formula nobody can verify, so write one that actually exercises the binary — the full formula below adds a second assertion that decodes a known timestamp and checks the answer.

Step 3 — compute the sha256

Download the exact asset and hash it. On macOS:

curl -L -o timeglyph-0.7.1-aarch64-apple-darwin.tar.gz \
  https://github.com/SecurityRonin/timeglyph/releases/download/v0.7.1/timeglyph-0.7.1-aarch64-apple-darwin.tar.gz
shasum -a 256 timeglyph-0.7.1-aarch64-apple-darwin.tar.gz

shasum -a 256 prints the 64-character hex digest followed by the filename — for this asset, d686ff4c8dcf4167333257041e60a1a0d85d291efbb208b588018d54db41d6cf. Copy the digest into the sha256 line, replacing the zeros. (Linux users: sha256sum instead of shasum -a 256. Homebrew also bundles its own copy: brew install --interactive and friends, but shasum is simplest.)

The -L on curl matters — GitHub release downloads redirect, and without -L you'll hash a tiny redirect page instead of the tarball. If your computed hash looks wrong, check that the downloaded file is actually megabytes, not a few hundred bytes.

Checkpoint: the file on disk is the real binary tarball (check its size), and the sha256 line now holds its digest.

Step 4 — supporting both Apple Silicon and Intel

Macs come in two architectures now: Apple Silicon (arm64) and older Intel (x86_64) — and Homebrew also runs on Linux, where the same formula can serve the musl builds. If your release workflow builds all four targets (the matrix in the map does), your formula hands each user the right binary. Here is the file as it actually ships today — Formula/timeglyph.rb in SecurityRonin/homebrew-tap, verbatim:

class Timeglyph < Formula
  desc "Forensic timestamp decipherment — scored, cited, ambiguity-first"
  homepage "https://github.com/SecurityRonin/timeglyph"
  version "0.7.1"
  license "Apache-2.0"

  on_macos do
    if Hardware::CPU.arm?
      url "https://github.com/SecurityRonin/timeglyph/releases/download/v0.7.1/timeglyph-0.7.1-aarch64-apple-darwin.tar.gz"
      sha256 "d686ff4c8dcf4167333257041e60a1a0d85d291efbb208b588018d54db41d6cf"
    else
      url "https://github.com/SecurityRonin/timeglyph/releases/download/v0.7.1/timeglyph-0.7.1-x86_64-apple-darwin.tar.gz"
      sha256 "d185000c02d29d2a050e32919ea1b5856dd64aec04ecd881a0a5b6537dae644c"
    end
  end

  on_linux do
    if Hardware::CPU.arm?
      url "https://github.com/SecurityRonin/timeglyph/releases/download/v0.7.1/timeglyph-0.7.1-aarch64-unknown-linux-musl.tar.gz"
      sha256 "54023ed5f1a80471a51e7ae4adb78ed8a39d7aef0ec47b0408846c21bd4abeff"
    else
      url "https://github.com/SecurityRonin/timeglyph/releases/download/v0.7.1/timeglyph-0.7.1-x86_64-unknown-linux-musl.tar.gz"
      sha256 "9bf6fd1da0be4e957dbe9fe2f0b1939e0d2456044b8e0bd98755fb5e29b04663"
    end
  end

  def install
    bin.install "timeglyph"
    # The macOS archive also carries the lens GUI (Linux is CLI-only).
    bin.install "timeglyph-lens" if OS.mac?
  end

  test do
    assert_match "timeglyph", shell_output("#{bin}/timeglyph --version")
    assert_match "2020-01-01", shell_output("#{bin}/timeglyph decode unix 1577836800")
  end
end

Four URLs, four hashes, one per platform-architecture pair: on_macos/on_linux pick the OS, Hardware::CPU.arm? picks the architecture inside each. Compute each sha256 from its own asset (Step 3, four times — or read them all from the release's checksums.txt, which is what the automation in Step 6 does). version, desc, install, and test stay shared. Note the second test assertion: decoding the Unix timestamp 1577836800 must print 2020-01-01 — a real functional check, not just a version string. Don't reach for anything fancier than this structure — two nested branches is the whole job, and over-engineering the selection logic is its own footgun.

Commit this file to Formula/timeglyph.rb in the tap. That's the seed done.

Step 5 — verify the seed installs

Before automating anything, confirm the hand-written formula works:

brew install SecurityRonin/tap/timeglyph
timeglyph --version
brew audit --strict SecurityRonin/tap/timeglyph

brew install should download the asset matching your Mac's architecture, verify the sha256, and drop timeglyph on your PATH. Running timeglyph --version proves it landed. brew audit --strict runs Homebrew's own lint over the formula and flags style problems before users hit them. (These are live commands — the tap and formula are public, so you can run all three right now and watch them pass.)

Checkpoint: all three commands succeed. If brew install fails on the sha256, you hashed the wrong file or the wrong architecture's asset. If it fails on bin.install, the binary's name or path inside the tarball doesn't match — unpack the tarball locally and look.

Step 6 — wire the auto-update so you never edit the formula by hand again

Editing the formula by hand on every release is the manual step we're eliminating. The mechanism is GitHub's repository_dispatch: one repo (your app's release workflow) sends a custom event to another repo (the tap), and a workflow in the tap wakes up and does the work.

The flow:

There are two halves: the dispatch (in your app repo's release.yml) and the handler (in the tap).

The dispatch step, in the app's release.yml

After the release job has created the GitHub Release with its assets, add a step that pokes the tap. This step lives in the same release.yml that the one-tag workflow fires:

  - uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3.0.0
    with:
      token: ${{ secrets.TAP_GITHUB_TOKEN }}
      repository: SecurityRonin/homebrew-tap
      event-type: update-timeglyph
      client-payload: '{"version": "${{ github.ref_name }}"}'

That is timeglyph's actual dispatch step. Under the hood it is a single HTTP POST, which you could equally send yourself:

curl --fail -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <token-with-tap-write-access>" \
  https://api.github.com/repos/SecurityRonin/homebrew-tap/dispatches \
  -d '{"event_type":"update-timeglyph","client_payload":{"version":"v0.7.1"}}'

The two parts that matter:

event-type: update-timeglyph — a name unique to this project. Not update-formula. Not update. The handler in the tap listens for exactly this string. (This is the second footgun, and it has its own section below.)
client_payload — arbitrary JSON you pass along. Here we send the tag (github.ref_name, e.g. v0.7.1) so the handler knows which release to read.

The secrets.TAP_GITHUB_TOKEN is a credential with write access to the tap. That's the third footgun, also below. (One reason to prefer the action over a hand-rolled curl: the action fails the job on a 403, while a bare curl without --fail exits 0 and hides the problem.)

The handler workflow, in the tap

In the tap repo, create .github/workflows/update-timeglyph.yml. It triggers on the matching event_type and regenerates the formula. This is the live handler from SecurityRonin/homebrew-tap, verbatim:

name: Update timeglyph formula

on:
  repository_dispatch:
    types: [update-timeglyph]
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to update to (e.g., v0.2.0 or 0.2.0)'
        required: true
        type: string

permissions:
  contents: write

jobs:
  update-formula:
    runs-on: ubuntu-latest
    steps:
      - name: Set version from event
        id: get-version
        run: |
          if [ "${{ github.event_name }}" = "repository_dispatch" ]; then
            RAW="${{ github.event.client_payload.version }}"
          else
            RAW="${{ inputs.version }}"
          fi
          # Strip leading 'v' if present (tags are v0.2.0, formula wants 0.2.0)
          VERSION="${RAW#v}"
          echo "version=${VERSION}" >> $GITHUB_OUTPUT

      - name: Checkout
        uses: actions/checkout@v4

      - name: Download checksums from release
        run: |
          VERSION="${{ steps.get-version.outputs.version }}"
          echo "Downloading checksums for v${VERSION}..."
          gh release download "v${VERSION}" \
            --repo SecurityRonin/timeglyph \
            --pattern "checksums.txt"
          cat checksums.txt
        env:
          GH_TOKEN: ${{ github.token }}

      - name: Extract SHA256 checksums
        id: checksums
        run: |
          extract_sha() {
            grep "$1" checksums.txt | awk '{print $1}'
          }

          VERSION="${{ steps.get-version.outputs.version }}"
          echo "arm64_macos_sha=$(extract_sha "timeglyph-${VERSION}-aarch64-apple-darwin.tar.gz")" >> $GITHUB_OUTPUT
          echo "x86_64_macos_sha=$(extract_sha "timeglyph-${VERSION}-x86_64-apple-darwin.tar.gz")" >> $GITHUB_OUTPUT
          echo "arm64_linux_sha=$(extract_sha "timeglyph-${VERSION}-aarch64-unknown-linux-musl.tar.gz")" >> $GITHUB_OUTPUT
          echo "x86_64_linux_sha=$(extract_sha "timeglyph-${VERSION}-x86_64-unknown-linux-musl.tar.gz")" >> $GITHUB_OUTPUT

      - name: Update Formula
        run: |
          VERSION="${{ steps.get-version.outputs.version }}"
          ARM64_MACOS="${{ steps.checksums.outputs.arm64_macos_sha }}"
          X86_64_MACOS="${{ steps.checksums.outputs.x86_64_macos_sha }}"
          ARM64_LINUX="${{ steps.checksums.outputs.arm64_linux_sha }}"
          X86_64_LINUX="${{ steps.checksums.outputs.x86_64_linux_sha }}"

          cat > Formula/timeglyph.rb << FORMULA
          class Timeglyph < Formula
            desc "Forensic timestamp decipherment — scored, cited, ambiguity-first"
            homepage "https://github.com/SecurityRonin/timeglyph"
            version "${VERSION}"
            license "Apache-2.0"

            on_macos do
              if Hardware::CPU.arm?
                url "https://github.com/SecurityRonin/timeglyph/releases/download/v${VERSION}/timeglyph-${VERSION}-aarch64-apple-darwin.tar.gz"
                sha256 "${ARM64_MACOS}"
              else
                url "https://github.com/SecurityRonin/timeglyph/releases/download/v${VERSION}/timeglyph-${VERSION}-x86_64-apple-darwin.tar.gz"
                sha256 "${X86_64_MACOS}"
              end
            end

            on_linux do
              if Hardware::CPU.arm?
                url "https://github.com/SecurityRonin/timeglyph/releases/download/v${VERSION}/timeglyph-${VERSION}-aarch64-unknown-linux-musl.tar.gz"
                sha256 "${ARM64_LINUX}"
              else
                url "https://github.com/SecurityRonin/timeglyph/releases/download/v${VERSION}/timeglyph-${VERSION}-x86_64-unknown-linux-musl.tar.gz"
                sha256 "${X86_64_LINUX}"
              end
            end

            def install
              bin.install "timeglyph"
              # The macOS archive also carries the lens GUI (Linux is CLI-only).
              bin.install "timeglyph-lens" if OS.mac?
            end

            test do
              assert_match "timeglyph", shell_output("#{bin}/timeglyph --version")
              assert_match "2020-01-01", shell_output("#{bin}/timeglyph decode unix 1577836800")
            end
          end
          FORMULA

          # Remove leading whitespace from heredoc
          sed -i 's/^          //' Formula/timeglyph.rb

      - name: Commit and push
        run: |
          VERSION="${{ steps.get-version.outputs.version }}"
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add Formula/timeglyph.rb
          git diff --cached --quiet && echo "No changes to commit" && exit 0
          git commit -m "timeglyph: update to v${VERSION}"
          git push

What it does, in order: reads the version from the dispatch payload (or from a manual workflow_dispatch input — a convenience trigger worth having, so you can re-run any version by hand), checks out the tap, downloads the release's checksums.txt (the release workflow already computed every asset's digest — no need to re-download the tarballs and hash them here), extracts the four digests, writes a fresh Formula/timeglyph.rb, then commits and pushes. The git diff --cached --quiet guard makes a re-run of an already-applied version a clean no-op instead of an empty-commit failure.

One subtlety in that heredoc. The shell variables (${VERSION}, ${ARM64_MACOS}) must be expanded, so the heredoc marker is unquoted. But #{bin} and #{version} inside the Ruby test block are Homebrew interpolations, not shell ones — they have to reach the file literally. An unquoted heredoc leaves #{...} alone (the shell only touches $-prefixed names), so this works as written. The sed afterwards strips the ten-space YAML indent from every line, because the heredoc body is indented to sit inside the workflow file but the committed formula must start at column zero. Either way, run the handler once on a real tag and read the committed file to confirm the hashes, the indentation, and the literal #{version} all survived.

Checkpoint: push a new tag to the app repo, watch release.yml run its dispatch step, then watch the update-timeglyph workflow appear and run in the tap. The result is a new commit on the tap bumping the formula.

Footgun 1 — a shared event type fires the wrong project's updater

repository_dispatch routes purely on the event_type string. If two projects both dispatch update-formula, both handler workflows fire on every dispatch — so your timeglyph release triggers the other-tool updater, which dutifully rebuilds other-tool's formula from other-tool's latest release. Nothing errors. The wrong formula just churns, and the right one might too, and you spend an afternoon wondering why.

The fix is mechanical: one event type per project, named after the project, and a handler whose types: filter matches exactly that string.

App timeglyph dispatches update-timeglyph → tap workflow update-timeglyph.yml listens for update-timeglyph.
App other-tool dispatches update-other-tool → tap workflow update-other-tool.yml listens for update-other-tool.

Distinct strings, distinct handlers, no crosstalk. The tap can hold a dozen handler workflows; each one only wakes for its own event.

Footgun 2 — the dispatching bot needs write access, or it 403s silently

repository_dispatch is a write operation against the tap. The default GITHUB_TOKEN in your app's release.yml is scoped to the app repo — it has no permission on the separate tap repo. Use it to dispatch to the tap and GitHub returns 403 Forbidden and does nothing. Here's the trap: a bare curl that gets a 403 still exits 0 by default, so the release job stays green. The release looks shipped. The tap never moves.

The fix is a credential that genuinely has write access to the tap:

Create a fine-grained personal access token (or a classic PAT with repo scope) on an account that is a write collaborator on SecurityRonin/homebrew-tap. For a fine-grained token, scope it to the homebrew-tap repository with Contents: read and write.
Store it as a secret in the app repo named TAP_GITHUB_TOKEN (per the map's advice, prefer an organization secret so every app that dispatches inherits it and rotation is one update). Reference it as ${{ secrets.TAP_GITHUB_TOKEN }} in the dispatch step.
Confirm write access before trusting it. Run the dispatch curl manually with -i to see the status line:

   curl -i -X POST \
     -H "Authorization: Bearer <the-token>" \
     https://api.github.com/repos/SecurityRonin/homebrew-tap/dispatches \
     -d '{"event_type":"update-timeglyph"}'

A working token returns 204 No Content. A 403 means the token's account isn't a write collaborator on the tap, or the token's scope doesn't include Contents: write. Fix that before you rely on it — and add --fail to the curl in your workflow so a future 403 turns the release red instead of hiding.

Verify it actually worked

Don't trust green. Confirm the end-to-end path with commands a user would run:

brew untap SecurityRonin/tap 2>/dev/null   # start clean
brew install SecurityRonin/tap/timeglyph
brew audit --strict SecurityRonin/tap/timeglyph
timeglyph --version

brew install SecurityRonin/tap/timeglyph resolving and downloading proves the tap, the formula name, the url, and the sha256 all line up.
brew audit --strict passing proves the formula meets Homebrew's own conventions — the thing that would block it from a future official submission.
timeglyph --version printing the version you just released proves the binary inside the tarball is the right one, installed on PATH.

Then, separately, confirm the automation: push a fresh tag to the app, wait for release.yml to finish, and check the tap for a new commit bumping the formula. Open the committed Formula/timeglyph.rb and read the version and all four sha256 lines — they should match the new release's assets. A green workflow is necessary but not sufficient; the proof is the formula file changed and still installs.

Shipping a GUI cask, not just a CLI formula

Everything above ships a CLI as a formula — brew install SecurityRonin/tap/timeglyph — and needs no signing at all. Files Homebrew fetches with curl and unpacks are never quarantined, and a command-line tool run from a terminal never triggers Gatekeeper's notarization check. That is the entire reason an unsigned CLI formula just works. No Apple account, nothing.

There is a middle ground worth knowing: timeglyph's own GUI, the timeglyph-lens overlay, ships inside the formula as a second plain binary (bin.install "timeglyph-lens" if OS.mac?). Launched from the terminal like any CLI, it stays on the no-signing path above. That trick holds exactly as long as you don't need a real .app bundle in /Applications.

A .app is the other case. When your tool grows into a double-clickable desktop app, you ship it as a cask — brew install --cask yourorg/tap/yourapp — and a cask installs a .app. A .app installed by a cask is quarantined (com.apple.quarantine) and launched from Finder, so it hits the full Gatekeeper wall. On Apple Silicon an unsigned or ad-hoc-signed app shows the harsh "'App' is damaged and can't be opened" message — not the milder "unidentified developer" with a right-click→Open escape. Homebrew is also dropping support for unsigned casks (2026-09-01), so signing the app isn't optional if you want the cask to survive.

What is not enough (learn this before you waste a release):

Ad-hoc / linker signature — the arm64 linker auto-applies Signature=adhoc, TeamIdentifier=not set. spctl -a -t exec -vvv still says rejected. The app runs on your Mac (no quarantine there) but is blocked on anyone's download.
Developer-ID-signed but not notarized — also blocked, since macOS Catalina. Signing alone is insufficient; notarization is a separate Apple-side scan.

So a cask needs the full chain: Developer ID Application signature → notarize → staple. That needs an Apple Developer Program membership.

If you have been through winget from zero, this is the same wall on a different OS. Gatekeeper is macOS playing the role SmartScreen plays on Windows, and Developer ID + notarization is the counterpart of Authenticode via Azure Trusted Signing: an unsigned artifact gets the scary block, a signed one from a validated organization sails through, and in both cases the check happens on the user's machine against the downloaded bytes — which is why an app that runs fine locally proves nothing. The paperwork even overlaps: the D-U-N-S number Dun & Bradstreet issued your organization for Azure's identity validation is the same one Apple's org enrollment asks for. One legal identity, validated once per platform, signs everything you ship.

One-time setup

Apple Developer Program ($99/yr). Enroll as the organization (the same legal name you use for any other platform's publisher identity — one identity everywhere). Org enrollment needs a D-U-N-S number (free from D&B, ~1–5 business days) and legal-entity verification. Note your Team ID (10 chars, e.g. AB12CD34EF). (Individual enrollment is faster but ships under a person's name.)
Developer ID Application certificate. developer.apple.com → Certificates → + → Developer ID Application → do the CSR dance in Keychain Access. Then export the cert and its private key as a .p12 with a strong password. Your identity string is Developer ID Application: Your Org (TEAMID).
Notarization API key. appstoreconnect.apple.com → Users and Access → Integrations → App Store Connect API → + → role Developer → download the AuthKey_XXXX.p8 (you get it once). Record the Key ID and the Issuer ID (a UUID on that page). An API key beats an Apple-ID + app-specific-password because there's no 2FA to babysit in CI.
Store six secrets (base64 the binary ones):

Secret	Value
`MACOS_CERT_P12_BASE64`	`base64 -i cert.p12`
`MACOS_CERT_PASSWORD`	the `.p12` export password
`MACOS_SIGN_IDENTITY`	`Developer ID Application: Your Org (TEAMID)`
`MACOS_NOTARY_KEY_P8_BASE64`	`base64 -i AuthKey_XXXX.p8`
`MACOS_NOTARY_KEY_ID`	the API Key ID
`MACOS_NOTARY_ISSUER_ID`	the API Issuer ID (UUID)

A nice pattern: gate the macOS signing steps on secrets.MACOS_CERT_P12_BASE64 != ''. CI stays green before you've enrolled (the .app ships unsigned and the cask waits as a draft PR); the moment all six secrets exist, the next release signs automatically. No workflow edit to "turn it on."

The CI signing flow (macOS runner)

# 1. import the .p12 into a temporary keychain (delete it in a trap)
# 2. sign with the hardened runtime + a secure timestamp:
codesign --force --deep --options runtime --timestamp \
  --sign "Developer ID Application: Your Org (TEAMID)" "YourApp.app"
codesign --verify --deep --strict --verbose=2 "YourApp.app"
# 3. notarize (Apple scans it, ~1–5 min) — API key, not Apple ID:
xcrun notarytool submit "YourApp.app.zip" \
  --key AuthKey.p8 --key-id "$KEY_ID" --issuer "$ISSUER_ID" --wait
# 4. staple the ticket so offline Gatekeeper checks pass:
xcrun stapler staple "YourApp.app"
# 5. ditto-zip the stapled .app for the cask

Verify a shipped release the way a user's Mac will, not the way yours does:

codesign --verify --deep --strict --verbose=2 /Applications/YourApp.app
spctl -a -t exec -vvv /Applications/YourApp.app   # → "accepted, source=Notarized Developer ID"
xcrun stapler validate /Applications/YourApp.app

The trap mirrors the sha256 checkpoint above: an app that launches on your own Mac proves nothing about a quarantined download on someone else's. Green locally is not green on download — always check spctl on the shipped artifact, and "accepted, source=Notarized Developer ID" is the only pass.

What bit me, and the fix

What bit me	The fix
Made one tap per tool, install commands all different	One shared `homebrew-tap`; every tool is `brew install yourorg/tap/<tool>`
Two projects shared event type `update-formula`; one release fired the other's updater	One event type per project (`update-timeglyph`), handler `types:` filter matches it exactly
Dispatch returned 403 from a read-only token; release stayed green, tap never updated	PAT with Contents: write on the tap, stored as a secret; add `--fail` so a 403 turns the release red
`brew install` failed on sha256	Hashed the wrong file — `curl -L` (follow redirects) and hash the right architecture's asset
Class name didn't match file name	`report-cli.rb` → `class ReportCli`; hyphens drop, words capitalize
`curl` hashed a redirect page, not the tarball	Add `-L`; verify the downloaded file is megabytes, not bytes
Heredoc ate the Ruby `#{version}` in the test block	Quote the heredoc marker or inject shell values with `sed`; read the committed file to confirm the literal survived

Once the seed formula installs and the dispatch path is proven, Homebrew costs you nothing per release: the tag fires release.yml, release.yml dispatches update-timeglyph, the handler rewrites the formula, and a Mac user's brew install and brew upgrade pick up the new version on their own.

The Half of Rust Nobody Teaches: Shipping

Albert Hui — Wed, 24 Jun 2026 00:24:34 +0000

Every Rust tutorial ends the same way: cargo build --release, a victory screenshot of a binary running in a terminal, the end. The Book, the YouTube series, the "build X in Rust" posts — all of them stop at the moment the code works on the author's laptop.

That is roughly the halfway point.

The other half — turning a binary that works for you into something a stranger can brew install on a Mac, winget install on Windows, or apt install on Ubuntu, that updates itself, carries a version number that means something, and ships without you babysitting it — is a discipline of its own. It is closer to product management than to programming, and almost nobody writes it down. So here it is: the shipping half, from a real multi-crate app distributed across five platforms and four package managers.

Consider this the map. Each leg below — the architecture, the one-tag workflow, every package manager, the build cache, the cross-compile traps — is a deep-dive of its own, and each gets its own post in this series. Here we walk the whole territory at altitude, so the pieces connect before you zoom into any one of them. If you only read one thing about shipping Rust, read this; if you're about to do it, follow the per-topic posts as they land.

Architecture first: one big app is many small crates

The instinct for a large Rust app is one giant crate. Resist it. The pattern that scales is a fleet: a family of small, single-purpose library crates, each a deep expert in one thing, plus a thin application crate on top that wires them together.

Two rules make this work:

One concern per crate, with an honest name. A crate name is read bare — in cargo add, in a dependency list, on crates.io search — stripped of all repo context. mft-core tells you what it is; utils does not. If your short prefix is distinctive (memf-, winevt-) it can stand alone; if it is a generic word (browser-), keep the full descriptive prefix so the name claims a namespace by itself.

Depend down, never sideways or up. Draw the layers and let dependencies only point downward. The app at the top imports everything; the leaf at the bottom imports nothing. When that arrow ever points the wrong way, you have found a design bug, not an inconvenience.

Arrows mean "depends on" — they only ever point down.

Two policies pay for themselves later:

Batteries-included binaries. A user in the field cannot cargo build --features gpu,cloud on their machine. Compile every capability in. If a heavy dependency trips a license or dependency gate, fix the gate, not the feature set — amputating capability to slim a build ships a tool that silently can't do the thing.
Lean core, full binary. When one crate is both a heavy end-user tool and something other libraries link for one primitive, split it: a lean <x>-core with just the primitives (no GPU, no cloud), and the full <x> binary that depends on it. Libraries link the lean core; the app stays batteries-included. One default can't be both lean-for-libraries and full-for-the-binary — the split is the answer, not feature juggling.

None of this is visible in a tutorial because a tutorial has one crate and no consumers. At fleet scale it is the whole game.

One tag ships everything

Here is the goal, and it is worth being strict about: a single signed git tag produces every artifact, on every platform, in every channel.

git tag -s v0.3.0 -m "v0.3.0"
git push origin v0.3.0

That tag triggers one release.yml workflow that fans out to every platform and channel:

Nothing else produces a release. If a repo's "tag" shows only GitHub's auto-generated source tarball, the workflow did not run — that auto-tarball is not the release. The discipline is: one tag in, a full release out, and you verify it actually produced binaries before telling anyone it shipped. A green push is not a green deploy.

The build matrix is the spine:

matrix:
  include:
    - { target: aarch64-apple-darwin,        os: macos-latest }
    - { target: x86_64-apple-darwin,         os: macos-15 }
    - { target: x86_64-unknown-linux-musl,   os: ubuntu-latest }
    - { target: aarch64-unknown-linux-musl,  os: ubuntu-latest }
    - { target: x86_64-pc-windows-msvc,      os: windows-latest }

The channels, and the part each one will bite you on

GitHub Releases

The easy one, and the only one that needs zero external secrets — the built-in GITHUB_TOKEN is enough to attach binaries + checksums. If all you ever do is publish executables, you can stop here. Everything below is for reaching people who never visit your Releases page.

crates.io

cargo publish, in dependency order, bottom of the graph up. Two rules:

A version publishes once. Bump the version before every release tag; a tag whose publish job re-pushes an existing version fails "already exists." Re-tagging the same vX.Y.Z is only safe if the publish job never ran.
Prefer the published registry crate over a path dependency the moment it is on crates.io. Path deps are for unpublished, in-flight work. Once your crate is published, switch dependents to version = "0.2" so the build is reproducible and decoupled from your local checkout layout.

For an application crate that depends on dozens of internal path crates, crates.io publishing simply does not apply — an app ships as a binary, not a crate. Don't fight it; skip the publish job for the app and let the binary channels carry it.

Homebrew

One shared tap for the whole fleet (brew install yourorg/tap/yourtool). The trap that costs an afternoon: each project must dispatch its own event type (update-yourtool) to a matching handler workflow in the tap. Share a generic update-formula event between two projects and the second project's release fires the first project's updater. And the bot that dispatches needs write access on the tap — repository_dispatch from a read-only collaborator returns 403, silently.

winget

The single most surprising one: the winget-releaser action cannot create a new package — it only bumps an existing one. So your first version is a manual submission (hand-author three YAML manifests, open a PR to microsoft/winget-pkgs), and every release after that auto-PRs. Make the winget job continue-on-error: true until that first manual PR merges, or it fails every release for no reason. Two more: keep the MSI's UpgradeCode stable across versions (winget keys upgrades off it), and pull the ProductCode fresh each release (it changes every build).

apt, via Cloudsmith

.deb packages built with cargo-deb, pushed to a Cloudsmith repo, installed by users with:

curl -1sLf https://dl.cloudsmith.io/public/yourorg/yourrepo/setup.deb.sh | sudo bash

The gotcha is a 404: the Cloudsmith repo must exist before the first push. Create it in the dashboard first; the workflow won't create it for you.

The gotchas that are actually the product-management lessons

These are the ones that don't appear in any "build a CLI in Rust" post, because they only exist once real people on real platforms install your thing.

E0463: can't find crate for core on cross-compiles. This means a rust-toolchain.toml pin is overriding the toolchain your CI action installed, so the cross-target landed on the wrong toolchain. Pin the action to the same version as the toml. It fails in ~20 seconds, before any real compilation, and a native cargo publish --dry-run will never catch it.

cargo-deb errors "must have a copyright or authors property." Add authors = [...] to [package]. One line, and it is the entire difference between a green and a red release.

cargo-wix in a workspace where the binary is a member crate. The trailing positional argument is parsed as the path to Cargo.toml, not the wxs input — so cargo wix ... wix/main.wxs errors "does not appear to be a Cargo.toml file." Use --package <crate> --include wix/main.wxs with repo-root-relative Source= paths in the wxs. (And WiX is Windows-only; package the MSI on a Windows runner.)

Heavy C/C++ dependencies don't cross-compile to musl for free. A bundled C++ engine (an embedded database, say) needs a C++ cross-compiler — and apt's musl-tools ships musl-gcc but no musl-g++. Either switch the Linux targets to -gnu, or use cargo-zigbuild so zig c++ provides the musl toolchain.

Secrets are organization-level, and a repo-level secret silently shadows them. Put your publish tokens (crates.io, the tap PAT, the winget PAT, the Cloudsmith key) as organization secrets so every repo inherits them and rotation is one update. Then delete the repo-level copies — a same-named repo secret overrides the org one, and the repo keeps using its stale local value while you wonder why the org rotation did nothing.

Commit Cargo.lock in every app/binary repo. Otherwise CI resolves a fresh dependency graph that can differ from what you tested — and a release red-herring becomes a multi-hour misdiagnosis of a perfectly good crate.

And the one about build times, because it will dominate your CI bill

A real app with a bundled C++ dependency can take 80+ minutes to compile on Windows MSVC — three times the macOS clang time, because cl.exe is slow on template-heavy C++ built as a few huge translation units. The fix is not a faster machine (those translation units don't parallelize); it is caching the build.

Swatinem/rust-cache caches target/, which includes the compiled C++ objects, so a warm build skips the recompile entirely — measured here as 84 minutes down to 14. Two things to know: it keys on the whole Cargo.lock (so any dependency bump invalidates everything, including the unchanged C++), and it keys by runner architecture, not the Rust --target — so two matrix targets on the same runner collide on one cache key unless you add key: ${{ matrix.target }}. The lock-key invalidation is the one real limitation — a dependency bump means a cold rebuild — and the obvious next move (a compiler-level cache like sccache) turned out to break this particular C++ build more than it helped, so rust-cache alone is the pragmatic answer here. The 10 GB GitHub Actions cache cap, by the way, is no longer hard — it is now a raisable, pay-as-you-go limit.

The deep-dives ahead

This was the map. Each leg is a full post of its own, landing in this series:

The fleet architecture — splitting one big app into many small crates, the depend-down discipline, and batteries-included vs. feature flags.
One tag, every artifact — the release.yml anatomy, the build matrix, and verifying a release actually shipped.
Publishing to crates.io — the lean-core/full-binary split, path-to-registry migration, and the publish-once rule.
Homebrew without the footguns — the shared tap, per-project dispatch handlers, and bot write access.
winget from zero — the manual first submission, then auto-updates, and keeping the MSI codes stable.
apt via Cloudsmith — .deb packaging and a one-line public install.
The Windows MSI — cargo-wix in a virtual workspace, packaged on a Windows runner.
Making CI builds fast — rust-cache, the cache-key collisions, the 84-to-14-minute story, and the caching layers that don't pay off.
The cross-compile traps — E0463, protoc, and musl-vs-gnu for C++ dependencies.

I'll link each here as it publishes.

Shipping is a product discipline

Here is the thing the tutorials are implicitly teaching by omission: that the code is the product. It isn't. The product is the thing a stranger installs without reading your README, that works the first time, that updates itself, and that you can release again next week without remembering 14 manual steps.

That is a product-management problem wearing an engineering costume. It has a roadmap (which channels, in what order), a definition of done (binaries verified live, not "the push was green"), a security posture (signed tags, org-scoped secrets, no insecure defaults), and a maintenance cost you pay every release. Treating it as an afterthought is why so much good Rust code never gets installed by anyone but its author.

The good news: it is almost entirely a one-time setup. Build the fleet architecture, write the one tag-driven workflow, eat the gotchas above once, and from then on shipping to five platforms and four package managers costs you exactly one signed tag. That is the half nobody teaches — and it is the half that turns code into a tool people use.