Argomenti trattati
The actions/setup-dotnet action prepares a runner with the .NET SDK and related tooling so workflows can build and publish .NET projects. It can download and cache one or more SDK versions, add them to the PATH, register problem matchers for build diagnostics, and configure authentication to private package feeds such as GitHub Packages or Azure Artifacts. Note that GitHub hosted runners ship with several preinstalled SDKs; those preinstalled versions change over time, so consult the hosted runner software documentation to see which .NET SDK versions are currently available.
This release series, identified as v5 of the action, includes internal runtime upgrades (the action now runs on node24) and requires a recent runner agent. Ensure self-hosted runners or actions runners use version v2.327.1 or later for compatibility with the updated runtime. For a complete list of changes and behavioral details, review the action’s release notes on the project’s releases page.
Basic usage and version selection
To use the action, add a step that references actions/setup-dotnet@v5 in your workflow. Provide the dotnet-version input to control which SDKs are installed; you can include a single value or a vertical list for multiple installs. If you do not pin a version in a repository global.json file, the highest applicable SDK installed on the runner may be used by default. When you need deterministic builds across matrix runs, you can either specify exact SDK versions or generate a temporary global.json in a prior workflow step that points to the resolved SDK installed by the action.
Version syntax, channels, and architecture
The dotnet-version input accepts several formats: exact SDK builds like A.B.C, major/minor channels such as A.B or A.B.x, abbreviated major releases A or A.x, and the special latest token that resolves to the highest active SDK. The historical A.B.Cxx format is supported for certain release patterns. Use dotnet-channel to influence latest resolution (for example, LTS or STS), but be aware the channel input is ignored when a specific SDK version is directly specified and a warning will be emitted.
Architecture and quality flags
You can tailor installations by setting the architecture input to values such as x64, x86, arm64, and other supported CPU families. When you require builds from different maturity levels, the dotnet-quality input can request daily, preview, or ga builds. Note that quality selection has constraints when paired with certain version formats: it applies only to versions expressed at a channel or major/minor level in newer SDKs.
Caching, workloads, and dependency files
The action optionally provides integrated caching for NuGet dependencies. When caching is enabled, it searches for lock files like packages.lock.json at the repository root, computes a hash, and includes that in the cache key. If a lock file is absent, the action fails unless you point it to an explicit path via the cache-dependency-path input. Because only the global-packages folder is restored by this mechanism, reusable projects may need the DisableImplicitNuGetFallbackFolder property or proper restore flags to avoid NU1403 errors during restore.
Workloads and monorepos
For workloads such as wasm-tools or maui, supply a comma-separated list to the workloads input; the action runs dotnet workload update before installing the requested workloads to refresh manifests. In monorepo layouts, set the NUGET_PACKAGES environment variable to direct the global-packages cache to a workspace path and use cache-dependency-path to reference lock files in subdirectories so caches are properly isolated and smaller.
Authentication, outputs, and environment variables
The action can configure authentication for package sources by accepting a source-url input and reading a token from an environment secret like NUGET_AUTH_TOKEN. This enables publishing to GitHub Packages, Azure Artifacts, or pushing to nuget.org (the latter requires passing the API key during push on macOS and Linux). The action exposes outputs such as dotnet-version, which reports the installed SDK for single-version installs or the highest installed version for multi-version installs, and cache-hit, which follows actions/cache semantics to indicate a cache match.
Several environment variables influence behavior and defaults: DOTNET_INSTALL_DIR controls installation location, DOTNET_NOLOGO suppresses CLI banners, DOTNET_CLI_TELEMETRY_OPTOUT controls telemetry, and DOTNET_MULTILEVEL_LOOKUP toggles fallback to global install locations. Default install and packages paths differ by OS, so set DOTNET_INSTALL_DIR to a writable path on self-hosted Linux runners to avoid permission issues. Finally, grant your workflow minimal permissions such as contents: read so the action can check out code and install dependencies.