Skip to content

fix: honor global.json in docs workflow#1076

Merged
wieslawsoltes merged 1 commit intomasterfrom
fix/docs-sdk-global-json
Mar 13, 2026
Merged

fix: honor global.json in docs workflow#1076
wieslawsoltes merged 1 commit intomasterfrom
fix/docs-sdk-global-json

Conversation

@wieslawsoltes
Copy link
Copy Markdown
Owner

Overview

This change fixes the GitHub Actions Docs workflow so it resolves the same
.NET SDK version as the rest of the repository. The workflow was installing a
floating 10.0.x SDK while the repository root global.json requires
10.0.200 exactly and disables SDK roll-forward.

That mismatch caused dotnet tool restore to fail on GitHub-hosted runners once
the runner image exposed 10.0.201 instead of 10.0.200.

Problem

The repository currently pins the SDK in global.json:

  • version: 10.0.200
  • rollForward: disable

Most CI workflows already respect that by using:

with:
  global-json-file: global.json

The Docs workflow was the exception. Its setup step used:

with:
  dotnet-version: |
    10.0.x
    8.0.x
    6.0.x

On the March 13, 2026 runner image, 10.0.x resolved to 10.0.201. Because
the repo explicitly disables roll-forward, any dotnet command executed from
the repository root tried to find 10.0.200 and failed before it could run the
requested SDK command.

Observed failure:

  • Workflow: Docs
  • Step: Restore local tools
  • Command: dotnet tool restore
  • Error: compatible SDK not found for requested version 10.0.200

Root Cause

The issue was not with the local tools manifest or DocFX itself.

The root cause was inconsistent SDK provisioning across workflows:

  • build.yml, release.yml, nightly.yml, and leak-tests.yml use
    global-json-file: global.json
  • docs.yml installed a floating 10.0.x SDK instead

That meant the docs job could drift to a different patch version than the one
required by the repository.

Change Made

Updated .github/workflows/docs.yml so the Setup .NET SDKs step now includes:

global-json-file: global.json

The explicit floating 10.0.x entry was removed, while the existing 8.0.x
and 6.0.x entries were preserved.

Result:

  • the primary SDK now matches the repository pin
  • the docs workflow remains able to install extra SDK bands if they are needed
    for multi-targeting or documentation generation
  • SDK resolution behavior is now consistent across CI workflows

Why This Fix

This is the narrowest correct fix.

Alternative options were considered:

  1. Change global.json to 10.0.201
  2. Re-enable SDK roll-forward in global.json

Those options would broaden repository-wide SDK behavior. The existing exact pin
appears intentional, and the failure was isolated to the one workflow that did
not honor that pin. Aligning the workflow with the repository contract is safer
than weakening the repository contract to accommodate one workflow.

Validation

Local validation performed:

  • dotnet tool restore from the repository root succeeded
  • git diff --check passed
  • workflow YAML was reviewed to confirm the docs job now matches the repo-wide
    SDK selection strategy

GitHub validation expected after push:

  • the Docs workflow should install 10.0.200 via global.json
  • dotnet tool restore should stop failing with exit code 155

Risk Assessment

Risk is low.

  • The change affects only one workflow file
  • It does not change source code, package versions, or build logic
  • It makes the docs workflow consistent with the rest of CI rather than
    introducing a new pattern

Potential residual risk:

  • If the docs build truly depends on a floating .NET 10 patch for some reason,
    this change would remove that behavior. That is unlikely and would contradict
    the repository's current exact SDK pinning strategy.

Files Changed

  • .github/workflows/docs.yml

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant