dotnet-releaser

dotnet-releaser is an all-in-one command line tool that fully automates the release cycle of your .NET libraries and applications to NuGet and GitHub by building, testing, running coverage, cross-compiling, packaging, creating release notes from PR/commits and publishing.

In practice, dotnet-releaser will automate the build and publish process of your .NET libraries and applications by wrapping:

• dotnet build with potentially multiple solutions
• dotnet test
  • Plus the automatic support for coverage.
• dotnet pack for creating NuGet packages
• dotnet publish that can automatically cross-compile to 9+ CPU/OS platforms.
  • And create additionally, by default, multiple packages (zip, debian, rpm...) to distribute your app
• dotnet nuget push to publish your package to a NuGet registry
• Pretty changelog creation from pull-requests and commits.
• Create and upload the changelog and all the packages packed to your GitHub repository associated with the release tag.
• dotnet-releaser tool requires .NET 9.0 runtime to be installed.

Features

• Very simple to use, configure and integrate into your GitHub Action CI
• Build and tests your .NET libraries and applications from multiple solutions.
• Add automatic coverage support via coverlet with your tests.
• Cross-compile your .NET 6.0+ application to 9+ OS/CPU targets.
• Create zip archives, Linux packages (debian, rpm) and Homebrew taps
• Allow to publish your application as a service (only Systemd for now for deb and rpm packages).
• Create and publish beautiful release notes by extracting the information directly from pull-requests and commits, while offering customizable templates.
• Publish all artifacts to NuGet and GitHub
• Can be used to build/tests/package/publish locally or from GitHub Action using the same command.

Defaults

By default, dotnet-releaser will:

• Build your project(s)/solution(s) in Release
• Run tests in Release
• Create NuGet packages for libraries and applications (packed as a .NET global tool)
• Create application packages for any packable application in your project:

  Platform	Packages
  win-x64, win-arm64	zip
  linux-x64, linux-arm64	rpm, deb, tar
  osx-x64, osx-arm64	tar

• Publish libraries and/or applications to NuGet
• Upload all the package artifacts and your changelog to GitHub on the tag associated with your package version (e.g your package is 1.0.0, it will try to find a git tag v1.0.0 or 1.0.0).
• Create a Homebrew repository and formula (e.g user_or_org/homebrew-your-app-name) for all the tar files associated with the targets for Linux and MacOS.

Any of these steps can be configured or even entirely disabled easily from a config file. See the user guide on how to setup this differently for your application.

Getting Started

• Install dotnet-releaser as a global .NET tool.

  dotnet tool install --global dotnet-releaser
  

• Go to a folder where you have your solution .sln/.slnx file or your project file (.csproj, .fsproj, .vbproj) and run:

  dotnet releaser new
  

• It should create a dotnet-releaser.toml at the same level than your solution with a content like:

  [msbuild]
  project = "Tonlyn.sln"
  [github]
  user = "xoofx"
  repo = "Tomlyn"
  

• If you want to try a full build locally:

  dotnet-releaser build --force dotnet-releaser.toml
  

• If you want to integrate it to GitHub Action, use the dotnet-releaser run command. More details in the doc Adding dotnet-releaser to your CI on GitHub. It is no more complicated than adding the following lines in your GitHub workflow file:

    permissions:
      # Required to create/update GitHub releases, tags, release notes and assets with GITHUB_TOKEN.
      # Use contents: read only if you do not publish anything back to GitHub.
      contents: write
      # Required by NuGet trusted publishing (`nuget.trusted_publishing = true`).
      id-token: write
  
    steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
  
    - name: Install .NET 10.0
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '10.0.x'
  
    - name: Build, Tests, Cover, Pack and Publish (on push tag)
      shell: bash
      run: |
        dotnet tool install --global dotnet-releaser
        dotnet-releaser run --github-token "${{secrets.GITHUB_TOKEN}}" src/dotnet-releaser.toml
  

  This example assumes [nuget] trusted_publishing = true and user = "your-nuget-user" in dotnet-releaser.toml; you can still pass --nuget-token "${{secrets.NUGET_TOKEN}}" if you use a classic NuGet API key. If you call dotnet-releaser from a reusable workflow, grant these permissions on the caller job. actions: write is not required by dotnet-releaser itself unless another step in your workflow needs the GitHub Actions API.

See the user guide below for further details on how to use dotnet-releaser.

User Guide

For more details on how to use dotnet-releaser, please visit the user guide.

License

This software is released under the BSD-Clause 2 license.

Who is using dotnet-releaser?

It's brand new, so it's mainly used by the author for now! 😇

You can visit the .github/workflows folder, or check the release notes of the following projects to see dotnet-releaser in action:

Applications:

• grpc-curl: An application shipping multiple executables.
• lunet: An application shipping a .NET global tool to NuGet.

Regular .NET Libraries:

• Markdig
• Scriban
• Tomlyn
• Zio

Credits

dotnet-releaser is a wrapper around many amazing OSS libraries:

• dotnet-packaging by using their NuGet Packaging.Targets to hook package creation into MSBuild user's project.
• XenoAtom.CommandLine for handling parsing command line arguments.
• XenoAtom.Logging for logging to the console.
• MsBuildPipeLogger for interacting with MSBuild structured output.
• Octokit.NET for interacting with GitHub.
• Tomlyn for parsing the TOML configuration file.
• CliWrap to easily wrap and launch executables.
• Spectre.Console for generating pretty logs and table reports.
• Scriban used for text templating of the changelog/release notes.
• DotNet.Glob used by changelog filtering on files.

Author

Alexandre Mutel aka xoofx.