setup-dotnet fails on air-gapped runners for floating versions

[juxtin]

Description:

On self-hosted runners without outbound internet access, actions/setup-dotnet fails to set up a .NET SDK when a floating version (e.g. 8.0.x, or a bare channel like 8.0) is requested, even when a satisfying SDK is already installed on the runner. Two separate steps in the install path make outbound requests before any check of what is already present locally:

1. Unconditional runtime pre-install. DotnetCoreInstaller.installDotnet() always runs the install script with --runtime dotnet --channel LTS first ("to get the latest stable version of the dotnet CLI"). This resolves Runtime/LTS/latest.version from builds.dotnet.microsoft.com (falling back to ci.dot.net) on every run, regardless of the requested version. On an air-gapped runner this fails immediately.

   • Source: src/installer.ts#L410-L417

2. Online latest.version resolution for floating/channel versions. A floating input such as 8.0.x is turned into a channel argument (8.0) rather than a concrete version. The install script then fetches Sdk/8.0/latest.version over the network to resolve the exact patch, before it checks whether a matching SDK is already on disk. On an air-gapped runner this also fails.

   • Channel argument construction: src/installer.ts#L120-L143
   • Version-file fetch: externals/install-dotnet.sh get_version_from_latestversion_file

Representative failing log (floating versions 8.0.x/9.0.x/10.0.x, no outbound access):

install-dotnet.sh --skip-non-versioned-files --runtime dotnet --channel LTS
dotnet-install: Download attempt #1 has failed: Unable to download https://builds.dotnet.microsoft.com/dotnet/Runtime/LTS/latest.version.
... (retries, then falls back to https://ci.dot.net/public/Runtime/LTS/latest.version) ...
Warning: Failed to install dotnet runtime + cli, exit code: 1. dotnet_install: Error: Failed to resolve the exact version number.

install-dotnet.sh --skip-non-versioned-files --channel 8.0
dotnet-install: Download attempt #1 has failed: Unable to download https://builds.dotnet.microsoft.com/dotnet/Sdk/8.0/latest.version.
... (retries, then falls back to https://ci.dot.net/public/Sdk/8.0/latest.version) ...
Error: Failed to install dotnet, exit code: 1. dotnet_install: Error: Failed to resolve the exact version number.

Clarifying the "it already reuses the cache" behavior

When a fully pinned version (e.g. 8.0.422) is requested, the input becomes a concrete --version argument, no latest.version fetch is needed for the SDK, and the install script reports .NET Core SDK with version 'X' is already installed when it finds it on disk. This is why pinned-version runs succeed and appear to "reuse" an existing install.

However, note two things:

• This reuse is the install script detecting an SDK already present at the install directory — setup-dotnet does not consult the GitHub Actions tool cache (@actions/tool-cache) in its install path. So "preload the tool cache" (as works for actions/setup-java) does not apply here.
• Even for a pinned version, the unconditional runtime pre-install (point 1) still makes an outbound latest.version request, which fails on a fully air-gapped runner.

For floating/channel versions, the online resolution (point 2) happens before the on-disk check, so an already-satisfying local SDK is never given the chance to short-circuit the network call.

Justification:

This blocks any workflow that runs setup-dotnet with floating versions on air-gapped self-hosted runners. Notably, GitHub's Automatic Dependency Submission (ADS) for NuGet uses floating versions (8.0.x, 9.0.x, 10.0.x) and therefore always takes the online-resolution path, so it cannot be made to work offline by preinstalling SDKs or preloading the tool cache. This came up via a customer support escalation; the report is intentionally scoped to the general capability and contains no customer- or environment-specific details.

For comparison, actions/setup-java is usable in preloaded/offline scenarios because a satisfying local toolchain short-circuits the download.

Proposed behavior:

• Before performing online version resolution for a floating/channel request, check whether an already-installed SDK under the install directory (DOTNET_ROOT / DotnetInstallDir) satisfies the requested version; if so, use it and skip the network call.
• Make the runtime pre-install (point 1) tolerant of a runner with no outbound access — e.g. skip it when a suitable CLI/runtime is already present, or don't hard-require the online latest.version resolution for it.
• (Secondary) Provide a supported way to point resolution/download at an internal mirror/feed (the install scripts already support an Azure feed override), so environments that maintain a mirror can resolve floating versions offline.

Are you willing to submit a PR?

Yes — happy to collaborate on this if the maintainers agree on the approach.

[mahabaleshwars]

Hi @juxtin,
Thank you for the detailed write-up — the breakdown of the two separate network calls (the unconditional runtime pre-install and the floating/channel latest.version resolution) is really clear and matches what we see in the current code path.

We've looked into the proposal of checking the local install directory before doing any online resolution for floating/channel requests, and while the goal is exactly right, making that the default behavior would unfortunately be breaking for existing users including Github Hosted Runners. Today, a floating input like 8.0.x always resolves to the latest available patch online, and a large number of workflows rely on that "always get the newest patch" guarantee. If we silently preferred an already-installed SDK first, those users could suddenly be pinned to whatever older patch happens to be baked into their runner image — a behavior change they didn't opt into, and one that could be surprising or hard to diagnose. So we don't want to change the meaning of 8.0.x for everyone.

Instead, we're exploring a check-latest input (defaulting to true), consistent with how actions/setup-node and actions/setup-python already work:

• check-latest: true (default)→ identical to today's behavior; online resolution is used to fetch the latest patch. Fully backward-compatible, no one is affected.

• check-latest: false→ for floating/channel (and pinned) requests, we first enumerate SDKs already present under the install directory (DOTNET_ROOT/DOTNET_INSTALL_DIR) and, if one satisfies the requested range, use it andskip the network calls entirely— including the unconditional runtime pre-install, since a locally installed SDK already ships its own host and runtime. If nothing local satisfies the request, we gracefully fall back to the normal online path, so this stays safe on connected runners too.

This keeps the default experience unchanged for everyone while giving air-gapped / preloaded environments (including the floating-version scenarios you mention) an explicit, supported way to reuse an already-installed SDK offline.

On your secondary suggestion — providing a supported way to point resolution/download at an internal mirror/feed — we think that's a valuable complement and worth considering as well. As you noted, the underlying install scripts already support an Azure feed override, so surfacing a supported way to use it would let environments that maintain an internal mirror resolve floating versions offline (rather than requiring a satisfying SDK to already be on the box). We see this as complementary to check-latest: false: the local-SDK short-circuit covers preloaded/air-gapped runners, while a mirror/feed override covers environments that prefer to resolve and download from an internal source. We'd like to explore this as a follow-up alongside the check-latest work.

We're still validating the details (particularly around correctly detecting a satisfying local SDK and ensuring the host/runtime are present before skipping). We'd love your feedback and we're very happy to collaborate on the PR!