As technology evolves and we progress as a community, I notice that older blog posts erode in their helpfulness. One of the topics I find myself constantly having to relearn, especially as an OSS author, is the ability to start a new project, build a continuous integration pipeline, and get my package to NuGet. It’s essential to understand how to design a workflow that works with your project, and in this post, we’ll take a step-by-step walkthrough of how to do just that.
We’ll be using some NuGet packages, the
dotnet CLI, and GitHub Actions to build a workflow accessible, and more importantly, understandable for most .NET developers. So let’s get into it.
To follow along, you can visit the complete sample solution found at my GitHub repository.
Step 1. Creating A Solution
There are many approaches to setting up a solution folder in the .NET ecosystem, and you may notice the philosophy of each of your favorite projects can vary wildly. For the sake of this tutorial, we’ll create the most straightforward solution folder, which has our solution file, along with source and test project folders side-by-side.
The first step is to create a new solution and add two new projects. The first project will be our class library, targeting
.NET Standard 2.0. The second project will be a unit testing project with a package reference to XUnit.
Don’t worry; This approach will work regardless of how many packageable and unit tests projects you have and as long as your
sln file is accessible from the current working directory of your command line.
Step 2. Initialize Our Git Repository
Once our solution is functionally complete, we should initialize our folder as a Git repository. In some cases, our solution folder may already be a Git repository. I recommend using the GitHub CLI to create a matching remote repository, where we will eventually run GitHub Actions.
> git init > gh repo create
I’ll assume you have a basic understanding of Git at this point. If you don’t, you’ll need to read about it. Git provides a free online version of Pro Git available to everyone.
Step 3. Adding NuGet Packages
Your packageable projects will need two additional NuGet packages for this particular approach:
MinVer allows you to use Git tags to version the packageable projects. MinVer also works on the Semantic Version philosophy of major, minor, and patch numbers.
The SourceLink package allows developers to pull source code for your project, making it easier to debug issues when they happen. SourceLink is an optional package but can go a long way in helping you and your community solve problems.
<ItemGroup> <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> </PackageReference> <PackageReference Include="MinVer" Version="2.5.0"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> </PackageReference> </ItemGroup>
Step 4. Add NuGet Information To Csproj
The next step is to add the necessary information to our packageable projects
csproj files. Here’s mine as an example. It’s important to note that
PackageVersion is missing on purpose, which will be handled by
MinVer later in this guide. Also, notice the
IsPackable attribute, which informs that .NET CLI that this particular project will become a NuGet package.
<PropertyGroup> <TargetFramework>netstandard2.0</TargetFramework> <Nullable>enable</Nullable> <RootNamespace>Khalid.Fibonacci</RootNamespace> <LangVersion>Latest</LangVersion> <!-- NuGet Package Information --> <PackageId>Khalid.Fibonacci</PackageId> <PackageProjectUrl>https://github.com/khalidabuhakmeh/Khalid.Fibonacci</PackageProjectUrl> <PackageLicenseExpression>MIT</PackageLicenseExpression> <PackageTags>Fibonnaci</PackageTags> <IsPackable>true</IsPackable> <Description>Generates an iterator for Fibonacci sequence</Description> </PropertyGroup>
Step 5. Add GitHub Action Workflows
Now that we have our solution completed with packageable and unit tests projects, we need to create two GitHub workflows. One workflow will build and test our solution on pushes to
main and when pull requests are submitted. The other will publish our NuGet packages to a package respository.
We’ll first need to create a directory at the root of our solution named
.github. Under that folder, we’ll create a new
workflows folder with two files of
Let’s take a look at the
name: Build & Test on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup .NET uses: actions/setup-dotnet@v1 with: dotnet-version: 5.0.x - name: Restore dependencies run: dotnet restore - name: Build run: dotnet build --no-restore -c Release - name: Test run: dotnet test -c Release --no-build --verbosity normal
We’re using the
dotnet CLI tool to accomplish everything we need. No special build tools or clients are necessary.
Next, let’s look at our
name: Publish on: push: tags: - '**' jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup .NET uses: actions/setup-dotnet@v1 with: dotnet-version: 5.0.x - name: Restore dependencies run: dotnet restore - name: Build run: dotnet build --no-restore -c Release - name: Test run: dotnet test -c Release --no-build --verbosity normal - name: Pack run: dotnet pack -c Release -o ./nupkgs --no-build - name: Publish run: dotnet nuget push ./nupkgs/*.nupkg --api-key $ --skip-duplicate -s https://api.nuget.org/v3/index.json
publish.yaml file is similar to the
build.yaml file except for three main differences:
- We only publish when we push a new tag to the repository.
- We use the .NET CLI to pack all packable projects.
- We push all NuGet packages to our package repository by using our API Key.
To make publishing possible, you’ll need to retrieve an API key from your package repository and add the secret to the repository.
Step 6. Tag Our Commits
Now, let’s add our changes to source control using common git commands of
commit. Of course, we’ll also want to tag our commit with a version.
> git tag 1.0.0
Our tag must use the
Major.Minor.Patch convention, or
MinVer will not detect our version. Once tagged, we can push our changes up to our GitHub repository.
> git push -u origin main --tags
You should have a GitHub repository that builds and tests changes on each new commit if you followed each step. You’ll also have a GitHub repository that publishes a new package on each tagged commit.
Again, if you want to look at the final result of this post, you can see the solution in its entirety at my GitHub repository.