Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .agents/skills/pr-testing/ci-infra-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -562,9 +562,10 @@ eyeballing — e.g. `eng/scripts/verify-cli-tool-nupkg.ps1`, `verify-cli-archive
itself a finding.

**Build behavior changed → read the binlog, not just the console.** CI build jobs emit
MSBuild binlogs via `/bl:` — e.g. `BuildAndArchive.binlog`, `BuildCli.binlog`,
`BundlePayload.binlog` under `artifacts/log/...` (`run-tests.yml`,
`build-cli-native-archives.yml`) and `SendToHelix.binlog` on the AzDO Helix path. Download
MSBuild binlogs via `/bl:` — e.g. `BuildAndArchive.binlog` from `run-tests.yml`,
`BuildNativeBundle.binlog` from `build-cli-native-archives.yml`, and child-build
`PublishAndPackageCli.binlog` from `eng/Bundle.proj`, under `artifacts/log/...`.
The AzDO Helix path emits `SendToHelix.binlog`. Download
the binlog and confirm the change took effect: the target/task ran, the property/condition
evaluated as intended, and the right items were (or were not) included.

Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/auto-rerun/rerun-pull-request.js
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,9 @@ const ignoredFailureStepPatterns = [
/^Run nuget dependent tests\b/i,
/^Build test project$/i,
/^Build and archive test project$/i,
/^Build native bundle and CLI packages$/i,
// Keep previous step names for reruns of older workflow revisions.
/^Build bundle payload archive$/i,
/^Build RID-specific packages\b/i,
/^Build Python validation image$/i,
/^Build with packages$/i,
Expand Down
100 changes: 26 additions & 74 deletions .github/workflows/build-cli-native-archives.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,63 +76,35 @@ jobs:
with:
node-version: 22.x

# Build RID-specific NuGet packages (DCP + Dashboard) locally instead of
# downloading them from the build_packages job. This allows the CLI archive
# build to run in parallel with build_packages.
#
# Capture the complete build output so the expected framework-owned IL2026
# can remain visible while verification rejects any additional IL2026 warnings.
- name: Build RID-specific packages
# Bundle.proj owns publish, warning validation, signing, payload assembly,
# and the clipack build/sign/pack flow in both CI systems.
- name: Build native bundle and CLI packages
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$buildLog = "$env:GITHUB_WORKSPACE/artifacts/log/$env:BUILD_CONFIGURATION/BuildBundleDeps.log"
# Repository cleanup can remove artifacts/log while the build is streaming output.
$temporaryLog = Join-Path '${{ runner.temp }}' 'BuildBundleDeps.log'
# Overrides contain multiple MSBuild switches; split them into arguments without evaluating them as code.
$versionOverrideArgs = @($env:VERSION_OVERRIDE_ARG -split '\s+' | Where-Object { $_ })
& '${{ runner.os == 'Windows' && './build.cmd' || './build.sh' }}' `
-ci `
-restore `
-build `
-pack `
-configuration $env:BUILD_CONFIGURATION `
"/bl:$env:GITHUB_WORKSPACE/artifacts/log/$env:BUILD_CONFIGURATION/BuildBundleDeps.binlog" `
/p:ContinuousIntegrationBuild=true `
/p:BuildBundleDepsOnly=true `
"/p:TargetRids=$env:TARGET_RIDS" `
"/p:AspireCliChannel=$env:ASPIRE_CLI_CHANNEL" `
@versionOverrideArgs 2>&1 | Tee-Object -FilePath $temporaryLog
$buildExitCode = $LASTEXITCODE
New-Item -ItemType Directory -Force -Path (Split-Path $buildLog -Parent) | Out-Null
Copy-Item -LiteralPath $temporaryLog -Destination $buildLog
exit $buildExitCode

- name: Verify Native AOT Dashboard warnings
shell: pwsh
run: >
./eng/scripts/verify-native-dashboard-warnings.ps1
-BuildLog "$env:GITHUB_WORKSPACE/artifacts/log/$env:BUILD_CONFIGURATION/BuildBundleDeps.log"

