KtsuBuild 1.0.0
KtsuBuild
.NET build automation tool with semantic versioning, changelog generation, and multi-platform publishing.
Features
- Semantic Versioning: Automatic version calculation based on commit messages
- Changelog Generation: Auto-generated CHANGELOG.md from git history
- License Generation: Generates LICENSE.md and COPYRIGHT.md from templates
- Multi-Platform Publishing: Build and publish for Windows, Linux, and macOS
- NuGet Publishing: Publish to NuGet.org, GitHub Packages, and custom feeds
- GitHub Releases: Create releases with assets and release notes
- Winget Manifests: Generate Windows Package Manager manifests
Installation
dotnet tool install -g KtsuBuild.CLI
Quick Start
# Run the full CI/CD pipeline
ktsub ci
# Build only (restore, build, test)
ktsub build
# Show current version information
ktsub version show
# Update all metadata files
ktsub metadata update
CLI Commands
Global Options
All commands support these global options:
| Option | Short | Description | Default |
|---|---|---|---|
--workspace |
-w |
The workspace/repository path | Current directory |
--configuration |
-c |
Build configuration (Debug/Release) | Release |
--verbose |
-v |
Enable verbose output | false |
ktsub ci
Run the full CI/CD pipeline: metadata update, build, test, pack, publish, and release.
ktsub ci [options]
Options:
--dry-run: Preview actions without executing them
What it does:
- Updates metadata files (VERSION.md, CHANGELOG.md, LICENSE.md)
- Restores NuGet packages
- Builds the solution
- Runs tests with coverage
- Packs NuGet packages
- Publishes executables for all platforms
- Publishes NuGet packages to configured feeds
- Creates a GitHub release with assets
ktsub build
Build workflow: restore, build, and test.
ktsub build [options]
ktsub release
Release workflow: pack, publish NuGet packages, and create GitHub release.
ktsub release [options]
Options:
--dry-run: Preview actions without executing them
ktsub version
Version management commands.
ktsub version show
Display current version information including last tag, calculated version, and increment reason.
ktsub version show [options]
Output:
Current Version: 1.2.3
Last Tag: v1.2.2
Last Version: 1.2.2
Version Increment: Patch
Reason: Found changes warranting at least a patch version
Is Prerelease: False
ktsub version bump
Calculate and display the next version number.
ktsub version bump [options]
ktsub version create
Create or update the VERSION.md file with the calculated version.
ktsub version create [options]
ktsub metadata
Metadata file management commands.
ktsub metadata update
Update all metadata files (VERSION.md, CHANGELOG.md, LICENSE.md, COPYRIGHT.md).
ktsub metadata update [options]
Options:
--no-commit: Don't commit changes after updating
ktsub metadata license
Generate LICENSE.md and COPYRIGHT.md files from templates.
ktsub metadata license [options]
ktsub metadata changelog
Generate CHANGELOG.md from git history.
ktsub metadata changelog [options]
ktsub winget
Windows Package Manager manifest commands.
ktsub winget generate
Generate Winget manifests for a version.
ktsub winget generate --version <version> [options]
Options:
--version,-V: The version to generate manifests for (required)--repo,-r: The GitHub repository (owner/repo)--package-id,-p: The package identifier--staging,-s: The staging directory with hashes.txt
ktsub winget upload
Upload manifests to a GitHub release.
ktsub winget upload --version <version> [options]
Options:
--version,-V: The version to upload manifests for (required)
Version Increment Tags
Control version increments by including tags in your commit messages:
| Tag | Effect | Example |
|---|---|---|
[major] |
Major version bump (1.0.0 → 2.0.0) | Breaking API changes |
[minor] |
Minor version bump (1.0.0 → 1.1.0) | New features |
[patch] |
Patch version bump (1.0.0 → 1.0.1) | Bug fixes |
[pre] |
Prerelease bump (1.0.0 → 1.0.1-pre.0) | Unstable changes |
[skip ci] |
Skip release entirely | Documentation-only changes |
Examples:
git commit -m "[minor] Add new authentication feature"
git commit -m "[patch] Fix null reference in user service"
git commit -m "[major] Redesign public API"
git commit -m "[skip ci] Update documentation"
If no tag is specified, KtsuBuild automatically determines the version bump by:
- Detecting public API changes in C# files (triggers minor bump)
- Filtering out bot commits and PR merges
- Defaulting to patch for meaningful changes, prerelease otherwise
Generated Metadata Files
KtsuBuild generates and maintains these files:
| File | Purpose |
|---|---|
VERSION.md |
Contains the current version number |
CHANGELOG.md |
Complete changelog with all versions |
LATEST_CHANGELOG.md |
Changelog for the current version only |
LICENSE.md |
License file generated from template |
COPYRIGHT.md |
Copyright notice with contributors |
Environment Variables
KtsuBuild uses these environment variables when running in CI/CD:
| Variable | Description |
|---|---|
GITHUB_TOKEN |
GitHub API token for releases and packages |
NUGET_API_KEY |
NuGet.org API key for publishing |
KTSU_PACKAGE_KEY |
API key for ktsu.dev package feed |
GITHUB_SERVER_URL |
GitHub server URL (default: https://github.com) |
GITHUB_REF |
Git reference (branch/tag) |
GITHUB_SHA |
Git commit SHA |
GITHUB_REPOSITORY |
Repository in owner/repo format |
GITHUB_REPOSITORY_OWNER |
Repository owner |
EXPECTED_OWNER |
Expected owner for official builds |
Build Configuration
The build system automatically determines:
- IsOfficial: Whether the repository is the official one (not a fork)
- IsMain: Whether the build is on the main branch
- IsTagged: Whether the current commit is already tagged
- ShouldRelease: Whether a release should be created (IsMain && !IsTagged && IsOfficial)
Examples
CI/CD Pipeline (GitHub Actions)
name: CI/CD
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '9.0.x'
- name: Install KtsuBuild
run: dotnet tool install -g KtsuBuild.CLI
- name: Run CI Pipeline
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
run: ktsub ci
Local Development
# Check what version would be released
ktsub version show
# Preview CI actions without making changes
ktsub ci --dry-run
# Build and test locally
ktsub build
# Update metadata files only
ktsub metadata update --no-commit
License
This project is licensed under the MIT License - see the LICENSE.md file for details.
No packages depend on KtsuBuild.
## v1.0.0 (major)
- refactor: simplify variable declarations and enhance code readability across command files ([@matt-edmondson](https://github.com/matt-edmondson))
- Additional initial work ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor and enhance KtsuBuild utilities and services ([@matt-edmondson](https://github.com/matt-edmondson))
- feat: update default single file option and enhance build logging ([@matt-edmondson](https://github.com/matt-edmondson))
- Add Winget manifest generation functionality ([@matt-edmondson](https://github.com/matt-edmondson))
- refactor: remove unnecessary test package references and improve project detection logic ([@matt-edmondson](https://github.com/matt-edmondson))
- Initial files ([@matt-edmondson](https://github.com/matt-edmondson))
- Add unit tests for Changelog and License generation ([@matt-edmondson](https://github.com/matt-edmondson))
.NET 5.0
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.2)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.2)
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- YamlDotNet (>= 16.3.0)
.NET 9.0
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- YamlDotNet (>= 16.3.0)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.2)
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.2)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
.NET 10.0
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.2)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.2)
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.1)
- YamlDotNet (>= 16.3.0)
.NET Standard 2.0
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.2)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.2)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- YamlDotNet (>= 16.3.0)
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
.NET Standard 2.1
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.2)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.2)
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- YamlDotNet (>= 16.3.0)
.NET 8.0
- System.Text.Json (>= 10.0.2)
- YamlDotNet (>= 16.3.0)
- Polyfill (>= 9.8.1)
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.2)
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.2)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
.NET 6.0
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.2)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.2)
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- YamlDotNet (>= 16.3.0)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
.NET 7.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.2)
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.2)
- System.Text.Json (>= 10.0.2)
- Polyfill (>= 9.8.1)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- YamlDotNet (>= 16.3.0)
| Version | Downloads | Last updated |
|---|---|---|
| 1.0.0 | 51 | 02/08/2026 |