semantic-release-nuget
semantic-release plugin to create and publish a NuGet package.
| Step | Description |
|---|---|
verifyConditions |
Verify the presence of the NUGET_TOKEN environment variable and the presence of the dotnet executable. |
prepare |
Creates a NuGet package. |
publish |
Publish a NuGet package to the given registries. |
Install
Install the plugin as a development dependency with
npm i -D @droidsolutions-oss/semantic-release-nuget
Usage
The plugin can be configured in the semantic-release configuration file:
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@droidsolutions-oss/semantic-release-update-file",
"@semantic-release/npm",
"@droidsolutions-oss/semantic-release-nuget",
[
"@semantic-release/git",
{
"assets": ["package.json", "package-lock.json", "CHANGELOG.md", "Directory.Build.props"],
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
}
],
"@semantic-release/gitlab"
]
}
Hint: you can use the @droidsolutions-oss/semantic-release-update-file plugin to update the version number in a project or Directory.Build.props file before.
Configuration
NuGet server authentication
The NuGet server authentication is required and can be set via environment variables.
Environment Variables
| Variable | Description |
|---|---|
NUGET_TOKEN |
NuGet token of the NuGet server you want to publish tocreated via npm token create. |
CI_SERVER_URL |
If you want to publish to your GitLab server, this needs to be set. When running in GitLab CI this is already set by GitLab. |
CI_PROJECT_ID |
If you want to publish to your GitLab server, this needs to be set. When running in GitLab CI this is already set by GitLab. |
CI_JOB_TOKEN |
If you want to publish to your GitLab server, this needs to be set. When running in GitLab CI this is already set by GitLab. |
Options
| Options | Description | Default |
|---|---|---|
nugetServer |
The URL of the NuGet server to push the package to. | nuget.org |
projectPath |
The relative path to the project file to pack. | |
includeSymbols |
If true Debug symbols will be included in the package. | false |
includeSource |
If true source code will be included in the package. | false |
dotnet |
The path to the dotnet executable if not in PATH. | dotnet |
publishToGitLab |
If true, package will also be published to the GitLab registry. | false |
usePackageVersion |
If true, version is directly set via dotnet pack argument. | false |
Note: If usePackageVersion is set the version from Semantic Release is given directly to the dotnet pack command via the -p:PackageVersion=<version> argument. In this case any existing version in project files are ignored.
Note: If publishToGitLab is set the environment variables for CI_SERVER_URL, CI_PROJECT_ID and CI_JOB_TOKEN must be set. If you are running in GitLab CI this is automatically set by GitLab for you.
Note: When you add the NPM plugin to update your package.json you should set npmPublish to false to prevent Semantic Release from trying to publish an NPM package.
Versioning
There are two ways how the version is set in the created NuGet package. The easiest way (e.g. in that it does not require any additional configuration) is to set usePackageVersion to true. This will give the version that Semantic Release calculated as the next one directly as an argument to the dotnet pack command. However this has the downside of your version not being persisted in your repository files.
The recommended way to have your package versioned is to have the version in your project file (you can also use a Directory.Build.props file in your repostiory). Add a VersionPrefix (or Version) tag to it and use the Update file plugin to update the version prior to creating the package. Make sure this plugins is before the git plugin in the plugins list and add the project file or the Directory.Build.props to the assets list. See example config below.
Example config
The following is an example how to use this plugin to build semantic versioned NuGet packages. Add a Directory.Build.props to your project, depending if you want to share the values it can be anywhere from project root to next to your csproj file. This file can and should contain some metadata about your NuGet package.
Note: Instead of this special file you can also add those properties directly in your csproj file. If you do so, make sure you change the path for the update file plugin accordingly.
<Project>
<PropertyGroup>
<VersionPrefix>1.12.0</VersionPrefix>
<Authors>Stefan Ißmer</Authors>
<Company>DroidSolutions GmbH</Company>
<Description>Contains tools to help work with semantic version numbers.</Description>
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
<RepositoryUrl>https://github.com/droidsolutions/semantic-release-nuget.git</RepositoryUrl>
<RepositoryBranch>main</RepositoryBranch>
<RepositoryCommit>e5d0dbf09c927044556a876eff07b81296da8976</RepositoryCommit>
</PropertyGroup>
</Project>
No configure Semantic Release and use the update file plugin to update values in the file. Apart from the Version you can also update the commit hash and others. Refer to the Semantic Release documentation for a list of values you can use.
{
// order of plugins is important, because it is the execution order
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@droidsolutions-oss/semantic-release-update-file", // update version in Directory.Build.props
"@semantic-release/npm",
"@droidsolutions-oss/semantic-release-nuget", // create nuget package
[
"@semantic-release/git",
{
"assets": [
"package.json",
"package-lock.json",
"CHANGELOG.md",
"Directory.Build.props" // add updated file to the Semantic Release commit
],
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
}
],
"@semantic-release/gitlab"
],
"npmPublish": false, // prevent creating NPM package
"nugetServer": "https://nuget.droidnet.de/v3/index.json", // custom (private) NuGet server
"projectPath": "src/DroidSolutions.SemanticVersion/DroidSolutions.SemanticVersion.csproj", // path to the project file
"includeSymbols": true,
"publishToGitLab": true, // also publish the package to your GitLab server
"files": [
{
"path": ["Directory.Build.props"], // configure update-file pluginn to update fields in Directory.Build.props
"type": "xml",
"replacements": [
{
"key": "VersionPrefix",
"value": "${nextRelease.version}"
},
{
"key": "RepositoryCommit",
"value": "${CI_COMMIT_SHA}"
}
]
}
]
}
14 Dec 9, 2022
18 Nov 16, 2022
3 Nov 1, 2022
31 Dec 29, 2022
1 Apr 9, 2022
4 Jul 28, 2022
12 Nov 28, 2022
12 Nov 24, 2022
215 Dec 30, 2022
17 Sep 19, 2022
21 Dec 12, 2022
297 Dec 30, 2022
36 Dec 22, 2022
7 Dec 16, 2022
28 Oct 21, 2022
2k Nov 21, 2022
9 Aug 14, 2022
6 Sep 30, 2022
8 Oct 18, 2022