setup-dotnet: GitHub Action for installing .NET SDK versions

What setup-dotnet solves in a GitHub Actions workflow

setup-dotnet sets up a .NET CLI environment for use in GitHub Actions. It optionally downloads and installs the requested .NET SDK version or versions and adds them to PATH, registers problem matchers for error output, and sets up authentication to private package sources such as GitHub Packages.

The intended user is a developer maintaining a GitHub Actions workflow that builds, tests, or packs a .NET project. GitHub hosted runners already have some .NET SDK versions preinstalled, but those versions can change, so pinning a version through this action makes builds reproducible. The action is licensed under MIT and is authored by GitHub.

How version selection and installation work

The dotnet-version input supports several syntaxes. An exact version such as 9.0.308 or 10.0.100-preview.1.25120.13 installs that specific SDK. A major.minor or major.minor.x such as 8.0 or 8.0.x installs the latest patch on that channel, including prereleases. A major or major.x such as 8 or 8.x installs the latest minor version of that major tag, including prereleases. An A.B.Cxx form such as 8.0.4xx installs the latest version of that SDK release, available since .NET 5.0. The keyword latest resolves dynamically to the highest active .NET SDK version, by default the latest stable GA version excluding previews and end-of-life releases.

The optional dotnet-channel input specifies the source channel and supports STS for the most recent Standard Term Support release, LTS for the most recent Long Term Support release, A.B for a specific release channel, and A.B.Cxx for a specific SDK release. It applies only when dotnet-version is set to latest; with a specific version a warning is logged and the channel input is ignored.

The dotnet-quality input installs the latest build of a specified quality in the channel, with values daily, preview, and ga. It is shared across all versions in the same step and is only applied where the version format supports it. To install a released SDK alongside a preview SDK, separate steps are required.

The architecture input accepts x64, x86, arm64, amd64, arm, s390x, ppc64le, and riscv64. If omitted, it defaults to the host OS architecture, and not all architectures are available on all platforms.

The global-json-file input reads the SDK version from a global.json file. If the supplied file does not exist, the action fails with an error.

Basic usage in a workflow

The README gives a basic workflow example.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: '8.0.x'
- run: dotnet build <my project>

Unless a concrete version is specified in global.json, the latest .NET version installed on the runner, including preinstalled versions, will be used by default. Pinning a version through dotnet-version avoids that surprise.

Multiple versions can be installed in one step.

steps:
- uses: actions/checkout@v7
- name: Setup dotnet
  uses: actions/setup-dotnet@v6
  with:
    dotnet-version: | 
      8.0.x
      9.0.x
- run: dotnet build <my project>

The action can also install for a specific architecture.

steps:
- uses: actions/checkout@v7
- name: Setup dotnet (x86)
  uses: actions/setup-dotnet@v6
  with:
    dotnet-version: |
      8.0.x
      9.0.x
    architecture: x86
- run: dotnet build <my project>

Channels, qualities, and global.json

Installing the latest LTS version uses dotnet-version latest with dotnet-channel LTS.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: latest
    dotnet-channel: LTS

Quality can be combined with version and channel.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: '8.0.x'
    dotnet-quality: 'preview'
- run: dotnet build <my project>

The latest daily build from the LTS channel combines all three inputs.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: latest
    dotnet-channel: LTS
    dotnet-quality: daily

When dotnet-quality is used with a specific SDK version, it supports only A.B, A.B.x, A, A.x, and A.B.Cxx formats where the major version is higher than 5. For all other formats it is ignored. To install a released SDK alongside a preview SDK, separate steps must be used, as shown in the README.

Breaking changes and runtime requirements

Version 5 upgraded the action from node20 to node24, and the runner must be on version v2.327.1 or later for compatibility. Version 6 migrated the action internals to ESM for compatibility with the latest @actions packages, with no changes to action inputs, outputs, or behavior.

Recent releases are v6.0.0 on 2026-07-16, v5.4.0 on 2026-06-26, and v5.3.0 on 2026-05-28. The last push was on 2026-10-05. The package.json declares node engine >=24.0.0 and version 6.0.0.

The README warns that GitHub hosted runner preinstalled versions are subject to change, and points to the runner documentation for currently available versions. That volatility is the main reason to pin versions explicitly.

Limitations and when setup-dotnet is the wrong tool

setup-dotnet is the wrong tool if you only need the .NET SDK versions already preinstalled on GitHub hosted runners and do not care which patch is used. It is also the wrong tool for non-GitHub CI systems, since it is a GitHub Action.

The dotnet-channel input is ignored when a specific version is given, and dotnet-quality has format and major-version restrictions. These interactions can produce a silent mismatch between what a workflow author expects and what is installed. A workflow that mixes preview and stable SDKs needs separate steps, which adds verbosity.

The README does not document rollback, offline installation, or behavior when a requested version is unavailable.

Alternatives and how the approach differs

The README does not name a competing setup action, but the approach differs from manual installation in that it combines SDK installation, PATH registration, problem matchers, and private source authentication in one step. A manual approach would run dotnet-install scripts and configure credentials separately, giving more control but requiring more workflow code.

The trade-off is convenience versus control. setup-dotnet hides the install script details and centralizes version syntax, but its inputs are the only configuration surface. Teams with unusual authentication or architecture needs should verify that the supported inputs cover their case.

Maintenance, licensing and upgrade cost

The repository is not archived and the last push was on 2026-10-05. The license is MIT. The action is TypeScript with Jest tests, ESLint, Prettier, and Husky hooks, and it builds with @vercel/ncc into dist.

Upgrade cost is driven by the Node runtime requirement and the @actions package ecosystem. V5 moved from node20 to node24 and V6 moved the internals to ESM, so workflow authors should check runner versions when upgrading. Because the action bundles its dependencies into dist, consumers install a prebuilt artifact rather than managing packages themselves.

The MIT license allows use, modification, and distribution, including in commercial products, but this is not legal advice and a team should have counsel review its obligations.

Editorial conclusion

Adopt setup-dotnet if your GitHub Actions workflows build .NET projects and you need a specific SDK version or channel. Skip it if you only use preinstalled runner SDKs and do not need version control. Verify the runner version requirement and the version syntax you rely on before pinning a major version.

Frequently asked questions

Official sources

1. actions/setup-dotnet on GitHub
2. Issues
3. License: MIT
4. README
5. Releases