Skip to content

Latest commit

 

History

History
945 lines (705 loc) · 43.6 KB

readme.md

File metadata and controls

945 lines (705 loc) · 43.6 KB

dotnet-releaser User Guide

1. Overview

dotnet-releaser allows to easily automate the build 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.
  • It will publish automatically the coverage results to https://coveralls.io if your repository is created there.

overview

1.1. Getting started

1.1.1. Install dotnet-releaser

dotnet-releaser expects that .NET 6 SDK is installed.

Then you just need to install it as a global tool. Update to the latest version if you have installed it already!

dotnet tool install --global dotnet-releaser

1.1.2. Create a TOM configuration file

You need to create a TOML configuration file that will instruct which project to build and package, and to which GitHub repository.

You can use dotnet-releaser new to create this configuration file.

Let's create a .NET HelloWorld project:

dotnet new console --name HelloWorld
cd HelloWorld
dotnet-releaser new --project HelloWorld.csproj

This will create a dotnet-releaser.toml. Replace the GitHub user/repository associated with the tool. You only need to specify them if you are going to publish to GitHub.

# configuration file for dotnet-releaser
[msbuild]
project = "HelloWorld.csproj"  # You can put directly a solution file here, or also multiple projects or solution files.
[github]
user = "github_user_or_org_here"
repo = "github_repo_here"

In practice, you don't need to configure more than these defaults.

1.1.3. Build

You can cross-compile and build all packages by running the sub-command build:

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