- name: Build bundle payload archive
# SkipNativeBuild skips only the outer CLI. Bundle.proj still publishes
# native desktop tray payloads and verifies the actual archive.
shell: pwsh
# Overrides contain multiple MSBuild switches; split them into arguments without evaluating them as code.
run: >
$versionOverrideArgs = @($env:VERSION_OVERRIDE_ARG -split '\s+' | Where-Object { $_ })
$dotnetScript = if ($IsWindows) { "./dotnet.cmd" } else { "./dotnet.sh" }
$arguments = @(
"msbuild",
"eng/Bundle.proj",
"/t:Build",
"/p:BuildDistributionPackages=true",
"/p:Configuration=$env:BUILD_CONFIGURATION",
"/p:TargetRid=$env:TARGET_RIDS",
"/p:BundleVersion=ci-bundlepayload",
"/p:PackDcpPackage=true",
"/p:ContinuousIntegrationBuild=true",
"/p:AspireCliChannel=$env:ASPIRE_CLI_CHANNEL",
"/bl:$env:GITHUB_WORKSPACE/artifacts/log/$env:BUILD_CONFIGURATION/BuildNativeBundle.binlog"
)
if (-not [string]::IsNullOrWhiteSpace($env:VERSION_OVERRIDE_ARG)) {
# The caller supplies whitespace-separated switches without spaces in values,
# e.g. /p:VersionSuffix=pr.123.gabcdef12 /p:DotNetFinalVersionKind=prerelease.
$arguments += $env:VERSION_OVERRIDE_ARG.Trim() -split '\s+'
}

${{ runner.os == 'Windows' && './dotnet.cmd' || './dotnet.sh' }}
msbuild
eng/Bundle.proj
/restore
"/p:Configuration=$env:BUILD_CONFIGURATION"
"/p:TargetRid=$env:TARGET_RIDS"
/p:BundleVersion=ci-bundlepayload
/p:SkipNativeBuild=true
/p:ContinuousIntegrationBuild=true
"/bl:$env:GITHUB_WORKSPACE/artifacts/log/$env:BUILD_CONFIGURATION/BundlePayload.binlog"
@versionOverrideArgs
& $dotnetScript @arguments
if ($LASTEXITCODE -ne 0) {
exit $LASTEXITCODE
}

- name: Smoke test packaged native tray
shell: pwsh
Expand All @@ -158,26 +130,6 @@ jobs:
./eng/scripts/test-native-terminalhost.ps1
-TerminalHostPath "$env:GITHUB_WORKSPACE/artifacts/bundle/$env:TARGET_RIDS/terminalhost/Aspire.TerminalHost${{ runner.os == 'Windows' && '.exe' || '' }}"

- name: Build CLI packages
shell: pwsh
# Overrides contain multiple MSBuild switches; split them into arguments without evaluating them as code.
run: >
$versionOverrideArgs = @($env:VERSION_OVERRIDE_ARG -split '\s+' | Where-Object { $_ })

${{ runner.os == 'Windows' && './build.cmd' || './build.sh' }}
-ci
-build
-pack
-restore
-configuration $env:BUILD_CONFIGURATION
"/bl:$env:GITHUB_WORKSPACE/artifacts/log/$env:BUILD_CONFIGURATION/BuildCli.binlog"
/p:ContinuousIntegrationBuild=true
/p:SkipManagedBuild=true
"/p:TargetRids=$env:TARGET_RIDS"
"/p:BundlePayloadPath=$env:GITHUB_WORKSPACE/artifacts/bundle/aspire-ci-bundlepayload-$env:TARGET_RIDS.tar.gz"
"/p:AspireCliChannel=$env:ASPIRE_CLI_CHANNEL"
@versionOverrideArgs

- name: Verify CLI tool nupkg
shell: pwsh
run: |
Expand Down
41 changes: 36 additions & 5 deletions docs/ci/native-cli-packaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,22 @@ The GitHub Actions test workflow builds native CLI archives per OS/RID and uploa

