Build native-feeling installers from one YAML manifest.

What PolyInstall does

PolyInstall turns a YAML manifest into one or more self-contained installer binaries. It is designed for product teams, open-source maintainers, and internal platform engineers who need a repeatable packaging flow without adopting a different installer authoring system for every operating system.

Before you install

The recommended path is to download a release build of the CLI. Release archives are self-contained, so users do not need the .NET SDK just to build installers from manifests.

Install and configure PolyInstall

Use the release build when you want to package an application. Build from source only when contributing, testing unreleased changes, or publishing custom runtime stubs.

# Example layout after extraction
polyinstall/
  polyinstall      # or polyinstall.exe on Windows
  schema/v1.json
  stubs/
    win-x64/       # host RID stub included with a win-x64 CLI archive

# Optional: extract separate stubs-linux-x64-<tag>.zip or stubs-osx-arm64-<tag>.zip
# under the same stubs/ root when building those targets from this host.

# PowerShell example for the current session
$env:PATH = "C:\Tools\polyinstall;$env:PATH"

# Confirm the command is visible
polyinstall validate .\manifest.yaml

# yaml-language-server: $schema=https://bolorundurowb.github.io/PolyInstall/schema/v1.json

polyinstall validate manifest.yaml --base ./release-input
polyinstall build manifest.yaml --base ./release-input

Build from source

Contributors can build the CLI and publish runtime stubs directly from the repository.

git clone https://github.com/bolorundurowb/PolyInstall.git
cd PolyInstall

dotnet restore src/PolyInstall.slnx
dotnet build src/PolyInstall.slnx -c Release --no-restore

# Publish a Windows runtime stub and uninstaller
dotnet publish src/PolyInstall.Runtime/PolyInstall.Runtime.csproj -c Release -r win-x64 -o stubs/win-x64
dotnet publish src/PolyInstall.Uninstall/PolyInstall.Uninstall.csproj -c Release -r win-x64 -o stubs/win-x64

# Build the sample installer
dotnet run --project src/PolyInstall.Cli/PolyInstall.Cli.csproj -- build examples/polyinstall.sample.yaml --base examples --stubs stubs

Build your first installer

This example packages a tiny application directory and creates a Windows x64 installer. It is intentionally small, so you can validate the full build loop in minutes.

mkdir -p hello-payload
printf "Hello from PolyInstall\n" > hello-payload/hello.txt

# yaml-language-server: $schema=https://bolorundurowb.github.io/PolyInstall/schema/v1.json
metadata:
  name: HelloPoly
  version: 0.1.0
  publisher: Example Ltd

build:
  output_dir: dist
  compression: brotli
  targets:
    - windows-x64
  windows:
    install_scope: user
    register_arp: true

ui:
  theme: system
  wizard_steps:
    - type: welcome
      title: Welcome to HelloPoly
    - type: destination
      title: Choose an install location
      default_path: "{UserHome}/HelloPoly"
    - type: progress
      title: Installing HelloPoly
    - type: finish
      title: Installation complete

files:
  - source_dir: hello-payload
    include:
      - "**/*"

polyinstall validate manifest.yaml --base .
polyinstall build manifest.yaml --base .

# Windows output
dist/HelloPoly-windows-x64.exe

Use the full manifest surface

PolyInstall supports multi-target builds, platform-specific packaging, wizard customisation, lifecycle tasks, glob filtering, custom output names, optional signing, environment variable substitution, and install-state tracking.

Complete multi-platform manifest

This manifest demonstrates advanced build options, glob filtering, environment substitution, branding, and OS-gated tasks.

# yaml-language-server: $schema=https://bolorundurowb.github.io/PolyInstall/schema/v1.json
metadata:
  name: Contoso Studio
  version: "${APP_VERSION:-1.0.0}"
  id: com.contoso.studio
  publisher: Contoso Ltd

build:
  output_dir: dist
  output_name: "{name}-{version}-{target}"
  compression: brotli
  targets:
    - windows-x64
    - linux-x64
    - osx-arm64
  windows:
    install_scope: user
    register_arp: true
  linux:
    package: appimage
  macos:
    package: dmg
  signing:
    windows:
      certificate_path: "${WINDOWS_CERT_PATH}"
      certificate_password_env: WINDOWS_CERT_PASSWORD
      timestamp_url: "http://timestamp.digicert.com"
    macos:
      identity: "Developer ID Application: Contoso Ltd"
      keychain: "${MACOS_KEYCHAIN_PATH}"
      notarization_profile: "polyinstall-notary"

ui:
  theme: system
  logo_path: "branding/contoso-logo.svg"
  wizard_steps:
    - type: welcome
      title: Welcome to Contoso Studio
    - type: eula
      title: Licence agreement
      source: "legal/LICENCE.txt"
    - type: destination
      title: Choose where to install
      default_path: "{ProgramFiles}/Contoso Studio"
    - type: progress
      title: Installing
    - type: finish
      title: Ready to launch

