Signing an MSIX Package from CI with a Hardware Token

You will learn how to configure an automated CI/CD pipeline to sign an MSIX package for sideloading or direct distribution using OneSigner's Azure Key Vault-compatible endpoint and the OneSignTool command-line client.

Understanding the MSIX Signing Requirements

Windows only installs MSIX packages that carry a valid signature, so any package you sideload or distribute outside the Microsoft Store must be signed with a code-signing certificate whose subject matches the Publisher in the package manifest. Packages submitted to the Microsoft Store are re-signed by Microsoft, so Store submissions do not need your own signature. Since June 2023, the CA/Browser Forum mandates that all code-signing certificates—both OV and EV—must reside on certified hardware tokens, such as a YubiKey, SafeNet, or ePass2003 device. This hardware requirement creates a structural challenge for automated CI/CD pipelines running on headless build agents.

To solve this, OneSigner runs as a Windows service and GUI on a dedicated machine that stays powered on with your hardware token physically plugged into a USB port. OneSigner exposes an Azure Key Vault-compatible endpoint. Your CI agent runs OneSignTool (or AzureSignTool) against that endpoint, and OneSigner performs the signing operation with the private key that stays on the USB token. If your build environment cannot accommodate a dedicated machine with a locally attached hardware token, you may want to evaluate whether a cloud-hosted signing service better fits your organizational infrastructure.

OneSigner does not issue qualified signatures on its own; signature validity depends entirely on the certificate and hardware token issued to you by a trusted Certificate Authority. If you need to acquire a new certificate, you can review available options in the certificate catalog.

Preparing Your Build Agent and OneSigner Host

Before writing your CI pipeline script, you must configure both the OneSigner host machine and your build agent. First, install OneSigner on the dedicated Windows machine where your USB hardware token remains connected. Ensure that the hardware token's minidriver or cryptographic service provider is installed and that the Windows certificate store can read the certificate when the token is plugged in.

Next, enable the Azure Key Vault proxy in OneSigner and map your code-signing certificate to a certificate name; OneSignTool refers to the certificate by that name with -kvc. OneSigner also provides a REST API and watched folders, but for CI pipelines the Key Vault-compatible endpoint is the usual integration path. Note the local IP address or hostname of your OneSigner host machine, and ensure that your CI build agent can reach it over your internal network or via a secure tunnel.

On your build agent, make OneSignTool.exe available: it is a single executable shipped with OneSigner in C:\OneSigner\app\, with no installer or runtime to set up. You will also need your MSIX packaging tools, such as MakeAppx.exe, ready to package your application binaries into the final .msix file before the signing step executes.

Writing the CI Pipeline Signing Step

With your infrastructure connected, you can add the signing step to your CI/CD pipeline configuration file. Whether you use GitHub Actions, GitLab CI, Jenkins, or Azure Pipelines, the underlying mechanism is a command-line invocation of OneSignTool targeting your MSIX file.

OneSignTool mimics the command-line arguments of AzureSignTool, making it straightforward to swap out existing Azure Key Vault references for your local OneSigner endpoint. Below is an example command block showing how to invoke OneSignTool from a Windows build agent script:

OneSignTool sign ^
  -kvu https://signing.example.com ^
  -kva %SIGNING_TOKEN% ^
  -kvc your-certificate-name ^
  -fd sha256 ^
  -tr http://timestamp.digicert.com ^
  -td sha256 ^
  "path\to\your-application.msix"

Replace https://signing.example.com with the URL of your OneSigner instance and your-certificate-name with the certificate name you configured in the Key Vault proxy, and keep the signing token in your CI system's secret store rather than in the script. If your organization requires automated code signing without managing local hardware tokens, you can read more about architectural approaches in Automate Code Signing in CI/CD Without Cloud HSM.

Handling Package Verification and Manifest Integrity

Once the signing command executes, you must verify that the signature was correctly applied to the MSIX package before publishing the artifact to your distribution server. An invalid signature, or a certificate subject that does not match the manifest Publisher, will stop Windows from installing the package.

To check the signature on your build agent or a test machine, run signtool:

signtool verify /pa /v "path\to\your-application.msix"

Ensure the output reports that the signature is valid and that the signing certificate chains up to a trusted root authority matching your organization's issued code-signing certificate. If signtool returns an error regarding timestamp verification or untrusted roots, confirm that both the build agent and the OneSigner host can reach the timestamp authority URL specified in your signing command.

Troubleshooting Common Pipeline Failures

Automated hardware-backed signing can fail due to environmental interruptions on the host machine. If your CI pipeline hangs or returns a timeout error during the signing step, check the OneSigner Windows service logs on your host machine to determine if the hardware token dropped its connection or went into a sleep state.

Another common issue is a token that has locked itself after several incorrect PIN entries; check the token PIN saved in the signing profile before retrying, because every failed attempt uses up one of the token's retries. Ensure your USB token's power management settings in Windows Device Manager are configured to prevent the operating system from turning off the USB hub to save power. For a deeper dive into optimizing pipeline performance and handling multi-step workflows, consult OneSigner 2026.8.29: Signing Queue, Bring-Your-Own-Certificate HTTPS, and OneSignTool 2.1.

If several build agents sign at the same time, requests wait for the token, because one hardware token performs one signing operation at a time; stagger very large batches if you see timeouts. OneSigner plans differ in the number of tenants and portal users, not in signing volume. To review plan features, visit the OneSigner Plans page.

Next Steps

Set up your OneSigner host machine with your hardware token, configure OneSignTool on your build agent, and run a test build to verify your MSIX package signature.