These PR artifacts are useful for validation and dogfooding, but they are not the final official signed release artifacts.

## Shared bundle validation

Validate packaging and signing against the outputs of the producing build,
not replacement projects or private MSBuild targets in `Infrastructure.Tests`.
The native jobs verify packaged Dashboard and TerminalHost behavior and compare
the CLI archive with its tool and npm packages. Official builds additionally
exercise real signing and notarization; unsigned GitHub artifacts cannot
establish those contracts.

The deployment workflow consumes a different build mode: it invokes
`eng/Bundle.proj` with `BuildDistributionPackages` omitted, producing a
standalone CLI rather than distribution packages. Validate that path with a
Linux build and inspect the resulting CLI and extracted bundle. A successful
distribution-mode build alone does not establish this contract, and validating
the build does not require deploying to Azure.

## Internal signed builds

The internal Azure DevOps `build_sign_native` stage is responsible for producing signed native CLI artifacts. Windows and macOS native jobs run with code signing enabled so each OS/arch-specific native executable can be signed or notarized on the appropriate platform.
Expand Down Expand Up @@ -57,11 +73,26 @@ Linux native jobs do not sign ELF binaries in `build_sign_native`. For Linux, ex

## Native AOT Dashboard package signing

All seven Dashboard SDK NuGet packages follow the CLI package-signing path: `assemble` stages them together in `Shipping` before its Windows signing pass. There is no second Dashboard staging pass after signing. When NuGet signing is enabled, this ensures Linux packages receive NuGet signatures even though Linux native jobs skip ELF signing.

NuGet signing follows `PostBuildSign` in `eng/pipelines/common-variables.yml`: release-branch and manually queued official builds set it to `false`, enabling Arcade's default package-signing inputs. Automatic main builds set it to `true`, excluding NuGet packages from in-build signing; native executable and npm signing are selected separately.

Assembly verifies every staged NuGet release package's signature before publishing build artifacts only when real signing is enabled and `PostBuildSign` is not `true`. This matches package-signing selection rather than assuming that a real-signed build signs every artifact. The unsigned `*.symbols.nupkg` files also staged in `Shipping` are excluded because they are symbol-server inputs, not NuGet release packages.
The official Assemble job stages the three Linux Dashboard SDK NuGet packages
before its Windows signing pass because Linux native jobs skip signing.
Windows/macOS Dashboard packages are staged afterward so their signed producer
outputs are preserved.

NuGet signing follows `PostBuildSign` in
[`common-variables.yml`](../../eng/pipelines/common-variables.yml):
release-branch and manually queued official builds set it to `false`, enabling
Arcade's default package-signing inputs. Automatic main builds set it to `true`,
excluding NuGet packages from in-build signing; native executable and npm
signing are selected separately.

Assembly checks that all seven Dashboard packages reached `Shipping`. When real
signing is enabled and `PostBuildSign` is not `true`, it also verifies every final
NuGet release package's signature before publishing, including Dashboard, CLI,
and managed packages. This matches package-signing selection
rather than assuming that a real-signed build signs every artifact. The unsigned
`*.symbols.nupkg` files are excluded because they are symbol-server inputs, not
NuGet release packages. See the Assemble job in
[`azure-pipelines.yml`](../../eng/pipelines/azure-pipelines.yml).

## Nix flake packaging

Expand Down
2 changes: 1 addition & 1 deletion docs/ci/test-trigger-selector-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ the graph root does not produce the repository project graph.

Evaluating `eng/Build.props`'s `ProjectToBuild` items would also make selection
depend on build flags and the current RID. Flags such as `SkipNativeBuild`,
`BuildBundleDepsOnly`, and `SkipTestProjects` differ across CI jobs.
`SkipManagedBuild`, and `SkipTestProjects` differ across CI jobs.

That project set is also a net loss for test selection:

Expand Down
59 changes: 45 additions & 14 deletions docs/specs/bundle.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,21 @@ The repository-development path uses project references and local artifacts wher

