Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

ci: Windows release files are signed through Azure Artifact Signing (#2708)

autonomousdevopsb27f8fc2fbfe
diff --git a/.github/actions/windows-signing/action.yml b/.github/actions/windows-signing/action.yml
new file mode 100644
index 000000000..3d53f7dc3
--- /dev/null
+++ b/.github/actions/windows-signing/action.yml
@@ -0,0 +1,109 @@
+name: Windows Authenticode signing
+description: >-
+ Sign every .exe and .dll under a folder that carries no signature yet, through Azure Artifact Signing, then check
+ every one of them: a valid signature, a timestamp, and ours naming the expected publisher. Files that already carry
+ a valid signature (Microsoft's ConPTY) are left as they are. Windows x64 runners only: the Artifact Signing action
+ does not run on Windows Arm, so arm64 builds are signed here too (Authenticode does not depend on the CPU).
+ docs/windows-code-signing.md has the Azure and GitHub setup this needs.
+
+inputs:
+ path:
+ description: The folder whose .exe and .dll files are signed, searched recursively
+ required: true
+ publisher:
+ description: The certificate's common name every signature we add must carry (the validated identity)
+ required: true
+ azure-client-id:
+ description: The Entra app registration that holds the Certificate Profile Signer role
+ required: true
+ azure-tenant-id:
+ description: The Entra tenant
+ required: true
+ azure-subscription-id:
+ description: The subscription that holds the Artifact Signing account
+ required: true
+ endpoint:
+ description: The Artifact Signing account's regional endpoint, such as https://eus.codesigning.azure.net/
+ required: true
+ account:
+ description: The Artifact Signing account name
+ required: true
+ profile:
+ description: The certificate profile name
+ required: true
+
+runs:
+ using: composite
+ steps:
+ # Get-AuthenticodeSignature reads, it never runs the file, so arm64 binaries are listed here on x64 too.
+ - name: List the files to sign
+ id: list
+ shell: pwsh
+ env:
+ SIGN_PATH: ${{ inputs.path }}
+ run: |
+ $ErrorActionPreference = 'Stop'
+ $files = @(Get-ChildItem -LiteralPath $env:SIGN_PATH -Recurse -File | Where-Object { $_.Extension -in '.exe', '.dll' })
+ if ($files.Count -eq 0) { throw "no .exe or .dll under $env:SIGN_PATH" }
+ $unsigned = @()
+ foreach ($file in $files) {
+ $status = (Get-AuthenticodeSignature -LiteralPath $file.FullName).Status
+ if ($status -eq 'NotSigned') { $unsigned += $file.FullName }
+ elseif ($status -eq 'Valid') { Write-Host "already signed $($file.FullName)" }
+ else { throw "$($file.FullName) has a $status signature: it was changed after it was signed" }
+ }
+ if ($unsigned.Count -eq 0) { throw "nothing under $env:SIGN_PATH needs signing: is this the unsigned build?" }
+ $list = Join-Path $env:RUNNER_TEMP 'windows-signing-files.txt'
+ Set-Content -LiteralPath $list -Value $unsigned -Encoding utf8
+ $unsigned | ForEach-Object { Write-Host "to sign $_" }
+ $delimiter = 'EOF_' + [guid]::NewGuid().ToString('N')
+ "files<<$delimiter`n$($unsigned -join "`n")`n$delimiter" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+ "list=$list" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+
+ # A short-lived token from this job's OIDC identity: no client secret exists to leak or rotate. The Entra federated
+ # credential trusts only the release environment of this repository.
+ - name: Sign in to Azure (OIDC)
+ uses: azure/login@v3
+ with:
+ client-id: ${{ inputs.azure-client-id }}
+ tenant-id: ${{ inputs.azure-tenant-id }}
+ subscription-id: ${{ inputs.azure-subscription-id }}
+
+ # The certificate lives about three days, so the RFC 3161 timestamp is what keeps a release valid afterwards.
+ - name: Sign
+ uses: azure/artifact-signing-action@v2
+ with:
+ endpoint: ${{ inputs.endpoint }}
+ signing-account-name: ${{ inputs.account }}
+ certificate-profile-name: ${{ inputs.profile }}
+ files: ${{ steps.list.outputs.files }}
+ file-digest: SHA256
+ timestamp-rfc3161: http://timestamp.acs.microsoft.com
+ timestamp-digest: SHA256
+ # Only the Azure CLI session from the login above: never a stray credential from the runner's environment.
+ exclude-environment-credential: true
+ exclude-workload-identity-credential: true
+ exclude-managed-identity-credential: true
+ exclude-azure-cli-credential: false
+
+ # The publisher, not the thumbprint: Artifact Signing issues a new certificate every few days.
+ - name: Verify every signature
+ shell: pwsh
+ env:
+ SIGN_PATH: ${{ inputs.path }}
+ SIGN_LIST: ${{ steps.list.outputs.list }}
+ PUBLISHER: ${{ inputs.publisher }}
+ run: |
+ $ErrorActionPreference = 'Stop'
+ $ours = @(Get-Content -LiteralPath $env:SIGN_LIST -Encoding utf8)
+ $failed = @()
+ foreach ($file in (Get-ChildItem -LiteralPath $env:SIGN_PATH -Recurse -File | Where-Object { $_.Extension -in '.exe', '.dll' })) {
+ $signature = Get-AuthenticodeSignature -LiteralPath $file.FullName
+ $signer = if ($signature.SignerCertificate) { $signature.SignerCertificate.GetNameInfo('SimpleName', $false) } else { '' }
+ $problem = if ($signature.Status -ne 'Valid') { "status $($signature.Status)" }
+ elseif (-not $signature.TimeStamperCertificate) { 'no timestamp' }
+ elseif ($ours -contains $file.FullName -and $signer -ne $env:PUBLISHER) { "signed by '$signer', not '$env:PUBLISHER'" }
+ if ($problem) { $failed += "$($file.FullName): $problem" } else { Write-Host "valid $signer $($file.FullName)" }
+ }
+ if ($failed.Count -gt 0) { $failed | ForEach-Object { Write-Host "::error::$_" }; throw "$($failed.Count) file(s) failed signature verification" }
+ "Signed $($ours.Count) file(s) under ``$env:SIGN_PATH`` as **$env:PUBLISHER**" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.yml
index b4898995d..45684fa69 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -220,6 +220,7 @@ jobs:
DESTINATION: ${{ needs.version.outputs.artifact_prefix }}
SCRATCH_PREFIX: ${{ needs.version.outputs.scratch_prefix }}
TEST_REUSE: ${{ inputs.test_candidate_reuse }}
+ WINDOWS_SIGNING: ${{ vars.WINDOWS_SIGNING }}
run: |
args=()
[[ "$TEST_REUSE" != true ]] || args+=(--require-candidate)
@@ -389,7 +390,7 @@ jobs:
run: bash scripts/upload-desktop-linux.sh "$VERSION"
# Each architecture on its own runner, like Linux (docs/superpowers/specs/2026-10-19-windows-installer-design.md
- # §2.2). Not signed: there is no signing service yet. The x64 job also builds harness-install.exe, one x64
+ # §2.2). sign-windows signs what these build. The x64 job also builds harness-install.exe, one x64
# program for every PC. upload-windows publishes the files from ubuntu, so these runners need no gcloud.
build-windows:
# The name desktop-release-candidate.py's check_jobs requires: without it GitHub would add the target too.
@@ -472,8 +473,92 @@ jobs:
path: windows-release/
if-no-files-found: error
- upload-windows:
+ # Authenticode through Azure Artifact Signing (docs/windows-code-signing.md), once the repository variable
+ # WINDOWS_SIGNING is `required`; until then this is skipped and Windows ships unsigned, as before. One x64 job for
+ # both architectures: the signing action does not run on Windows Arm. Each zip is opened, its .exe and .dll files
+ # signed, and written again in package-windows.ps1's layout under the same artifact name, so upload-windows and
+ # check-windows-zip.py see the shape they always have, and the published sha256 is the signed bytes'.
+ sign-windows:
needs: [version, build-windows]
+ if: vars.WINDOWS_SIGNING == 'required'
+ runs-on: windows-latest
+ timeout-minutes: 20
+ environment: release
+ env:
+ VERSION: ${{ needs.version.outputs.version }}
+ defaults:
+ run:
+ shell: pwsh
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ sparse-checkout: |
+ /.github/actions/windows-signing/
+ sparse-checkout-cone-mode: false
+ - uses: actions/download-artifact@v4
+ with:
+ pattern: desktop-windows-*
+ path: windows-release
+ - name: Open the zips
+ run: |
+ $ErrorActionPreference = 'Stop'
+ foreach ($arch in 'x64', 'arm64') {
+ $zip = "windows-release/desktop-windows-$arch/Harness-windows-$arch.zip"
+ if (-not (Test-Path -LiteralPath $zip -PathType Leaf)) { throw "$zip is missing" }
+ Expand-Archive -LiteralPath $zip -DestinationPath "windows-sign/$arch"
+ Remove-Item -LiteralPath $zip
+ }
+ Move-Item -LiteralPath 'windows-release/desktop-windows-x64/harness-install.exe' -Destination 'windows-sign/harness-install.exe'
+ - uses: ./.github/actions/windows-signing
+ with:
+ path: windows-sign
+ publisher: ${{ vars.WINDOWS_SIGNING_PUBLISHER || 'AUTONOMOUS INC.' }}
+ azure-client-id: ${{ vars.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ vars.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+ endpoint: ${{ vars.SIGNING_ENDPOINT }}
+ account: ${{ vars.SIGNING_ACCOUNT }}
+ profile: ${{ vars.SIGNING_PROFILE }}
+ # The same entries package-windows.ps1 writes: files only, relative, with forward slashes.
+ - name: Write the signed zips
+ run: |
+ $ErrorActionPreference = 'Stop'
+ Add-Type -AssemblyName System.IO.Compression
+ Add-Type -AssemblyName System.IO.Compression.FileSystem
+ foreach ($arch in 'x64', 'arm64') {
+ $stage = (Resolve-Path -LiteralPath "windows-sign/$arch").Path.TrimEnd([char[]]@('\', '/')) + '\'
+ $zip = Join-Path (Resolve-Path -LiteralPath "windows-release/desktop-windows-$arch").Path "Harness-windows-$arch.zip"
+ $archive = [System.IO.Compression.ZipFile]::Open($zip, [System.IO.Compression.ZipArchiveMode]::Create)
+ try {
+ foreach ($file in Get-ChildItem -LiteralPath $stage -Recurse -File -Force) {
+ $entry = $file.FullName.Substring($stage.Length).Replace('\', '/')
+ [System.IO.Compression.ZipFileExtensions]::CreateEntryFromFile(
+ $archive, $file.FullName, $entry, [System.IO.Compression.CompressionLevel]::Optimal
+ ) | Out-Null
+ }
+ } finally {
+ $archive.Dispose()
+ }
+ Write-Output "$zip $((Get-FileHash -LiteralPath $zip -Algorithm SHA256).Hash.ToLowerInvariant())"
+ }
+ Move-Item -LiteralPath 'windows-sign/harness-install.exe' -Destination 'windows-release/desktop-windows-x64/harness-install.exe'
+ - uses: actions/upload-artifact@v4
+ with:
+ name: desktop-windows-x64
+ path: windows-release/desktop-windows-x64/
+ if-no-files-found: error
+ overwrite: true
+ - uses: actions/upload-artifact@v4
+ with:
+ name: desktop-windows-arm64
+ path: windows-release/desktop-windows-arm64/
+ if-no-files-found: error
+ overwrite: true
+
+ upload-windows:
+ needs: [version, build-windows, sign-windows]
+ # Signed when WINDOWS_SIGNING is `required`, and then never without it; unsigned only while signing is off.
+ if: ${{ !cancelled() && needs.build-windows.result == 'success' && (needs.sign-windows.result == 'success' || (needs.sign-windows.result == 'skipped' && vars.WINDOWS_SIGNING != 'required')) }}
runs-on: ubuntu-latest
timeout-minutes: 15
env:
@@ -713,7 +798,9 @@ jobs:
# its full producer source tree, Desktop build inputs, version, run and attempt.
candidate:
needs: [version, build-macos, build-linux, upload-windows]
- if: ${{ inputs.prepare_only }}
+ # Explicit results: an implicit success() also inspects skipped ancestors, and sign-windows is skipped while
+ # WINDOWS_SIGNING is off.
+ if: ${{ !cancelled() && inputs.prepare_only && needs.version.result == 'success' && needs.build-macos.result == 'success' && needs.build-linux.result == 'success' && needs.upload-windows.result == 'success' }}
runs-on: ubuntu-latest
timeout-minutes: 8
steps:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e530f5fc1..558c5b479 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -317,8 +317,53 @@ jobs:
version: ${{ needs.version.outputs.version }}
release: true
+ # Authenticode through Azure Artifact Signing (docs/windows-code-signing.md) once the repository variable
+ # WINDOWS_SIGNING is `required`; until then skipped, and the payload ships unsigned as before. One x64 job for both
+ # architectures (the signing action does not run on Windows Arm). Microsoft's conpty.dll and OpenConsole.exe keep
+ # their own signatures. Each payload goes back under its artifact name, so windows-staging reads it unchanged.
+ pty-sign:
+ needs: [version, pty-build]
+ if: vars.WINDOWS_SIGNING == 'required'
+ runs-on: windows-latest
+ timeout-minutes: 20
+ environment: release
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ sparse-checkout: |
+ /.github/actions/windows-signing/
+ sparse-checkout-cone-mode: false
+ - uses: actions/download-artifact@v4
+ with:
+ pattern: harness-pty-windows-*
+ path: .pty
+ - uses: ./.github/actions/windows-signing
+ with:
+ path: .pty
+ publisher: ${{ vars.WINDOWS_SIGNING_PUBLISHER || 'AUTONOMOUS INC.' }}
+ azure-client-id: ${{ vars.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ vars.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+ endpoint: ${{ vars.SIGNING_ENDPOINT }}
+ account: ${{ vars.SIGNING_ACCOUNT }}
+ profile: ${{ vars.SIGNING_PROFILE }}
+ - uses: actions/upload-artifact@v4
+ with:
+ name: harness-pty-windows-x64
+ path: .pty/harness-pty-windows-x64/
+ if-no-files-found: error
+ overwrite: true
+ - uses: actions/upload-artifact@v4
+ with:
+ name: harness-pty-windows-arm64
+ path: .pty/harness-pty-windows-arm64/
+ if-no-files-found: error
+ overwrite: true
+
windows-staging:
- needs: [version, preflight, publish, pty-build]
+ needs: [version, preflight, publish, pty-build, pty-sign]
+ # Signed when WINDOWS_SIGNING is `required`, and then never without it; unsigned only while signing is off.
+ if: ${{ !cancelled() && needs.publish.result == 'success' && needs.pty-build.result == 'success' && (needs.pty-sign.result == 'success' || (needs.pty-sign.result == 'skipped' && vars.WINDOWS_SIGNING != 'required')) }}
runs-on: ubuntu-latest
timeout-minutes: 15
env:
diff --git a/cli/src/scripts/windowsWorkflows.spec.ts b/cli/src/scripts/windowsWorkflows.spec.ts
index c6495a336..ca9612689 100644
--- a/cli/src/scripts/windowsWorkflows.spec.ts
+++ b/cli/src/scripts/windowsWorkflows.spec.ts
@@ -37,7 +37,7 @@ describe('the Windows release workflows', () => {
expect(release).toContain('OBJECT_PREFIX="$STAGING_PREFIX" METADATA_PATH="$STAGING_PREFIX/pty/metadata.json" bash cli/scripts/publish-pty-payload.sh')
expect(release).toMatch(/staging=harness\/staging; else staging=harness\/staging-dry-run; fi/)
expect(release).not.toMatch(/bash cli\/scripts\/promote-pty-payload\.sh/)
- expect(release).toMatch(/windows-staging:\n\s+needs: \[version, preflight, publish, pty-build\]/)
+ expect(release).toMatch(/windows-staging:\n\s+needs: \[version, preflight, publish, pty-build, pty-sign\]/)
expect(release).toMatch(/github-release:\n\s+needs: \[version, publish\]/)
expect(release).toMatch(/publish:\n\s+needs: \[version, preflight, process-images\]/)
expect(release).not.toMatch(/METADATA_PATH=harness\/pty\/metadata\.json/)
@@ -104,7 +104,7 @@ describe('the Windows release workflows', () => {
expect(desktop).toContain("'desktop-windows-installer': 'harness-install.exe'")
})
- // Installer spec §2.2: every desktop release ships Windows, unsigned, from the same manifest write.
+ // Installer spec §2.2: every desktop release ships Windows from the same manifest write.
it('builds Windows in the desktop release and publishes it with the other platforms', () => {
const release = read('release-desktop.yml')
const job = (name: string) => release.match(new RegExp(`\n ${name}:\n([\\s\\S]*?)(?=\n [\\w-]+:\n|$)`))?.[1] ?? ''
@@ -124,4 +124,36 @@ describe('the Windows release workflows', () => {
expect(release).toMatch(/cleanup:\n\s+needs: \[version, preflight, build-macos, build-linux, build-windows, upload-windows, candidate, publish\]/)
expect(release).toContain('[harness-install.exe](${base}/harness-install.exe)')
})
+
+ // docs/windows-code-signing.md: one x64 signing job per release (Artifact Signing does not run on Windows Arm), off
+ // until WINDOWS_SIGNING is `required`, and then nothing Windows publishes without it.
+ it('signs the Windows files of both releases before they publish, once signing is required', () => {
+ const job = (workflow: string, name: string) => workflow.match(new RegExp(`\n ${name}:\n([\\s\\S]*?)(?=\n [\\w-]+:\n|$)`))?.[1] ?? ''
+ const gate = (signing: string) =>
+ `(needs.${signing}.result == 'success' || (needs.${signing}.result == 'skipped' && vars.WINDOWS_SIGNING != 'required'))`
+ for (const [file, signing, build, next] of [
+ ['release-desktop.yml', 'sign-windows', 'build-windows', 'upload-windows'],
+ ['release.yml', 'pty-sign', 'pty-build', 'windows-staging'],
+ ]) {
+ const workflow = read(file)
+ const sign = job(workflow, signing)
+ expect(sign).toContain(`needs: [version, ${build}]`)
+ expect(sign).toContain("if: vars.WINDOWS_SIGNING == 'required'")
+ expect(sign).toContain('runs-on: windows-latest')
+ expect(sign).toContain('environment: release')
+ expect(sign).toContain('uses: ./.github/actions/windows-signing')
+ expect(sign.match(/overwrite: true/g)).toHaveLength(2)
+ expect(job(workflow, next)).toContain(gate(signing))
+ }
+ // A skipped sign-windows is an ancestor of `candidate`: an implicit success() there would skip every candidate
+ // prepared while signing is off.
+ expect(job(read('release-desktop.yml'), 'candidate')).toContain(
+ "if: ${{ !cancelled() && inputs.prepare_only && needs.version.result == 'success' && needs.build-macos.result == 'success' && needs.build-linux.result == 'success' && needs.upload-windows.result == 'success' }}",
+ )
+ const action = readFileSync(join(workflows, '..', 'actions', 'windows-signing', 'action.yml'), 'utf8')
+ expect(action).toContain('uses: azure/login@v3')
+ expect(action).toContain('uses: azure/artifact-signing-action@v2')
+ expect(action).toContain('timestamp-rfc3161: http://timestamp.acs.microsoft.com')
+ expect(action).not.toMatch(/client-secret|azure-password/)
+ })
})
diff --git a/desktop/RELEASE.md b/desktop/RELEASE.md
index 8bf8c56c5..cba1c7e2e 100644
--- a/desktop/RELEASE.md
+++ b/desktop/RELEASE.md
@@ -594,8 +594,12 @@ its own runner and `upload-windows` publishes from ubuntu. Three files go to `ha
no app: it reads the manifest when it runs, picks this PC's zip as `install.ps1 -App` does, checks it and runs its
`Harness.exe --install` (`installer/`, docs/superpowers/specs/2026-10-19-windows-installer-design.md).
-Nothing is code-signed yet. Windows shows SmartScreen once, on the installer a browser downloaded; Smart App Control
-blocks the build where it is on. A failed Windows build stops the release, as a failed macOS or Linux build does.
+`sign-windows` Authenticode-signs every `.exe` and `.dll` in both zips and `harness-install.exe` through Azure Artifact
+Signing, as **AUTONOMOUS INC.**, once the repository variable `WINDOWS_SIGNING` is `required`
+([docs/windows-code-signing.md](../docs/windows-code-signing.md)). Until then it is skipped and the files ship
+unsigned: Windows shows SmartScreen once, on the installer a browser downloaded, and Smart App Control blocks the build
+where it is on. Once signing is required, a failed signature stops the release and a candidate prepared unsigned is
+not reused. A failed Windows build stops the release, as a failed macOS or Linux build does.
If Microsoft Defender flags `harness-install.exe` or the app, submit the file as a software developer at
https://www.microsoft.com/wdsi/filesubmission with the release version. Do not change the build to dodge a detection.
diff --git a/docs/validation-and-release.md b/docs/validation-and-release.md
index 1d42616f3..3c2035dec 100644
--- a/docs/validation-and-release.md
+++ b/docs/validation-and-release.md
@@ -118,7 +118,8 @@ from `main` before relying on its CI.
Record what you ran, with run links, in the PR. Release workflows are not a full
test suite: the CLI release runs typecheck and bundle checks, and the Desktop release
-builds, signs and verifies downloads. A release failure is still a code failure: fix
+builds, signs and verifies downloads. Windows files are signed through Azure Artifact
+Signing once `WINDOWS_SIGNING` is `required` ([Windows code signing](windows-code-signing.md)). A release failure is still a code failure: fix
it and cut the next version.
Do not add CI runs to a PR. Don't start **CI → Run workflow** for a PR that already has
@@ -217,7 +218,9 @@ or use `--deleted-branch NAME`; `--apply` performs the selected cleanup.
### Package Desktop while final checks run
When the final implementation is pushed, start `make release-desktop ARGS="--prepare"`
-on that PR branch alongside its required tests and review. This chooses the next
+on that PR branch alongside its required tests and review. While Windows signing is required, the
+`release` environment must allow that branch, or `sign-windows` fails and no candidate is made
+([Windows code signing](windows-code-signing.md#2-github-repository-admin)). This chooses the next
version using the same tags/live-manifest rules as a release, then dispatches a
candidate build. Use an explicit version with `--prepare` when preparing a minor
bump. The candidate uses the release's normal macOS, Linux and Windows build, signing and
diff --git a/docs/windows-code-signing.md b/docs/windows-code-signing.md
new file mode 100644
index 000000000..86909fb60
--- /dev/null
+++ b/docs/windows-code-signing.md
@@ -0,0 +1,156 @@
+# Windows code signing
+
+Windows files the Desktop and CLI releases publish are Authenticode-signed through
+[Azure Artifact Signing](https://learn.microsoft.com/azure/artifact-signing/) (formerly Trusted Signing), as
+**AUTONOMOUS INC.** Signing removes the SmartScreen "Windows protected your PC" prompt from a signed publisher's
+installer as reputation builds, lets Smart App Control run the app, and gives antivirus a publisher to trust.
+
+Signing is off until the repository variable `WINDOWS_SIGNING` is `required`. Until then the signing jobs are skipped
+and Windows ships unsigned, exactly as before this change.
+
+## What is signed
+
+| Release | Job | Files |
+| --- | --- | --- |
+| Desktop (`release-desktop.yml`) | `sign-windows` | every `.exe` and `.dll` in `Harness-windows-x64.zip` and `Harness-windows-arm64.zip` (`Harness.exe`, `harness-desktop.exe`, `harness_pipe_io.dll`, Flutter's and the plugins' DLLs), and `harness-install.exe` |
+| CLI (`release.yml`) | `pty-sign` | `harness-pty.exe`, `harness-launch.exe`, `harness.exe`, `harness-serial.exe` for x64 and arm64 |
+
+A file that already carries a valid signature keeps it: Microsoft's `conpty.dll` and `OpenConsole.exe` are not
+re-signed. A file whose signature is broken fails the job.
+
+## How it works
+
+```
+build-windows (x64) ─┐ ┌─> upload-windows ─> publish
+build-windows (arm64) ─┴─> sign-windows (x64 only) ─┘
+pty-build (x64, arm64) ──> pty-sign (x64 only) ──────> windows-staging
+```
+
+- **One x64 job per release.** The Artifact Signing action does not run on Windows Arm runners. Authenticode signing
+ does not depend on the CPU, so the x64 job signs the arm64 files too.
+- **`.github/actions/windows-signing`** does the work:
+ 1. List every `.exe` and `.dll` without a signature.
+ 2. Sign in to Azure with the job's GitHub OIDC token (`azure/login@v3`). There is no client secret.
+ 3. Sign with `azure/artifact-signing-action@v2`, using SHA-256 and an RFC 3161 timestamp from
+ `timestamp.acs.microsoft.com`. Artifact Signing certificates last about three days, so the timestamp is what
+ keeps a signature valid after that.
+ 4. Verify every `.exe` and `.dll` with `Get-AuthenticodeSignature`. Each needs status Valid and a timestamp, and
+ each one we signed must name `WINDOWS_SIGNING_PUBLISHER`. The check uses the publisher name, not a thumbprint,
+ because the certificate changes every few days.
+- **Desktop zips are opened, signed and written again** with the entries `package-windows.ps1` writes, under the same
+ artifact names (`overwrite: true`). `upload-windows` and `check-windows-zip.py` are unchanged. The manifest's
+ sha256 is the hash of the signed bytes.
+- **Gate.** `upload-windows` and `windows-staging` accept a skipped signing job only while `WINDOWS_SIGNING` is not
+ `required`. Once it is, a failed or skipped signature stops the Windows publish. Nothing falls back to unsigned.
+- **Candidate reuse.** While signing is required, `desktop-release-candidate.py` refuses a prepared candidate without
+ a successful `sign-windows` job. A candidate built before signing was turned on is rebuilt, not shipped unsigned.
+- **PR CI is unchanged.** Signing runs only in the release workflows.
+
+## Setup
+
+### 1. Azure (owner, once)
+
+Identity validation is done: **AUTONOMOUS INC.**, Public Trust, United States, valid until 29 January 2029. Renew
+it before then in the portal (Artifact Signing account → Identity validations → Renew).
+
+The remaining steps wait for the organisation's permission grant:
+
+1. **Artifact Signing account.** Create one in the subscription and note its name and region. The endpoint is
+ regional, e.g. `https://eus.codesigning.azure.net/` for East US.
+2. **Certificate profile.** In the account, create a **Public Trust** profile from the AUTONOMOUS INC. identity
+ validation. Note its name.
+3. **App registration.** In Microsoft Entra ID → App registrations, create e.g. `openharness-windows-signing`. Note
+ its client ID and the tenant ID. Do not create a client secret.
+4. **Federated credential.** On that app → Certificates & secrets → Federated credentials → Add:
+ - scenario: GitHub Actions deploying Azure resources
+ - organization and repository: this repository
+ - scenario: **Other issuer**, issuer `https://token.actions.githubusercontent.com`, audience
+ `api://AzureADTokenExchange`
+ - subject: **`repo:autonomous-ai@98006261/openharness@1322671404:environment:release`**
+
+ This repository uses GitHub's immutable OIDC subject (`gh api repos/autonomous-ai/openharness/actions/oidc/customization/sub`
+ shows `use_immutable_subject: true`), which names the org and repository by ID too. The subject the "GitHub
+ Actions" scenario writes, `repo:autonomous-ai/openharness:environment:release`, never matches, and `azure/login`
+ fails with `AADSTS700213: No matching federated identity record`. Only jobs in that environment can sign, and the
+ environment's own rules decide which branches and tags those are.
+5. **Role.** On the certificate profile (not the account or the subscription) → Access control (IAM), assign
+ **Artifact Signing Certificate Profile Signer** to the app registration.
+
+### 2. GitHub (repository admin)
+
+1. **Environment.** The signing jobs run in the existing `release` environment. Add these to it as environment
+ variables (Settings → Environments → `release`). They are identifiers, not secrets:
+
+ | Variable | Value |
+ | --- | --- |
+ | `AZURE_CLIENT_ID` | the app registration's client ID |
+ | `AZURE_TENANT_ID` | the tenant ID |
+ | `AZURE_SUBSCRIPTION_ID` | the subscription holding the signing account |
+ | `SIGNING_ENDPOINT` | the account's regional endpoint |
+ | `SIGNING_ACCOUNT` | the account name |
+ | `SIGNING_PROFILE` | the certificate profile name |
+ | `WINDOWS_SIGNING_PUBLISHER` | optional: the certificate's common name, `AUTONOMOUS INC.` when unset |
+
+2. **Deployment branches and tags.** `release` allows branch `main` and tags `v*`, which covers `v*_desktop` and
+ `v*_cli` tag releases and runs dispatched from `main`. A Desktop candidate prepared from a PR branch
+ (`make release-desktop ARGS="--prepare"`) is refused by the environment while signing is required: its
+ `sign-windows` fails and the candidate is not made. Either prepare candidates from `main` after the merge, or add
+ a branch pattern for candidate branches to the environment.
+
+ Do not add required reviewers. A signing job that waits for approval holds the release run.
+3. **Switch.** Settings → Secrets and variables → Actions → **Variables** (repository, not environment):
+ `WINDOWS_SIGNING` = `required`. It has to be a repository variable because the jobs' `if:` reads it before any
+ environment loads. Set it only after the first test below passes.
+
+## First run and rollout
+
+1. **Lint.** Run `actionlint .github/workflows/release.yml .github/workflows/release-desktop.yml`. PR CI's `plan` job
+ lints neither release workflow.
+2. **Desktop candidate.** Set `WINDOWS_SIGNING=required`, then from `main` run
+ `make release-desktop ARGS="--prepare"` (or **Actions → Release desktop → Run workflow** with
+ `prepare_only: true`). This builds, signs and verifies without publishing to users. Check that `sign-windows`
+ lists each file, that its summary names AUTONOMOUS INC., and that `upload-windows` passes `check-windows-zip.py`.
+3. **CLI dry run.** Run **Actions → Release → Run workflow** with the `metadata-test.json` path. `pty-sign` signs, and
+ `windows-staging` publishes to `harness/staging-dry-run`.
+4. **On a real PC** (Windows 11, Smart App Control on if possible), download the candidate's or staging installer in
+ Edge:
+ - File → Properties → Digital Signatures shows AUTONOMOUS INC. with a timestamp.
+ - `Get-AuthenticodeSignature harness-install.exe` reports Valid.
+ - Smart App Control lets the installer and app run.
+ - SmartScreen shows the publisher. A new publisher can still get one prompt until reputation builds; record what
+ you see.
+5. **Docs.** Once a signed release is out, update the copy that says Windows is unsigned:
+ - the `note:` in `docs/superpowers/specs/2026-10-19-windows-installer-design.md` (around line 258) and the installer
+ UI text it describes
+ - the SmartScreen and Smart App Control rows in that spec and in `2026-10-18-windows-desktop-design.md`
+ - the antivirus note in `2026-10-16-windows-native-cli-design.md`
+
+**Turning it off.** Set `WINDOWS_SIGNING` to anything other than `required`, or delete it. Releases then ship
+unsigned again. Files already published stay validly signed, because each signature is timestamped.
+
+## Design
+
+- **Growth:** N/A. Nothing is stored. The Azure account logs each signing request; Azure retains those logs.
+- **Concurrency:** N/A. Each release signs its own artifacts in its own job.
+- **Read cost:** N/A.
+- **Scale:** a Desktop release signs about 20 to 40 files and a CLI release 8. The Basic plan includes 5,000
+ signatures a month, about 100 releases. The first warning is the Azure quota on the account's metrics page, or a
+ `429` in the signing step.
+- **Compatibility:** Windows does not care whether a file is signed. The updater and `install.ps1` compare sha256 from
+ the manifest, which is computed after signing.
+- **Migration and rollback:** see Turning it off. Prepared unsigned candidates are rebuilt automatically.
+- **Audience:** Azure enforces it. Only the `release` environment's OIDC subject has the Signer role, and only
+ on one certificate profile.
+- **Identity:** a dedicated app registration with a federated credential. No person's login and no long-lived secret.
+- **Failure:** a signing or verification failure fails the job, and with signing required that stops the Windows
+ publish. Nothing ships unsigned silently.
+- **Platforms:** Windows x64 and arm64, both signed on an x64 runner. macOS signing (`macos-signing`) is unchanged.
+
+## Not covered yet
+
+- **The updater and `harness-install.exe` do not check the publisher** of what they download; they rely on sha256
+ from the manifest. Requiring an AUTONOMOUS INC. signature there is a separate change for after signing is live.
+- **`windows-desktop.yml`'s staging release mode** builds unsigned staging packages. Add the same signing job there
+ if staging E2E should cover signed files.
+- **The Windows Node runtime** (`release-node-runtime-windows.yml`) republishes nodejs.org's `node.exe`, which the
+ OpenJS Foundation already signs.
diff --git a/scripts/desktop-release-candidate.py b/scripts/desktop-release-candidate.py
index 69e79bacb..3e7f8c820 100644
--- a/scripts/desktop-release-candidate.py
+++ b/scripts/desktop-release-candidate.py
@@ -232,10 +232,13 @@ def read_receipt(artifact, archive, run, repository, version, tree, inputs, buck
return receipt
-def check_jobs(run, jobs):
+def check_jobs(run, jobs, windows_signing=False):
required = {'version', 'preflight', 'build-macos', 'build-linux (ubuntu-22.04, x64)',
'build-linux (ubuntu-22.04-arm, arm64)', 'build-windows (windows-latest, x64)',
'build-windows (windows-11-arm, arm64)', 'upload-windows', 'candidate', 'cleanup'}
+ # While WINDOWS_SIGNING is `required`, a candidate built before it (sign-windows skipped) would ship unsigned.
+ if windows_signing:
+ required.add('sign-windows')
require(required <= {job['name'] for job in jobs}, 'candidate build/verification jobs are missing')
for job in jobs:
require(job.get('run_id') == run['id'] and job.get('head_sha') == run['head_sha']
@@ -294,7 +297,7 @@ def find_candidate(client, version, inputs, bucket, current_run, wait_seconds=MA
continue
jobs = client.api(f'actions/runs/{run["id"]}/jobs?filter=latest&per_page=100')
require(jobs['total_count'] == len(jobs['jobs']), 'candidate job list is incomplete')
- check_jobs(run, jobs['jobs'])
+ check_jobs(run, jobs['jobs'], windows_signing=os.environ.get('WINDOWS_SIGNING') == 'required')
artifacts = client.api(f'actions/runs/{run["id"]}/artifacts?per_page=100')['artifacts']
selected = [item for item in artifacts if item['name'] == f'desktop-release-candidate-{run["run_attempt"]}']
require(len(selected) == 1 and selected[0].get('size_in_bytes', 65537) <= 65536, 'candidate receipt is missing or too large')
diff --git a/scripts/tests/test_desktop_release_candidate.py b/scripts/tests/test_desktop_release_candidate.py
index c8020d616..8d7268963 100644
--- a/scripts/tests/test_desktop_release_candidate.py
+++ b/scripts/tests/test_desktop_release_candidate.py
@@ -224,6 +224,21 @@ class CandidateIdentityTests(unittest.TestCase):
if change == 'wrong-source': client.jobs[2]['head_sha'] = 'f' * 40
candidate.find_candidate(client, VERSION, INPUTS, BUCKET, 456)
+ # A candidate prepared while signing was off would otherwise publish unsigned Windows files once it is on.
+ def test_unsigned_windows_candidate_cannot_reuse_once_signing_is_required(self):
+ jobs = make_jobs()
+ candidate.check_jobs(make_run(), jobs)
+ for skipped in [False, True]:
+ with self.subTest(skipped=skipped):
+ signed = jobs + [dict(jobs[0], name='sign-windows', conclusion='skipped' if skipped else 'success')]
+ if skipped:
+ with self.assertRaises(ValueError):
+ candidate.check_jobs(make_run(), signed, windows_signing=True)
+ else:
+ candidate.check_jobs(make_run(), signed, windows_signing=True)
+ with self.assertRaises(ValueError):
+ candidate.check_jobs(make_run(), jobs, windows_signing=True)
+
def test_wait_follows_one_live_run_without_starting_another(self):
client = FakeGithub()
client.run.update(status='in_progress', conclusion=None)