setup-dotnet

This action sets up a .NET CLI environment for use in actions by:

optionally download and install the requested .NET SDK version(s) and add them to the PATH
registering problem matchers for error output
setting up authentication to private package sources like GitHub Packages

Note: GitHub hosted runners have some versions of the .NET SDK preinstalled. Installed versions are subject to change. Please refer to the documentation: Software installed on github hosted runners for .NET SDK versions that are currently available.

What’s new in V6

Migrated action internals to ESM for compatibility with latest @actions/* packages. No changes to action inputs, outputs, or behavior.

Breaking changes in V5

Upgraded action from node20 to node24

Make sure your runner is on version v2.327.1 or later to ensure compatibility with this release. see Release Notes

For more details, see the full release notes on the release page

Usage

See action.yml

Basic:

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

Warning: Unless a concrete version is specified in the global.json file, the latest .NET version installed on the runner (including preinstalled versions) will be used by default. Please refer to the documentation for the currently preinstalled .NET SDK versions.

Multiple version installation:

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>

Supported version syntax

The dotnet-version input supports following syntax:

A.B.C (e.g 9.0.308, 10.0.100-preview.1.25120.13) - installs exact version of .NET SDK
A.B or A.B.x (e.g. 8.0, 8.0.x) - installs the latest patch version of .NET SDK on the channel 8.0, including prerelease versions (preview, rc)
A or A.x (e.g. 8, 8.x) - installs the latest minor version of the specified major tag, including prerelease versions (preview, rc)
A.B.Cxx (e.g. 8.0.4xx) - available since .NET 5.0 release. Installs the latest version of the specific SDK release, including prerelease versions (preview, rc).
latest - dynamically resolves to the highest active .NET SDK version. By default, it installs the latest stable (GA) version (excluding previews and end-of-life releases). Can be combined with dotnet-channel and dotnet-quality.

Using with `dotnet-channel` input

The optional dotnet-channel input specifies the source channel for the installation. Supported values:

Value	Description
`STS`	The most recent Standard Term Support release
`LTS`	The most recent Long Term Support release
`A.B` (e.g. `8.0`)	A specific release channel
`A.B.Cxx` (e.g. `8.0.1xx`)	A specific SDK release (available since 5.0)

Note: The dotnet-channel input is only applied when dotnet-version is set to latest. If used with a specific version, a warning will be logged and the channel input will be ignored.

Install latest LTS version:

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

Using the `architecture` input

Using the architecture input, it is possible to specify the required .NET SDK architecture. Possible values: x64, x86, arm64, amd64, arm, s390x, ppc64le, riscv64. If the input is not specified, the architecture defaults to the host OS architecture (not all of the architectures are available on all platforms).

Example: Install multiple SDK versions 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>

Using the `dotnet-quality` input

The dotnet-quality input installs the latest build of the specified quality in the channel. Supported values: daily, preview, ga. For more details about quality options, see the official .NET documentation.

Important: dotnet-quality is a single input shared across all versions listed in dotnet-version for the same step (and is only applied where supported by the version format), so per-version quality is not supported. For example, setting dotnet-quality: preview for 10.0.x and 11.0.x resolves both versions as previews. To install a released SDK alongside a preview SDK, use separate steps:

steps:
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: '10.0.x'

- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: '11.0.x'
    dotnet-quality: 'preview'

Note: When used with a specific SDK version, dotnet-quality 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, dotnet-quality will be ignored.

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

dotnet-quality can also be combined with dotnet-version: latest and dotnet-channel to target specific builds such as the latest daily build from the LTS channel.

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

Using the `global-json-file` input

setup-dotnet action can read .NET SDK version from a global.json file. Input global-json-file is used for specifying the path to the global.json. If the file that was supplied to global-json-file input doesn’t exist, the action will fail with error.

Note: In case both dotnet-version and global-json-file inputs are used, versions from both inputs will be installed.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    global-json-file: csharp/global.json
- run: dotnet build <my project>
  working-directory: csharp

Note: The action supports latest* variants of the rollForward field in global.json. When set to latestPatch, latestFeature, latestMinor, or latestMajor, the action installs the appropriate SDK version. For prerelease versions, the exact pinned version is always installed regardless of the rollForward setting.

Important: When using rollForward in global.json, the sdk.version field must be a fully-qualified SDK version (e.g., 8.0.100, 10.0.100). Wildcard versions (e.g., 10.0.*) and runtime-style versions (e.g., 8.0.0) are not supported. See the .NET SDK version specification for details.

Caching NuGet Packages

The action has a built-in functionality for caching and restoring dependencies. It uses toolkit/cache under the hood for caching global packages data but requires less configuration settings. The cache input is optional, and caching is turned off by default.

The action searches for NuGet Lock files (packages.lock.json) in the repository root, calculates their hash and uses it as a part of the cache key. If lock file does not exist, this action throws error. Use cache-dependency-path for cases when multiple dependency files are used, or they are located in different subdirectories.

Warning: Caching NuGet packages is available since .NET SDK 2.1.500 and 2.2.100 as the NuGet lock file is available only for NuGet 4.9 and above.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: 8.x
    cache: true
- run: dotnet restore --locked-mode

Note: This action will only restore global-packages folder, so you will probably get the NU1403 error when running dotnet restore. To avoid this, you can use DisableImplicitNuGetFallbackFolder option.

<PropertyGroup>
  <DisableImplicitNuGetFallbackFolder>true</DisableImplicitNuGetFallbackFolder>
</PropertyGroup>

Reduce caching size

Note: Use NUGET_PACKAGES environment variable if available. Some action runners already has huge libraries. (ex. Xamarin)

env:
  NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: 8.x
    cache: true
- run: dotnet restore --locked-mode

Caching NuGet packages in monorepos

env:
  NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: 8.x
    cache: true
    cache-dependency-path: subdir/packages.lock.json
- run: dotnet restore --locked-mode

Matrix Testing

Using setup-dotnet it’s possible to use matrix syntax to install several versions of .NET SDK:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        dotnet: [ '8.0.x', '9.0.x', '10.0.x' ]
    name: Dotnet ${{ matrix.dotnet }} sample
    steps:
      - uses: actions/checkout@v7
      - name: Setup dotnet
        uses: actions/setup-dotnet@v6
        with:
          dotnet-version: ${{ matrix.dotnet }}
      - name: Execute dotnet
        run: dotnet build <my project>

Note: Unless a concrete version is specified in the global.json file, the latest .NET version installed on the runner (including preinstalled versions) will be used by default. To control this behavior you may want to use temporary global.json files:

Matrix testing with temporary global.json creation

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        dotnet: [ '8.0.x', '9.0.x', '10.0.x' ]
    name: Dotnet ${{ matrix.dotnet }} sample
    steps:
      - uses: actions/checkout@v7
      - name: Setup dotnet
        uses: actions/setup-dotnet@v6
        id: stepid
        with:
          dotnet-version: ${{ matrix.dotnet }}
      - name: Create temporary global.json
        run: |
          echo '{"sdk":{"version": "${{ steps.stepid.outputs.dotnet-version }}"}}' > ./global.json
      - name: Execute dotnet
        run: dotnet build <my project>

Note: When generating a temporary global.json within your workflow on Windows, ensure the command is executed using a shell such as PowerShell Core (pwsh) or bash (where supported) to avoid formatting inconsistencies that could cause .NET commands to fail.

Setting up authentication for nuget feeds

Github Package Registry (GPR)

steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: '8.0.x'
    source-url: https://nuget.pkg.github.com/<owner>/index.json
  env:
    NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
- run: dotnet build <my project>
- name: Create the package
  run: dotnet pack --configuration Release <my project>
- name: Publish the package to GPR
  run: dotnet nuget push <my project>/bin/Release/*.nupkg

Azure Artifacts

- uses: actions/setup-dotnet@v6
  with:
    source-url: https://pkgs.dev.azure.com/<your-organization>/_packaging/<your-feed-name>/nuget/v3/index.json
  env:
    NUGET_AUTH_TOKEN: ${{secrets.AZURE_DEVOPS_PAT}} # Note, create a secret with this name in Settings
- name: Publish the package to Azure Artifacts
  run: dotnet nuget push <my project>/bin/Release/*.nupkg

nuget.org

- uses: actions/setup-dotnet@v6
  with:
    dotnet-version: 8.0.x
- name: Publish the package to nuget.org
  run: dotnet nuget push */bin/Release/*.nupkg -k $NUGET_AUTH_TOKEN -s https://api.nuget.org/v3/index.json
  env:
    NUGET_AUTH_TOKEN: ${{ secrets.NUGET_TOKEN }}

Note: It’s the only way to push a package to nuget.org feed for macOS/Linux machines due to API key config store limitations.

Using the `workloads` input

The workloads input allows you to install .NET workloads as part of the SDK setup. Workloads provide additional platform tools and dependencies for frameworks. This action automatically runs dotnet workload update before installing the specified workloads to ensure manifests are refreshed and existing workloads are updated to their latest compatible versions.

steps:
- uses: actions/checkout@v5
- name: Setup .NET with workloads
  uses: actions/setup-dotnet@v6
  with:
    dotnet-version: '9.0.x'
    workloads: workload1, workload2  # Specify the workloads required for the project, such as wasm-tools, maui, etc.
- run: dotnet build <my project>

Note: Ensure workloads are compatible with your runner’s OS, architecture, and .NET SDK version before enabling workload installation. Some workloads may require additional installation time due to large toolchain downloads.

Using the `check-latest` input

By default (check-latest: true) the action resolves and installs the latest version matching the request online, which is the historical behavior. With check-latest: false it first looks for an SDK already installed under DOTNET_INSTALL_DIR and reuses it, skipping SDK resolution and download — useful for air-gapped or preloaded runners (the cache and workloads inputs still use the network). If none matches, it installs online as usual.

steps:
- uses: actions/checkout@v7
- name: Reuse a preinstalled SDK when available
  uses: actions/setup-dotnet@v6
  with:
    dotnet-version: '8.0.x'
    check-latest: false
- run: dotnet build <my project>

An installed SDK is reused only when it matches the requested spec (A.B.C, A.B, A.B.x, A.B.Cxx, A, A.x or latest; x, X and * interchange except in a feature band, which is lowercase Cxx), satisfies dotnet-quality, is not older than the sdk.version declared in global.json, and sits next to a runnable dotnet executable. As online, dotnet-quality is ignored for a full A.B.C request, so such a request always resolves to a GA SDK. Cross-architecture requests, latest with an LTS or STS channel, and a bare wildcard always install online.

When the request comes from global.json, the SDK is picked the way the .NET resolver picks one: latestPatch, latestFeature, latestMinor and latestMajor take the highest SDK the policy allows, while feature, minor and major roll forward to the nearest higher feature band, minor or major and then take its latest patch. patch — the default when rollForward is omitted — prefers the declared version, otherwise the latest patch in its band. disable and a prerelease sdk.version require an exact match, and allowPrerelease is not used: dotnet-quality is the only prerelease control.

Setting `check-latest` from the environment

When the input is not set, the action reads the DOTNET_CHECK_LATEST environment variable (true or false, case-insensitive; an unsupported value warns and is ignored), which covers workflows you cannot edit. Setting it on a self-hosted runner alongside SDKs preinstalled under DOTNET_INSTALL_DIR lets those workflows run without reaching aka.ms, builds.dotnet.microsoft.com or ci.dot.net. It applies to every job on that runner, so a dedicated runner is recommended; any workflow can still override it with an explicit check-latest input.

Outputs and environment variables

Outputs

`dotnet-version`

Using the dotnet-version output it’s possible to get the installed by the action .NET SDK version.

Single version installation

In case of a single version installation, the dotnet-version output contains the version that is installed by the action.

    - uses: actions/setup-dotnet@v6
      id: stepid
      with:
        dotnet-version: 8.0.416
    - run: echo '${{ steps.stepid.outputs.dotnet-version }}' # outputs 8.0.416

Multiple version installation

In case of a multiple version installation, the dotnet-version output contains the latest version that is installed by the action.

    - uses: actions/setup-dotnet@v6
      id: stepid
      with:
        dotnet-version: | 
          8.0.416
          9.0.308
    - run: echo '${{ steps.stepid.outputs.dotnet-version }}' # outputs 9.0.308

Installation from global.json

When the dotnet-version input is used along with the global-json-file input, the dotnet-version output contains the version resolved from the global.json.

    - uses: actions/setup-dotnet@v6
      id: stepid
      with:
        dotnet-version: | 
          9.0.308
          10.0.101
        global-json-file: "./global.json" # contains version 8.0.416
    - run: echo '${{ steps.stepid.outputs.dotnet-version }}' # outputs 8.0.416

`cache-hit`

A boolean value to indicate an exact match was found for the cache key (follows actions/cache)

Environment variables

Some environment variables may be necessary for your particular case or to improve logging. Some examples are listed below, but the full list with complete details can be found here: https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-environment-variables

Env.variable	Description	Default value
DOTNET_INSTALL_DIR	Specifies a directory where .NET SDKs should be installed by the action.	default value for each OS
DOTNET_CHECK_LATEST	Fallback for the `check-latest` input, for workflows that cannot set it. Ignored when the input is set.	true
DOTNET_NOLOGO	Removes logo and telemetry message from first run of dotnet cli	false
DOTNET_CLI_TELEMETRY_OPTOUT	Opt-out of telemetry being sent to Microsoft	false
DOTNET_MULTILEVEL_LOOKUP	Configures whether the global install location is used as a fall-back	true
NUGET_PACKAGES	Configures a path to the NuGet `global-packages` folder	default value for each OS

Example usage of environment variable:

build:
  runs-on: ubuntu-latest
  env:
    DOTNET_INSTALL_DIR: "path/to/directory"
    NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
  steps:
    - uses: actions/checkout@v7
    - uses: actions/setup-dotnet@v6
      with:
        dotnet-version: '8.0.x'
        cache: true

You can also set DOTNET_INSTALL_DIR to a value based on runtime variables, such as $HOME/.dotnet or ${{ runner.temp }}/.dotnet before the setup-dotnet step:

    - name: Set DOTNET_INSTALL_DIR
      run: echo "DOTNET_INSTALL_DIR=$HOME/.dotnet" >> $GITHUB_ENV

Note: On some self-hosted or large Linux runners, installing .NET under the default /usr/share/dotnet location may fail due to insufficient permissions. To ensure successful installation, set DOTNET_INSTALL_DIR to a user-writable path.

Recommended permissions

When using the setup-dotnet action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:

permissions:
  contents: read # access to check out code and install dependencies

License

The scripts and documentation in this project are released under the MIT License

Contributions

Contributions are welcome! See Contributor’s Guide