[eng/Bundle.proj](../../eng/Bundle.proj) orchestrates local bundle creation. Restore the repository toolchain first and install the target platform's Native AOT prerequisites.

The bundling process is:

1. Validate the requested configuration and acquire DCP for the target platform.
2. Publish the managed helper, Dashboard, TerminalHost, AppHost Server, and
platform tray, or reuse their prepared outputs when requested.
3. For signed distributions, sign the component binaries. The macOS tray app
also requires whole-app signing and notarization.
4. Create any requested Dashboard and DCP distribution packages, then assemble
the payload archive from the prepared components.
5. Publish the CLI with the payload embedded and sign it when requested.
Distribution builds also create CLI archives, .NET tool packages, and npm packages.

Signing precedes payload assembly so the embedded components retain their
signatures. Assembly and packaging do not republish components.

```powershell
# Windows example, from the repository root
.\restore.cmd
Expand All @@ -378,18 +393,25 @@ dotnet msbuild eng/Bundle.proj /t:Build /p:TargetRid=win-x64 /p:Configuration=Re
dotnet msbuild eng/Bundle.proj /t:Build /p:TargetRid=osx-arm64 /p:Configuration=Release
```

The build sequence is:
`Build` is the default entry point. A default build creates the payload archive
and self-extracting CLI without distribution packages. Dashboard distribution
outputs include a NuGet package and runtime ZIP.

1. Publish `Aspire.Managed` as a self-contained single-file executable.
2. Publish `Aspire.Dashboard` and `Aspire.TerminalHost` with Native AOT for the same RID and configuration.
3. Publish the native tray payload on macOS, Windows, or glibc Linux, before signing bundle components.
4. Restore the matching DCP package, using the target OS/architecture rather than the build machine's defaults.
5. Run `CreateLayout` to assemble the payload and create its `.tar.gz` archive.
6. Publish the Native AOT CLI with `BundlePayloadPath` pointing to that archive.
The assembled directories are under `artifacts/bundle/{rid}/`; the payload
archive is `artifacts/bundle/aspire-{version}-{rid}.tar.gz`. The self-extracting
CLI is in the CLI project's publish output, not in the payload directory.

