WinGet Manifest Integration

Relevant source files

The following files were used as context for generating this wiki page:

• builder/builder/sources/adapters.py
• README.md
• catalog/packages.yaml
• builder/builder/main.py
• tests/test_workflow.py

WinGet Manifest Integration enables the repo-builder to discover software versions and installer metadata by querying Microsoft’s official community repository. It identifies stable versions, filters for specific architectures, and retrieves verified SHA256 hashes to package installers into OPSI archives. This system functions entirely within the builder and does not require the WinGet client or internet access on the OPSI managed clients.

Sources: README.md:143-150

Architecture and Discovery Logic

The integration uses the GitHub REST API to navigate the microsoft/winget-pkgs repository. It traverses the directory structure based on the package_identifier defined in the catalog.

Metadata Resolution Process

1. Version Selection: The builder requests the contents of the package directory on GitHub. It parses directory names as versions, orders them semantically, and selects the latest stable version that matches optional track filters.
2. Manifest Retrieval: After selecting a version, the builder fetches the corresponding .installer.yaml file from raw.githubusercontent.com.
3. Installer Filtering: The builder iterates through the Installers list in the YAML manifest. It filters candidates based on:
   • Architecture: Must match the package architecture (defaulting to x64).
   • InstallerType: Must match configured types (e.g., msi, wix, exe).
   • Scope: Must be set to machine.
4. Data Extraction: The system extracts the InstallerUrl and the required InstallerSha256 for the download phase.

Sources: builder/builder/sources/adapters.py:108-146, README.md:143-150

Workflow Diagram

The following diagram illustrates how the WinGet adapter resolves a release.

Configuration Parameters

Packages utilizing this integration must set source.type to winget_manifest in catalog/packages.yaml.

Parameter	Type	Description
package_identifier	String	The official WinGet ID (e.g., Google.Chrome).
installer_types	List	Allowed types like msi, wix, exe, inno, nullsoft.
allowed_hosts	List	Hostnames permitted for installer downloads.
track	String	Optional version prefix filter (e.g., 3.14).
disable_host_validation	Boolean	If true, permits redirects to external mirrors.
allowed_url_prefixes	List	Restricts installer URLs to verified project paths.

Sources: catalog/packages.yaml:57-73, README.md:118-121, builder/builder/sources/adapters.py:117-124

Security and Validation

The WinGet integration enforces strict security boundaries to prevent the use of malicious or untrusted installers.

• Hash Enforcement: The builder requires an InstallerSha256 from the manifest. It validates the downloaded file against this hash; if they disagree, the build fails.
• Host Pinning: Every InstallerUrl must belong to the allowed_hosts list. If a vendor redirects to an unlisted host, the process fails unless disable_host_validation is explicitly enabled.
• URL Prefixing: For shared platforms like GitHub, allowed_url_prefixes ensures the installer comes from the verified project path rather than an arbitrary repository.
• Argument Integrity: The builder uses silent_args defined in the local catalog instead of executing commands found in the WinGet manifest.

Sources: README.md:118-124, README.md:143-150, builder/builder/sources/adapters.py:148-154

Implementation Example

The following snippet demonstrates the resolution logic used to parse the WinGet repository structure.

# builder/builder/sources/adapters.py:112-114
identifier = s["package_identifier"]
base = "manifests/" + identifier[0].lower() + "/" + identifier.replace(".", "/")
api = "https://api.github.com/repos/microsoft/winget-pkgs/contents/" + base

The system uses a specific sequence to interact with the GitHub API and raw content servers.

Summary

WinGet Manifest Integration provides a robust mechanism for automated software updates by utilizing Microsoft's community-driven package metadata. By combining WinGet's version tracking with the project's local security policies—such as host allowlisting and local argument definition—the system ensures that only verified, machine-wide installers are packaged for the OPSI repository.