Skip to content
UmbraUmbra

Release process

View as Markdown

For maintainers. The repo also has a release skill and a release-manager agent under .claude/ that walk through this.

Cutting a release

Section titled “Cutting a release”
  1. Bump the version in Directory.Build.props (one version for Umbra.exe, umbractl.exe and the installer).
  2. Write the notes from the merged pull requests.
  3. Tag vX.Y.Z and push the tag.
  4. .github/workflows/release.yml builds and attaches UmbraSetup-<version>.exe (and the portable zip) to the GitHub release.
  5. Verify the release assets: the installer’s name must be UmbraSetup-<release version>.exe, because that’s what the self-updater requires.

There’s also a release-checklist skill that builds a filled checklist (build, install tests, human checks gathered from merged PRs, ship steps).

Signing

Section titled “Signing”

release.yml signs the installer with signtool only if the repo secrets SIGN_CERT_BASE64 (a code-signing .pfx, base64) and SIGN_CERT_PASSWORD exist. Otherwise it publishes it unsigned. One-time setup:

  1. Get a code-signing certificate (an OV/EV certificate from a CA, or Azure Trusted Signing / SignPath if you qualify) and export it as a .pfx.
  2. Encode it with [Convert]::ToBase64String([IO.File]::ReadAllBytes("cert.pfx")) and add the two repo secrets.
  3. The next tagged release is signed. SmartScreen reputation still builds up over time.

winget

Section titled “winget”

The release workflow also fills the manifests in winget/ with the version and SHA256 (scripts/winget.ps1) and attaches them to the workflow run as winget-manifests-<version>.

First submission (needs a person, not CI):

  1. After a release, download the winget-manifests-<version> artifact, or run powershell -File scripts/winget.ps1 -Installer dist/UmbraSetup-<version>.exe.
  2. Run wingetcreate submit <folder>, or fork microsoft/winget-pkgs and copy the three files to manifests/a/AmineChr54/Umbra/<version>/.
  3. Validate with winget validate <folder> and winget install --manifest <folder> in a clean VM, then open the pull request. Moderators must approve the first one.

Later releases repeat step 2 for each version (or use wingetcreate update AmineChr54.Umbra / winget-releaser once the package exists).

Catalog and site

Section titled “Catalog and site”

Widgets and themes are published by merging their pull requests; there’s no release step. The website (this site) is built from main by .github/workflows/pages.yml.

Section titled “Related”

Updates and installer · Dev setup