The assembled directories are under `artifacts/bundle/{rid}/`; the payload archive is `artifacts/bundle/aspire-{version}-{rid}.tar.gz`. The self-extracting CLI is in the CLI project's publish output, not in the payload directory.
See the [project's options](../../eng/Bundle.proj) for distribution packaging,
signing, output paths, and component-reuse controls. Skipping component
publishing requires prepared inputs; `SkipCliArtifacts` instead omits the CLI
and its packages. Repository build wrappers translate the legacy
`/p:SkipNativeBuild=true` argument into CLI omission; use the direct MSBuild
entry point above for advanced bundle controls.

`Configuration` defaults to Debug for local bundle builds. The GitHub Actions native-archive workflow defaults to Release and passes it explicitly; CI bundle creation rejects non-Release configurations so distributed payloads use Native AOT optimizations. `SkipManagedBuild=true` reuses existing Managed, Dashboard, and TerminalHost publishes; `SkipNativeBuild=true` skips the final CLI publish. They do not make missing payload components optional.
Windows, macOS, and glibc Linux archive checks validate tray payloads before CLI embedding.
Official macOS tray signing includes notarization. CLI symbols are staged
independently; see
[CLI native symbols](../ci/cli-native-symbols.md).

### CreateLayout

Expand All @@ -401,27 +423,36 @@ dotnet run --project tools/CreateLayout -- \
--artifacts artifacts \
--rid linux-x64 \
--configuration Release \
--tray-linux artifacts/bin/Aspire.Tray.Linux/Release/net10.0/linux-x64/publish \
--tray-dir artifacts/bin/Aspire.Tray.Linux/Release/net10.0/linux-x64/publish \
--bundle-version local-test \
--archive
```

`--output`, `--artifacts`, `--rid`, and `--configuration` are required. `--bundle-version`, `--archive`, and `--verbose` are optional. The output directory is cleaned before assembly. There is no `--embed-in-cli`, `--runtime`, or runtime-download option; embedding happens in the subsequent CLI publish.

Desktop layouts also require their native tray input: `--tray-app` on macOS,
`--tray-windows` on Windows, or `--tray-linux` on glibc Linux.
Use `--dashboard "/path/to/prepared/publish"` to select a Dashboard publish directory instead of discovering one under the artifacts directory. Invalid or incomplete input fails without falling back to discovery.

Desktop layouts require `--tray-dir <directory>` for their prepared tray input.
Use the complete `.app` directory on macOS and the executable/icon publish
directory on Windows or glibc Linux. The target RID selects the payload format;
musl layouts have no tray input.

`TrayDirectory` overrides the matching tray directory in `eng/Bundle.proj`.
Publishing requires a matching host OS, validated before any component restore
or publish. Cross-architecture builds on that OS remain supported.
`SkipTrayPublish=true` reuses a prepared directory without requiring the
publishing host OS; payload validation still applies before packaging.

For the complete tool contract, see [CreateLayout](../../tools/CreateLayout/README.md). CI packaging additionally uses [dashboardpack](../../eng/dashboardpack/Common.projitems), [clipack](../../eng/clipack/Common.projitems), signing targets, and the native-archive workflows.

### Experimental Native Tray Companion

`aspire tray start` starts or restores the native companion from the invoking CLI's leased bundle; `aspire tray stop` shuts down the companion without stopping AppHosts. The companion uses the CLI's versioned discovery and exact-instance stop contracts. Linux musl, headless sessions, and standalone CLI binaries without a bundled payload are unsupported.

macOS bundles contain the complete `Aspire Tray.app`, including its executable, plist, artwork, and signature. Windows x64 and ARM64 bundles contain `tray/aspire-tray.exe` and the shared `tray/Aspire.ico`. `CreateLayout` copies the already-published payload and rejects missing or incompatible files. The native archive verification targets check the actual packaged payload before it is embedded in the CLI.
macOS bundles contain the complete `Aspire Tray.app`, including its executable, plist, artwork, and signature. Windows x64 and ARM64 bundles contain `tray/aspire-tray.exe` and the shared `tray/Aspire.ico`. `CreateLayout` copies the already-published payload and rejects missing or incompatible files. Archive verification checks the actual packaged payload before it is embedded in the CLI.

Linux x64 and ARM64 bundles contain `tray/aspire-tray` and `tray/Aspire.png`.
The Linux archive verifier rejects extra entries and requires both files to be regular, non-symlink files.
`LinuxTrayDirectory` overrides the pre-built Linux tray directory used by `eng/Bundle.proj`.

Layout assembly validates ELF architecture and executable permissions. GTK 3 and
an Ayatana/compatible AppIndicator library are dynamically loaded host
Expand Down
4 changes: 2 additions & 2 deletions eng/AfterSigning.targets
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,12 @@
<TargetRids Condition="'$(TargetRids)' == ''">$([System.Runtime.InteropServices.RuntimeInformation]::RuntimeIdentifier)</TargetRids>
</PropertyGroup>

<!-- Keep this condition in sync with the native and bundle dependency project selection
<!-- Keep this condition in sync with the native project selection
in eng/Build.props. This target packs Aspire.Cli.Tool from the native archive output,
which depends on those projects being included in the build. -->
<Target Name="_PackCliDotnetToolAfterPack"
BeforeTargets="Pack"
Condition="'$(SkipNativeBuild)' != 'true' and '$(BuildBundleDepsOnly)' != 'true'">
Condition="'$(SkipNativeBuild)' != 'true'">
<ItemGroup>
<_CliToolPackRid Include="$(TargetRids.Split(':'))" />
<_CliToolPackProject Include="@(_CliToolPackRid -> '$(RepoRoot)eng\clipack\Aspire.Cli.%(Identity).csproj')" />
Expand Down
Loading
Loading