files:
  - source_dir: app
    include:
      - "**/*"
    exclude:
      - "**/*.pdb"
      - "**/*.map"
      - "**/tmp/**"
  - source_dir: packaging
    include:
      - "branding/**"
      - "legal/**"

file_associations:
  - extension: ".cstudio"
    description: "Contoso Studio project"
    prog_id: "ContosoStudio.Project.1"
    icon: "{AppDir}\\branding\\contoso.ico"
    command: '"{AppDir}\\ContosoStudio.exe" "%1"'
    mime_type: "application/x-contoso-studio"
    bundle_path: "{AppDir}/Contoso Studio.app"

tasks:
  pre_install:
    - require: os.isWindows
      action: write_registry
      parameters:
        key_path: "HKCU\\Software\\Contoso\\Studio"
        value_name: InstallStarted
        value: "true"
        value_kind: string
  post_install:
    - require: os.isWindows
      action: create_shortcut
      parameters:
        target_path: "{AppDir}\\ContosoStudio.exe"
        name: "Contoso Studio"
        location: desktop
        description: "Launch Contoso Studio"
        icon_path: "{AppDir}\\branding\\contoso.ico"
    - require: os.isWindows
      action: add_to_path
      parameters:
        path: "{AppDir}"
        scope: user
    - require: os.isLinux
      action: create_desktop_entry
      parameters:
        file_name: "contoso-studio.desktop"
        name: "Contoso Studio"
        exec: "{AppDir}/ContosoStudio"
        icon: "{AppDir}/branding/contoso.png"
        comment: "Launch Contoso Studio"
    - require: os.isUnix
      action: set_permissions
      parameters:
        path: "{AppDir}/ContosoStudio"
        mode: 755
  pre_uninstall:
    - require: os.isWindows
      action: write_registry
      parameters:
        key_path: "HKCU\\Software\\Contoso\\Studio"
        value_name: UninstallStarted
        value: "true"
        value_kind: string

Shortcut and file association behaviour

Shortcut names are display names, not full destination paths. PolyInstall chooses the correct desktop or Start Menu directory from location and optional subfolder, then combines it with name. On Windows, .lnk is appended automatically when name does not already end with it; name: "Contoso Studio" and name: "Contoso Studio.lnk" both produce a single Contoso Studio.lnk file. Prefer omitting .lnk in manifests so the same task reads naturally on Linux and macOS.

tasks:
  post_install:
    - require: os.isWindows
      action: create_shortcut
      parameters:
        target_path: "{AppDir}\\ContosoStudio.exe"
        name: "Contoso Studio"        # Do not include .lnk unless you need to be explicit.
        location: start_menu          # start_menu or desktop
        subfolder: "Contoso"
        description: "Launch Contoso Studio"
        icon_path: "{AppDir}\\branding\\contoso.ico"

File associations should normally be declared with top-level file_associations entries. Use a leading dot in extension, choose a stable prog_id that will not change between releases, include the icon file in your payload, and quote %1 in the open command so paths with spaces work correctly. If prog_id is omitted, PolyInstall derives one from the app name and extension, but explicit values are clearer for long-lived products.

file_associations:
  - extension: ".cstudio"
    description: "Contoso Studio project"
    prog_id: "ContosoStudio.Project.1"
    icon: "{AppDir}\\branding\\contoso.ico"
    command: '"{AppDir}\\ContosoStudio.exe" "%1"'
    mime_type: "application/x-contoso-studio"     # Linux; optional if the derived type is fine.
    bundle_path: "{AppDir}/Contoso Studio.app"    # macOS; required for macOS associations.

Use the file_association task action only when an association must be created conditionally in a lifecycle phase. Top-level associations are easier to read, participate in feature selection, and are registered after files are copied.

Platform packaging notes

Optional installer signing

Signing is opt-in. If build.signing is omitted, PolyInstall produces unsigned installers. If you configure a platform signing block, the build validates that the required identity reference is present and signs only the matching platform artifacts. Do not put plaintext private keys or account passwords in YAML.

build:
  signing:
    windows:
      certificate_thumbprint: "0123456789abcdef..."
      store_name: My
      store_location: current_user
      timestamp_url: "http://timestamp.digicert.com"
    macos:
      identity: "Developer ID Application: Example Corp"
      keychain: "${MACOS_KEYCHAIN_PATH}"
      notarization_profile: "polyinstall-notary"

What can be used together?

Environment variable substitution

During build and validate, string values support ${VAR} and ${VAR:-default}. This is useful in CI, but avoid embedding secrets because the generated manifest is stored inside the installer binary.

metadata:
  version: "${GITHUB_REF_NAME:-0.0.0-local}"

build:
  output_dir: "${DIST_DIR:-dist}"

Command reference

polyinstall build <manifest.yaml> [--base <dir>] [--stubs <dir>]
polyinstall validate <manifest.yaml> [--base <dir>]

Build installers in CI

Use GitHub Actions to validate manifests on pull requests and build release installers from the same YAML file you use locally. The project includes a reusable setup action that downloads a PolyInstall release, verifies its checksum, extracts it, and adds polyinstall to PATH.