It will create a sub folder artifacts-dotnet-releaser (Don't forget to add it to your .gitignore!) that will contain:

> ls artifacts-dotnet-releaser
HelloWorld.1.0.0.linux-arm.deb        
HelloWorld.1.0.0.linux-arm.tar.gz     
HelloWorld.1.0.0.linux-arm64.deb      
HelloWorld.1.0.0.linux-arm64.tar.gz   
HelloWorld.1.0.0.linux-x64.deb        
HelloWorld.1.0.0.linux-x64.tar.gz     
HelloWorld.1.0.0.nupkg                
HelloWorld.1.0.0.osx-arm64.tar.gz     
HelloWorld.1.0.0.osx-x64.tar.gz       
HelloWorld.1.0.0.rhel-x64.rpm         
HelloWorld.1.0.0.rhel-x64.tar.gz      
HelloWorld.1.0.0.win-arm.zip          
HelloWorld.1.0.0.win-arm64.zip        
HelloWorld.1.0.0.win-x64.zip          

1.1.4. Publish

The publish command allows to build and publish all packages to GitHub and NuGet.

dotnet-releaser publish --force --github-token "${{secrets.GITHUB_TOKEN}}" --nuget-token "${{secrets.YOUR_NUGET_SECRET_TOKEN}}"  dotnet-releaser.toml

NOTE: When running from a GitHub Action, it is recommended to use the predefined GITHUB_TOKEN accessible from your secrets: ${{secrets.GITHUB_TOKEN}}, but you might want to create your own PAT_GITHUB_TOKEN to leverage more features of dotnet-releaser. See section later in this document About GITHUB_TOKEN.

It is recommended to use dotnet-releaser run instead when running from a GitHub Action, as explained in the following section.

If you want to run this from a command line, you need to a personal access token

1.2. Adding dotnet-releaser to your CI on GitHub

You can easily replace all the steps used to build, tests, cover, pack and publish your library or application with dotnet-releaser, as it will automate entirely the publication of your package.

1.2.1. Steps for a GitHub CI Integration

In order to use dotnet-releaser on your GitHub CI, you need:

  1. Checkout your repository with the correct settings with actions/checkout
    • Verify that you are using v2 and by setting the property fetch-depth: 0 to get all previous tags. See example below.
  2. To install dotnet 6.0
  3. To install the global tool dotnet-releaser
dotnet tool install --global dotnet-releaser
  1. To run the dotnet-releaser command assuming that you have added all the secret tokens to your GitHub repository
dotnet-releaser run --nuget-token "${{secrets.NUGET_TOKEN}}" --github-token "${{secrets.GITHUB_TOKEN}}" src/dotnet-releaser.toml

It is recommended to use shell: bash on GitHub Action so that if a secrets token is empty, bash won't remove the quotes, unlike pwsh.

Depending on the kind of GitHub event, the run command will automatically:

  • If it is a pull-request or a push to a non release branch, it will perform a full build.
  • If it is a push to a branch and the branch is a release branch (configured in github.branches), then it will perform a full build and it will upload a release draft with changelog with the name of the branch prefixed by draft-{name_of_the_branch} (example: draft-main). You can disable the create of a draft release but it is usually convenient to look at what will be your next release notes.
  • If it is a push with a tag version (e.g v1.9.6 as configured with [github] section in the configuration) it will perform a full build with publish
    • For an application, it will publish multiple cross-compiled packages to your release

NOTE about the publish process:

The publish process relies on a tag commit being pushed, and the GitHub action being run on that tag commit. If you have set up your GitHub action to only run on specific branches and not on tag pushes, the dotnet-releaser publish portion of the process will never run. To fix this and still specify specific branches to run your action on, use something like this in your GitHub action:

on:
  push:
    branches:
      - main # Used for stable releases
      - develop # Used for preview releases
    tags:
      - '*' # run on all tags being pushed

1.2.2. Example of a GitHub CI Integration

An example of a setup with GitHub Actions:

    steps:
    - name: Checkout
      uses: actions/checkout@v2
      with:
        fetch-depth: 0

    - name: Install .NET 6.0
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: '6.0.x'

    - name: Build, Tests, Cover, Pack and Publish (on push tag)
      shell: bash
      run: |
        dotnet tool install --global dotnet-releaser
        dotnet-releaser run --nuget-token "${{secrets.NUGET_TOKEN}}" --github-token "${{secrets.GITHUB_TOKEN}}" src/dotnet-releaser.toml

NOTE about tokens:

It is recommended to use shell: bash on GitHub Action so that if a secrets token is empty, bash won't remove the quotes, unlike pwsh.

In order to publish changelogs, NuGet and app packages to NuGet and GitHub, you need to specify secrets tokens:

  • ${{secrets.GITHUB_TOKEN}} is available by default on GitHub Action and allow to interact directly with your repository. Nothing to create here. Unless you are going to publish an application to a separate Homebrew repository, and in that case you need to create an extra token. See Homebrew documentation for more details.
  • ${{secrets.NUGET_TOKEN}} needs to be created in your repository settings and add a secrets with the key NUGET_TOKEN by generating the token directly on your NuGet account here.

dotnet-releaser is currently not available as a GitHub Action, as it requires anyway dotnet to be installed (in order to compile the projects). As you can see, the integration is very straightforward with .NET global tools.

If you want to see an example of integration in a real project on GitHub, checkout this ci.yml from the project grpc-curl.

1.3. Prepare your project/packages

dotnet-releaser is relying on a proper configuration of your projects to detect which project should be packaged.

1.3.1. Setup correctly your project for packaging

For all projects that you want to create and publish a package for (library or executable apps), it is recommended to configure all the fields required for proper NuGet packaging.

Some of these fields are also used for deb, rpm packages for example, or used to create the homebrew project:

  <PropertyGroup>
    <Description>dotnet-releaser is a all-in-one command line tool that fully automates the release cycle of your .NET libraries and applications to NuGet and GitHub</Description> 
    <Copyright>Alexandre Mutel</Copyright>
    <NeutralLanguage>en-US</NeutralLanguage>
    <Authors>Alexandre Mutel</Authors>
    <PackageTags>releaser;packaging;deb;rpm;tool</PackageTags>
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    <PackageReleaseNotes>https://github.com/xoofx/$(AssemblyName)/blob/master/changelog.md</PackageReleaseNotes>
    <PackageIcon>$(AssemblyName).png</PackageIcon>
    <PackageProjectUrl>https://github.com/xoofx/$(AssemblyName)</PackageProjectUrl>
    <PackageLicenseExpression>BSD-2-Clause</PackageLicenseExpression>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>```
  <PropertyGroup>

1.3.2. Disable packaging for projects non package-able

In your msbuild project (e.g csproj or fsproj), you need to disable packaging for all projects that you don't want to package (e.g tests):

  <PropertyGroup>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

1.3.3. Versioning of your package

dotnet-releaser doesn't impose the way you are going to define the versioning of your package.

The version can be:

  • Manually defined in your csproj (or Directory.Build.props to share it). e.g:
    <PropertyGroup>
      <Version>1.2.0</Version>
    </PropertyGroup>
    If you don't define a version, msbuild will use the version 1.0.0 by default.
  • Automatically setup by an auto-versioning helper:

NOTE:

There are some requirements for compatible versioning of your libraries/applications with dotnet-releaser:

  • All the publish-able packages in your project should use the same version.
  • The version defined in the package to publish (e.g <Version>1.2.0</Version>) must match the version used for tagging a release. By default, the tag is expected to match the version. You can define a prefix for your tag via github.version_prefix (see [github] section below). For example you could define github.version_prefix = "v" to specify that expected tag will be e.g v1.2.0.

2. Configuration

The configuration is all done with a configuration file in the TOML format.

2.1. General

The following properties can only be set before any of the sections (e.g [msbuild], [nuget]...)

Global Type Description
profile string Defines which packs are created by default. See packaging for more details.
artifacts_folder string Defines to which folder to output created packages. By default it is setup to artifacts-dotnet-releaser relative to where to TOML configuration file is.
# This is the default, creating all the OS/CPU/Packages listed on the front readme.md
profile = "default"
# Setting `custom` will make no default packs. You need to configure them manually
# profile = "custom"
# Store the artifacts to `myfolder`
artifacts_folder = "myfolder"

2.2. MSBuild

This section defines:

  • The application project to build. This property is mandatory. There is no default!
  • The MSBuild configuration (e.g Debug or Release). Default is Release
  • Additional MSBuild properties

Example:

# MSBuild section
[msbuild]
project = "../Path/To/My/Project.csproj"
configuration = "Release"
[msbuild.properties]
PublishReadyToRun = false # Disable PublishReadyToRun
[msbuild] Type Description
project string[] Specifies a list of the path to the project (e.g csproj) or solution *.sln files to compile with MSBuild. If this path uses a relative path, it will be relative to the location of your TOML configuration file.
configuration string Specifies the MSBuild Configuration property. By default this is set to Release.
configuration_debug string Specifies the MSBuild Configuration property for a debug build. By default this is set to Debug.
properties map<string, string> Allows to defines properties that will be pass by MSBuild.
build_debug bool Specifies if you want to build also the debug version (usually only for running tests with more diagnostics). By default this is set to false.

By default, dotnet-releaser is using the following MSBuild defaults if you are going to compile a .NET executable as a single file/self contained application:

# Default values used by `dotnet-releaser`
[msbuild.properties]
PublishTrimmed = true
PublishSingleFile = true
SelfContained = true
PublishReadyToRun = true 
CopyOutputSymbolsToPublishDirectory = false
SkipCopyingSymbolsToOutputDirectory = true 

2.3. Tests

[test] Type Description
enable bool Specifies whether or not to run tests if the projects contain any tests. Default is true.
run_tests bool Run tests with the release Configuration specified in [msbuild]. Default is true.
run_tests_for_debug bool Run tests with the debug Configuration specified in [msbuild]. Default is false.

Example:

[test]
run_tests_for_debug = true   # Run the tests in debug. By default this is false.

2.4. Coverage

Coverage will produce artifacts in the output folder.

2022/02/25 05:18:37.727 info: [16492] Coverage Results:
|       | Project      | Line   | Branch | Method |
| ----- | ------------ | ------ | ------ | ------ |
|       | Tomlyn       | 84.25% | 79.65% | 82.28% |
|       | Tomlyn.Tests | 96.86% | 65.22% | 92.31% |
| Total |              | 86.86% | 78.79% | 83.02% |
[coverage] Type Description
enable bool Specifies whether or not to run coverage when running tests. Default is true.
package string The name of the NuGet package used to generate the coverage. Default is coverlet.collector
version string The version of the NuGet package used. Default is 3.1.*.
format string[] Coverage output format. These are either json (the default always added), cobertura, lcov, opencover or teamcity as well as combinations of these formats.
single_hit bool Specifies whether to limit code coverage hit reporting to a single hit for each location. Default is false
source_link bool Specifies whether to use SourceLink URIs in place of file system paths. Default is true.
include_test_assembly bool Include coverage of the test assembly. Default is true.
skip_auto_props bool Neither track nor record auto-implemented properties. Default is true.
does_not_return_attribute bool Methods marked with these attributes are known not to return, statements following them will be excluded from coverage. Default is true.
deterministic_report bool Generates deterministic report in context of deterministic build. Take a look at documentation for further informations directly on coverlet. Default is false.
exclude string[] Exclude from code coverage analysing using filter expressions.
exclude_by_file string[] Ignore specific source files from code coverage.
include string[] Explicitly set what to include in code coverage analysis using filter expressions.
include_directory string[] Explicitly set which directories to include in code coverage analysis.
badge_upload_to_gist bool Enable to publish a badge for the coverage to a GitHub gist.
badge_gist_id string Gist identifier used to publish a badge for the coverage to a GitHub gist.

Example to disable coverage:

[coverage]
enable = false

Example to disable the use of source link:

[coverage]
source_link = false

Badge coverage to Gist

dotnet-releaser allow to publish a coverage badge directly to a GitHub gist that can then be linked back from your readme.

Using this feature requires a few setup steps:

  • Create a gist with a readme.md that explain that it is a gist used by dotnet-releaser for all your repositories. For example see this gist here
  • Get the id of the gist: In the URL for example https://gist.github.com/xoofx/4b1dc8d0fa14dd6a3846e78e5f0eafae the ID of the gist is 4b1dc8d0fa14dd6a3846e78e5f0eafae
  • You can then configure the coverage by enabling pushing the badge to the specified gist:
    [coverage]
    badge_upload_to_gist = true
    badge_gist_id = "4b1dc8d0fa14dd6a3846e78e5f0eafae"
  • Then you need to create a custom GITHUB_TOKEN with the appropriate permissions
  • You need to use this token when passing it to dotnet-releaser run
  • You can then reference the badge with a URL directly to the SVG published. The file created in the gist by dotnet-releaser will be of the form dotnet-releaser-coverage-badge-{owner}-{repo}.svg. For example for the project xoofx/TurboXml the file created will be dotnet-releaser-coverage-badge-xoofx-TurboXml.svg. The link to the SVG would be simply:
    ![coverage](https://gist.githubusercontent.com/xoofx/4b1dc8d0fa14dd6a3846e78e5f0eafae/raw/dotnet-releaser-coverage-badge-xoofx-TurboXml.svg)
    Notice the gist ID in the URL that you should replace with your own gist ID.

2.5. Coveralls

The coverage results can be uploaded automatically to https://coveralls.io/

dotnet-releaser will detect automatically if there is an existing owner/repository by checking the end-point https://coveralls.io/{owner}/{repository}.json and will skip the upload to coveralls if it is not detected.

In order for the upload to coveralls to work, the --github-token passed to must be coming from ${{secrets.GITHUB_TOKEN}}.

[coveralls] Type Description
publish bool Specifies whether or not to publish to coveralls. Default is true.
url string The coveralls URL endpoint. Default is https://coveralls.io

Example to disable the use of source link:

[coveralls]
publish = false

2.6. GitHub

In order to publish to GitHub, you need to define at least the actual user and repo of your command line application.

Example:

[github]
user = "xoofx"
repo = "dotnet-releaser"
# base = "https://github.com"
# version_prefix = "v"
[github] Type Description
user string Defines the user or organization on your GitHub server.
repo string Defines the repository under your user or organization on your GitHub server.
base string Defines the base URL for your GitHub server. By default, it is using the public GitHub repository https://github.com
version_prefix string Defines the prefix to add to the package version in order to find the associated tag release on GitHub. By default, there is no prefix defined (so the package version must be == the GitHub tag). Usually, it can require that you setup a v on your prefix in case your GitHub tags are prefixed by this letter (e.g v1.0.0).
branches string[] The list of release branches that are authorized to receive a tag for a release. By default main and master are configured. If you push a version tag to a branch not listed here, you will get an error in the log.

Example:

[github]
user = "xoofx"
repo = "dotnet-releaser"
branches = ["main", "release_v2", "release_v3"] # all the branches that can be tagged with a version

2.7. Packaging

This is where you define the matrix of all the OS, CPUs and archives/packages you want to cross-compile and generate.

The kind of packaging can be define at the top level with the profile property.

profile = "default"

This defines the packaging to use the default OS/CPU/packages.

## This is the default no need to specify it
profile = "default"

For this profile, it will use by default several packs pre-configured.

A group of packages in the TOML configuration is defined by:

[[pack]] Type Description
publish bool You can disable a particular pack to be build/published.
rid string The target OS + CPU by defining its runtime identifier. See https://docs.microsoft.com/en-us/dotnet/core/rid-catalog for all the possible values.
kinds string Defines the kinds of package to create: zip, tar, deb or rpm.
renamer renamer[] A regex renamer for the final filename. A renamer is defined by the object { pattern = "regex", replace = "replacement" }. This is useful to replace a string in the package name.

For each rid define in a pack, it will create the packages defined by kinds.

For example, the default profile is creating the following packs:

# Create zip files only for Windows platforms
[[pack]]
rid = ["win-x64", "win-arm", "win-arm64"]
kinds = ["zip"]
# Default targets for Linux/Ubuntu Debian compatible distro with debian and tar packages
[[pack]]
rid = ["linux-x64", "linux-arm", "linux-arm64"]
kinds = ["deb", "tar"]
# Default targets for Linux/Redhat compatible distro with rpm and tar packages
[[pack]]
rid = ["rhel-x64"]
kinds = ["rpm", "tar"]
# Default targets for macOS, only tar files for this platform
[[pack]]
rid = ["osx-x64", "osx-arm64"]
kinds = ["tar"]

You can decide to override a specific rid, e.g

For example, defining this pack with the default profile:

[[pack]]
rid = ["win-x64"]
kinds = ["zip", "tar"]

Will only override the win-x64 to generate a zip and a tar.gz

You can disable a particular pack to be build/published.

[[pack]]
publish = false
rid = ["win-x64"]
kinds = ["zip"]

By default, all packs declared are publish = true.

You can also replace the generated filename by using a replacer:

[[pack]]
rid = ["win-x64"]
kinds = ["zip"]
renamer = [{ pattern = "win-x64", replace = "windows-amd64" }]

profile = "custom"

If you want to disable the list of default packages, you can use the custom profile.

In that case, you need to define all packs manually as described above.

You can for example target e.g win-x86 which is not generated by default.

But you can also extend the default profile by just defining this rid. It's up to what is more convenient for your setup!

2.8. NuGet

Allow to publish to a NuGet registry. By default it is on and publishing to the official NuGet public registry.

[nuget] Type Description
publish bool Allow to disable publishing to NuGet.
source string Allow to override the default publish NuGet registry (https://api.nuget.org/v3/index.json) when publishing to NuGet.
publish_draft bool Allow to publish NuGet draft packages with dotnet-releaser run. Default is false. When this option is true, even if there is no release tag on the current commit, the NuGet package will still be pushed if the current branch is listed in the main branches in github.branches. This option is useful when you want to push draft/pre-release NuGet packages per commit.

For example:

[nuget]
source = "https://my.special.registry.nuget.org/v3/index.json"
# publish = false

2.9. Homebrew

By default, a Homebrew repository and formula will be created if a tar file is generated for either a Linux or MacOS platform.

[brew] Type Description
publish bool Enable or disable Homebrew support. Default is enabled.
home string Allow to override the default homebrew repository name. See more details below.

By default, if your application name is my-application, and your GitHub user xyz, it will create and update automatically a repository at https://github.com/xyz/homebrew-my-application.

If you want to change this default behavior, and use your own homebrew repository, you can specify it by setting home:

[brew]
home = "homebrew-all-my-apps"

This repository will contain:

  • a top level readme.md
  • a folder Formula
  • a Homebrew Ruby file Formula/my-application.rb that contains the formula with all the tar files that can be installed.

See for example the generated Homebrew repository for grpc-curl

NOTE: In order to create and publish to a different repository, you will need to create a personal access GitHub Token and pass it to --github-token-extra.

By default the ${{secrets.GITHUB_TOKEN}} is only valid to interact with the current repository.

2.10. Scoop

By default, a Scoop repository (bucket) and manifest will be created if a zip file is generated for the Windows platform.

[scoop] Type Description
publish bool Enable or disable Scoop support. Default is enabled.
home string Allow to override the default scoop repository name. See more details below.

By default, if your application name is my-application, and your GitHub user xyz, it will create and update automatically a repository at https://github.com/xyz/scoop-my-application.

If you want to change this default behavior, and use your own scoop bucket, you can specify it by setting home:

[scoop]
home = "scoop-all-my-apps"

This repository will be created using the Scoop bucket template.

NOTE: In order to create and publish to a different repository, you will need to create a personal access GitHub Token and pass it to --github-token-extra.

By default the ${{secrets.GITHUB_TOKEN}} is only valid to interact with the current repository.

2.11. Changelog

dotnet-releaser comes with great defaults that can generate automatically your changelog from your commits and pull-requests.

The generated changelog can then be uploaded as part of the publish process when pushing a new release with packages.

Please follow the dedicated user-guide for configuring changelog.

2.12. Service

dotnet-releaser allows to package an application as a service that can be be automatically started by the platform supporting such kind of packages.

Currently, only Systemd services are supported for deb and rpm packages.

In order to activate support for services, you need to set:

[service]
publish = true # Allow to package the application as a service for the packages supporting it.

Then for each kind of service system, your application might require specific configuration.

2.12.1. Systemd

An example of a specific configuration for a systemd service

[service.systemd]
arguments = "/etc/my_configuration_file.toml" 
user = "xoofx"
create_user = true
[service.systemd.sections.Unit]
After = "network.target"

In the example above, we would like to pass to our service a file as an argument /etc/my_configuration_file.toml, launch the service with the user xoofx and make sure the service is started after the network.

[service.systemd] Type Description
arguments string Specifies the arguments that will be passed to your application when being run by systemd.
user string Specifies the user to use to launch the application as a service.
create_user string Creates the user/group with the name specified by service.systemd.user that will be used by the service. Default is false.
sections map The sections provides access to the underlying Unit file. See details below.

Anything that is defined after sections will be transferred to the final Unit file.

There are pre-existing sections created, like Unit or Install or Service, but you can add your own section.

[service.systemd.sections.Unit]
After = "network.target"

The service created by dotnet-releaser comes with the following defaults:

[Unit]
Description = your package description will be set here
StartLimitBurst = 4
StartLimitIntervalSec = 60
[Install]
WantedBy = multi-user.target
[Service]
ExecStart = /usr/local/bin/your-app your-arguments-or-empty
Restart = always
RestartSec = 1
Type = simple

See the Systemd configuration manual for the meaning of these defaults.

2.13. Package Dependencies

It is possible to define package dependencies if the underlying package model supports it.

NOTE: Package dependencies are currently only supported for deb and rpm.

# Adds one dependency to `a-first-runtime`
[[deb.depends]]
name = "a-first-runtime"
# Adds a dependency to a runtime with multiple versions
[[deb.depends]]
name = ["your-runtime1.0", "your-runtime2.0", "your-runtime3.0"]

In order to specify dependencies for rpm, you can use a similar syntax with [[rpm.depends]].

2.14. About GITHUB_TOKEN

By default, GitHub Actions are providing a GITHUB_TOKEN for the repository. In order for dotnet-releaser to be able to use this token correctly you need to configure in the settings of your repository:

  • Go to the menu Code and Automation/Actions/General:

    Menu Code and Automation/Actions/General

  • At the bottom of the page, under Workflow permissions, select Read and write permissions:

    Workflow permissions

Custom GITHUB_TOKEN

The default GITHUB_TOKEN should cover the basic scenarios, but you might want to create your own token to leverage more features of dotnet-releaser:

You can create and reuse the same token for all your repositories or you can create a token for each repository more selectively:

First, go to the settings for the tokens https://github.com/settings/tokens

Standard tokens

You should tick the public_repo in the list:

  • public_repo

And put an appropriate expiration date.

GitHub Setup of Personal access token

Fine-grained tokens

  1. Select Fine-grained tokens (Beta) and press the button Generate new token
  2. Select an expiration date
  3. Select the repository access
  4. In the Repository permissions, select:
    • Actions ⇒ Access: Read and write
    • Administration ⇒ Access: Read and write
    • Contents ⇒ Access: Read and write
  5. In the Account permissions, select:
    • Gists ⇒ Access: Read and write

You can then create the token and copy it and add it as a secrets environment for your GitHub Action workflows. You can use the name PAT_GITHUB_TOKEN with PAT for Personal Access Token.

3. CLI Usage

Get some help by typing dotnet-releaser --help

dotnet-releaser 0.2.0 - 2022 (c) Copyright Alexandre Mutel

Usage: dotnet-releaser [command] [options]

Options:
  --version     Show version information.
  -?|-h|--help  Show help information.

Commands:
  build         Build only the project.
  changelog     Generate changelog for the specified GitHub owner/repository and optionally upload them back.
  new           Create a dotnet-releaser TOML configuration file for a specified project.
  publish       Build and publish the project.
  run           Automatically build and publish a project when running from a GitHub Action based on which branch is active, if there is a tag (for publish), and if the change is a `push`.

Run 'dotnet-releaser [command] -?|-h|--help' for more information about a command.

3.1. dotnet-releaser new

Create a dotnet-releaser TOML configuration file for a specified project.

Usage: dotnet-releaser new [options] <dotnet-releaser.toml>

Arguments:
  dotnet-releaser.toml      TOML configuration file path to create. Default is: dotnet-releaser.toml

Options:
  --project <project_file>  A - relative - path to a solution file (.sln) or project file (.csproj, .fsproj, .vbproj). By default, it will try to find a solution file where this command is run or where the output dotnet-releaser.toml file
                            is specified.
  --user <GitHub_user/org>  The GitHub user/org where the packages will be published. If not specified, it will try to detect automatically if there is a git repository configured from the folder (and parents) of the TOML configuration
                            file, and extract any git remote that could give this information.
  --repo <GitHub_repo>      The GitHub repo name where the packages will be published. If not specified, it will try to detect automatically if there is a git repository configured from the folder (and parents) of the TOML configuration
                            file, and extract any git remote that could give this information.
  --force                   Force overwriting the existing TOML configuration file.
  -?|-h|--help              Show help information.

Example:

$ dotnet-releaser new

The command above will create a dotnet-releaser.toml configuration file and detect automatically which solution file and user/repo GitHub project from current folder.

3.2. dotnet-releaser build

Build only the project.

Usage: dotnet-releaser build [options] <dotnet-releaser.toml>

Arguments:
  dotnet-releaser.toml                The input TOML configuration file.

Options:
  --github-token <token>              GitHub Api Token. Required if publish to GitHub is true in the config file
  --skip-app-packages-for-build-only  Skip building application packages (e.g tar) when building only (but not publishing). This is useful when running on a CI and you want to build app packages only when publishing.
  --table                             Specifies the rendering of the tables. Default is square.
                                      Allowed values are: None, Ascii, Ascii2, AsciiDoubleHead, Square, Rounded, Minimal, MinimalHeavyHead, MinimalDoubleHead, Simple, SimpleHeavy, Horizontal, Heavy, HeavyEdge, HeavyHead, Double, DoubleEdge,
                                      Markdown.
                                      Default value is: Square.
  --force                             Force deleting and recreating the artifacts folder.
  -?|-h|--help                        Show help information.

Example:

$ dotnet-releaser build --project HelloWorld.csproj --user xoofx --repo HelloWorld

3.3. dotnet-releaser publish

NOTE: this command fails if the release assets have been already uploaded; use --force-upload to replace them.

Build and publish the project.

Usage: dotnet-releaser publish [options] <dotnet-releaser.toml>

Arguments:
  dotnet-releaser.toml          The input TOML configuration file.

Options:
  --github-token <token>        GitHub Api Token. Required if publish to GitHub is true in the config file
  --nuget-token <token>         NuGet Api Token. Required if publish to NuGet is true in the config file
  --github-token-extra <token>  GitHub Api Token. Required if publish homebrew to GitHub is true in the config file. In that case dotnet-releaser needs a personal access GitHub token which can create the homebrew repository. This token has
                                usually more access than the --github-token that is only used for the current repository.
  --table                       Specifies the rendering of the tables. Default is square.
                                Allowed values are: None, Ascii, Ascii2, AsciiDoubleHead, Square, Rounded, Minimal, MinimalHeavyHead, MinimalDoubleHead, Simple, SimpleHeavy, Horizontal, Heavy, HeavyEdge, HeavyHead, Double, DoubleEdge,
                                Markdown.
                                Default value is: Square.
  --force                       Force deleting and recreating the artifacts folder.
  --force-upload                Force uploading the release assets.
  -?|-h|--help                  Show help information.

3.4. dotnet-releaser run

NOTE:

This command is meant to be used only from your GitHub Action yml file.

Automatically build and publish a project when running from a GitHub Action based on which branch is active, if there is a tag (for publish), and if the change is a `push`.

Usage: dotnet-releaser run [options] <dotnet-releaser.toml>

Arguments:
  dotnet-releaser.toml                The input TOML configuration file.

Options:
  --github-token <token>              GitHub Api Token. Required if publish to GitHub is true in the config file
  --nuget-token <token>               NuGet Api Token. Required if publish to NuGet is true in the config file
  --github-token-extra <token>        GitHub Api Token. Required if publish homebrew to GitHub is true in the config file. In that case dotnet-releaser needs a personal access GitHub token which can create the homebrew repository. This
                                      token has usually more access than the --github-token that is only used for the current repository.
  --skip-app-packages-for-build-only  Skip building application packages (e.g tar) when building only (but not publishing). This is useful when running on a CI and you want to build app packages only when publishing.
  --table                             Specifies the rendering of the tables. Default is square.
                                      Allowed values are: None, Ascii, Ascii2, AsciiDoubleHead, Square, Rounded, Minimal, MinimalHeavyHead, MinimalDoubleHead, Simple, SimpleHeavy, Horizontal, Heavy, HeavyEdge, HeavyHead, Double, DoubleEdge,
                                      Markdown.
                                      Default value is: Square.
  --force                             Force deleting and recreating the artifacts folder.
  -?|-h|--help                        Show help information.

3.5. dotnet-releaser changelog

This command is useful if you want to have a look at the changelog that will be generated by dotnet-releaser.

This command can also be used to upload proper release notes for past tags in your GitHub project. See for example what was generated for Tomlyn.

Generate changelog for the specified GitHub owner/repository and optionally upload them back.

Usage: dotnet-releaser changelog [options] <dotnet-releaser.toml> <version>

Arguments:
  dotnet-releaser.toml    The input TOML configuration file.
  version                 An optional version to generate the changelog for. If it is not defined, it will fetch all existing tags and generate the logs for them.

Options:
  --update                Update the changelog on GitHub for the specified version or all versions if no versions are specified.
  --github-token <token>  GitHub Api Token. Required if publish to GitHub is true in the config file
  -?|-h|--help            Show help information.

3.6. Logs generated by dotnet-releaser

This is an example of logs generated by dotnet-releaser when running from your CI:

example log