Exploring GitHub Packages

In this lesson, you will learn how to work with GitHub Packages to enhance your DevOps workflow by hosting and managing packages—such as code dependencies and libraries—alongside your source code on GitHub. In this tutorial, we focus on creating, packaging, and publishing a NuGet package from a .NET class library in a Windows environment.

GitHub Packages supports various package formats including NuGet, NPM, and Maven. One major advantage of using GitHub Packages is that it centralizes your source code and package management, enhances package access control, easily integrates into CI/CD pipelines, and simplifies version management.

Below is a step-by-step guide demonstrating how to create a sample .NET class library for temperature conversion, package it, and publish it to GitHub Packages.

Creating the .NET Class Library

Open Visual Studio and create a new Class Library project. In this library, you will build a simple Converter class with methods to convert temperatures between Celsius, Fahrenheit, and Kelvin. After an initial test build, the namespace is updated for clarity. The final version of the class appears as follows:

namespace kodeKonvert
{
    public class Converter
    {
        public double CelsiusToFahrenheit(double celsius)
        {
            return (celsius * 9) / 5 + 32;
        }

        public double FahrenheitToCelsius(double fahrenheit)
        {
            return (fahrenheit - 32) * 5 / 9;
        }

        public double KelvinToCelsius(double kelvin)
        {
            return kelvin - 273.15;
        }

        public double CelsiusToKelvin(double celsius)
        {
            return celsius + 273.15;
        }
    }
}

After updating the namespace from "CodeKonvert" to "kodeKonvert" and confirming that the project builds successfully, proceed to configure the NuGet package metadata.

Configuring NuGet Package Metadata

Right-click on your project and select Properties. In the Properties window, configure the following settings:

• Assembly Name: Set to "CodeConvert" (or your preferred name).
• Default Namespace: Should match the assembly name.
• Version: Set to "1.0.0".
• Generate NuGet Package on Build: Enable this option to automatically produce a NuGet package with each build.
• Authors: For this demonstration, enter "KodeKloud".
• Description: Provide a brief explanation, such as "Simple library to convert temperature."

After updating these settings, click Save All and build the project. The build output confirms the creation of your DLL and NuGet package, as shown in this sample log:

Build started at 12:27 PM...
1>------ Build started: Project: KodeKonvert, Configuration: Debug Any CPU ------
1>KodeKonvert -> C:\Users\jeremy\source\repos\KodeKonvert\bin\Debug\net8.0\KodeKonvert.dll
Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped
Build completed at 12:28 PM and took 03.495 seconds

When switching to a Release configuration using:

dotnet build --configuration Release

you will see that the package is created (e.g., KodeKonvert.1.0.0.nupkg). If you encounter warnings regarding missing readme files, refer to NuGet best practices.

Setting Up GitHub Personal Access Tokens

Before publishing your package, generate a GitHub Personal Access Token (PAT) with minimum necessary permissions:

1. Go to your GitHub profile.
2. Navigate to Settings > Developer Settings > Personal Access Tokens.
3. Choose either fine-grained or classic tokens (both work for this demo).
4. Enter a descriptive note, such as "Token for building packages", and set an expiration.
5. Select the necessary scopes: repos and read and write packages.
6. Generate the token and copy it immediately—it will only be displayed once.

The following diagrams illustrate the token management screens:

Adding GitHub Packages as a NuGet Source

Next, update your local NuGet settings to use GitHub Packages as a source. Run the following command in your terminal (replace the username and token with your details):

dotnet nuget add source --username jeremykodekloud --password ghp_nJhqV0Io3 --store-password-in-clear-text --name github https://nuget.pkg.github.com/jeremykodekloud/index.json

If the package source is added successfully, you can verify it by listing all the sources:

dotnet nuget list source

The output will display sources such as nuget.org, your GitHub source, and Microsoft Visual Studio Offline Packages.

Publishing the NuGet Package to GitHub Packages

With the NuGet source configured, you can now publish your package. Ensure you specify the correct file path for your package (e.g., bin\Release\KodeKonvert.1.0.0.nupkg):

dotnet nuget push bin\Release\KodeKonvert.1.0.0.nupkg --source github --api-key ghp_nJhqV0Io3g92U9Ck4kLMrrCyhCb2y31rx9f

A successful push will display output similar to the following:

Pushing KodeKonvert.1.0.0.nupkg to 'https://nuget.pkg.github.com/jeremykodekloud'...
 PUT https://nuget.pkg.github.com/jeremykodekloud/ 380ms
Your package was pushed.

After publishing, visit your GitHub Packages page to verify that the new package ("KodeKonvert") appears as private with version "1.0.0". Linking your package to a repository can enable additional features such as a README display, discussion threads, and contributor details.

To install your package, users can run:

dotnet add package KodeKonvert --version 1.0.0

Integrating the Package into a New Project

To demonstrate how to consume the published package, create a new Blazor Web App project by executing the following commands:

dotnet new blazorwasm -o testweb
cd testweb

After the project setup, add your published NuGet package:

dotnet add package KodeKonvert --version 1.0.0

The output confirms that the package has been restored and integrated into your project:

info : Restoring packages for C:\Users\jeremy\source\repos\testweb\testweb.csproj...
info : Installed KodeKonvert 1.0.0 from https://nuget.pkg.github.com/jeremykodekloud/index.json to C:\Users\jeremy\.nuget\packages\kodekonvert\1.0.0
...

This final step demonstrates how straightforward it is to set up and consume a NuGet package hosted on GitHub Packages.

Thank you for reading this lesson on exploring GitHub Packages. For further details, check out the GitHub documentation and NuGet Package Manager guides.