Validate manifests on pull requests

A lightweight validation workflow catches schema mistakes, missing payload paths, invalid shortcut parameters, and incompatible task/platform settings before a release job tries to package artifacts.

name: Validate installer manifest

on:
  pull_request:
    paths:
      - "installer/**"
      - ".github/workflows/installer.yml"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: bolorundurowb/PolyInstall/.github/actions/setup-polyinstall@v2.0.1
        with:
          version: v2.0.1
          github-token: ""

      - name: Validate manifest
        run: polyinstall validate installer/manifest.yaml --base installer

Build and upload installers

Use a matrix when you want separate artifacts per target. The example below sets APP_VERSION from the tag name so manifests can use ${APP_VERSION:-0.0.0-local} without hard-coding release versions. For per-target matrix builds, set build.targets in the manifest to a substituted value such as "${POLYINSTALL_TARGET:-windows-x64}".

name: Build installers

on:
  push:
    tags:
      - "v*"
  workflow_dispatch:

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include:
          - runner: windows-latest
            rid: win-x64
            target: windows-x64
            artifact: installer-windows-x64
          - runner: ubuntu-latest
            rid: linux-x64
            target: linux-x64
            artifact: installer-linux-x64
          - runner: macos-14
            rid: osx-arm64
            target: osx-arm64
            artifact: installer-osx-arm64

    runs-on: ${{ matrix.runner }}
    steps:
      - uses: actions/checkout@v4

      - uses: bolorundurowb/PolyInstall/.github/actions/setup-polyinstall@v2.0.1
        with:
          version: v2.0.1
          rid: ${{ matrix.rid }}
          github-token: ""

      - name: Validate manifest
        env:
          POLYINSTALL_TARGET: ${{ matrix.target }}
        run: polyinstall validate installer/manifest.yaml --base installer

      - name: Build installer
        env:
          APP_VERSION: ${{ github.ref_name }}
          POLYINSTALL_TARGET: ${{ matrix.target }}
        run: polyinstall build installer/manifest.yaml --base installer

      - name: Upload installer artifacts
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.artifact }}
          path: installer/dist/**

Manifest options in detail

PolyInstall manifests are YAML documents that validate against the published schema at https://bolorundurowb.github.io/PolyInstall/schema/v1.json. Think of a manifest as the recipe for your installer: it names the product, chooses where output files go, describes the installer screens, selects the files to copy, and optionally runs setup tasks.

# yaml-language-server: $schema=https://bolorundurowb.github.io/PolyInstall/schema/v1.json

Root object

The root object groups product metadata, build settings, UI flow, payload selection, optional integrations, and lifecycle behaviour. Use these links when you see a field in a sample manifest and want to understand what it controls.

metadata

metadata describes the product you are packaging. These values appear in generated filenames, installer text, and platform integration such as Windows Add/Remove Programs.

build

build controls what PolyInstall creates. This is where you choose output folders, compression, target operating systems, and optional native packaging formats.

build.signing

build.signing is optional. It is validated only when present, so unsigned installers require no signing configuration. Platform signing blocks should reference existing certificate stores, files, keychains, or CI secrets rather than storing credentials in the manifest.

ui

ui controls the install wizard the user sees. It is about presentation and flow, not which files are packaged. File selection happens in files.

wizard_steps entries

Each wizard step is one screen. The order in the manifest is the order the user sees.

files entries

files tells PolyInstall what to place inside the installer. Each entry starts at one source directory, includes matching files, and then removes anything matched by exclude.

file_associations entries

Top-level file_associations entries register document extensions after installation. They are easier to maintain than platform-specific registry or desktop-database tasks, and they can be gated by optional features in the same way as file groups and tasks.

file_associations:
  - extension: ".cstudio"
    description: "Contoso Studio project"
    prog_id: "ContosoStudio.Project.1"
    icon: "{AppDir}\\branding\\contoso.ico"
    command: '"{AppDir}\\ContosoStudio.exe" "%1"'

tasks

Lifecycle task arrays are optional. Install tasks run around file copy. Uninstall tasks run while installed files are still present, so they can stop services, remove shortcuts, or clean configuration before the install tree is deleted. A complete novice can ignore tasks until the installer needs to change the system outside the install folder.

InstallTask entries

Task action parameters

Common issues

Most build failures come from missing stubs, schema mismatches, host-specific packaging tools, or file globs that do not match the intended payload directory.

Help improve PolyInstall

PolyInstall welcomes focused issues, documentation improvements, tests, and implementation changes that keep the manifest contract, generated schema, CLI behaviour, and runtime behaviour aligned.

Contributor workflow

git clone https://github.com/bolorundurowb/PolyInstall.git
cd PolyInstall

dotnet restore src/PolyInstall.slnx
dotnet build src/PolyInstall.slnx -c Release --no-restore
dotnet test src/PolyInstall.slnx -c Release --no-build --verbosity normal