Publish Private Nuget Packages on Github

Introduction

If you are already working with microservices you have probably noticed that some services shared certain files with specific functionalities or abstractions.
Refactoring these files manually can be a nightmare when they are not a part of a package as it demands repeating the changes across all services.
Working this way is not recommended and it is a bad practice too.

To simplify this process this commons files can be turned into a package, centralizing them in one location to simplify the refactoring process.
In the end we just need to release the fixes or updates, making them available to every service that depends on the package.

First Step: Create Project

For this tutorial I used a Class Library project to develop my package who will provide some commons files as base entity, dto, repository, service and controller, you can check this project in this link

Second Step: Upload your project in Github

This is the easiest step, you just need to create a github repository, link with your local repository and commit your project.

Third Step: Configure your csproject file

Locate your csproject in your IDE or Github, after that you can add a some details about your project such as version, description, author, company, tags which will help other users find your package, below I’ve provided a template from Microsoft documentation as an example:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- General project information -->
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>

    <!-- NuGet package details -->
    <PackageId>**YOUR_PROJECT_NAME**</PackageId>
    <Version>**VERSION**</Version>
    <Authors>**YOUR_NAME**</Authors>
    <Company>**COMPANY_NAME**</Company>
    <PackageTags>**TAG_NAME;TAG_NAME,TAG_NAME**</PackageTags>
    <Description>**PACKAGE_DESCRIPTION**</Description>  
    <RepositoryUrl>**https://github.com/...**</RepositoryUrl>
  </PropertyGroup>

 <!-- Dependencies -->
  <ItemGroup>
    <PackageReference/>
  </ItemGroup>

</Project>

• PackageId: The unique identifier for your package on NuGet.
• Version: Version of the package (e.g., 1.0.0).
• Authors: Name(s) of the author(s).
• Company: Name of yout company (if the package belongs to one company).
• Description: Detailed information about your package.
• PackageTags: Keywords to help users find your package.
• RepositoryUrl: Link to your project's repository.

Check the Microsoft documentation in order to know more about optional or additional fields.

Fourth Step: Github Token & Repository Secret

To publish your package, you'll need to generate a GitHub token, follow these steps:

1. Log in to your GitHub account.
2. Navigate to Settings and select Developer settings.
3. Click on Personal access tokens and then choose the Token (classic) option.
4. Generate a new token with the following permissions:

1. Copy your token immediately, as it won’t be shown again.
2. Navigate to your project repository on GitHub.
3. Click on Settings (gear icon) for the repository.
4. Go to Actions > Secrets and variables, and choose the Secrets option.
5. Click on New repository secret.
6. Paste your token and assign a name to it (e.g., GITHUB_TOKEN).

Fifth Step: NuGet.Config

Create in your root folder a NuGet.config file and paste the following code:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="Github" value="https://nuget.pkg.github.com/GITHUB_USERNAME/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <github>
        <add key="Username" value="GITHUB_USERNAME" />
        <add key="ClearTextPassword" value="GITHUB_TOKEN" />
    </github>
</packageSourceCredentials>
</configuration>

Replace the GITHUB_USERNAME with your GitHub username. You can find it in your profile or in a GitHub URL (e.g., https://github.com/username). Also, replace the GITHUB_TOKEN with your generated token.

This file allows users to download the package with the following command:

dotnet add package <PackageName>

You will need this setup when using the package in a real project to authenticate to the package source.

Why are there two package sources in this file?

When you need to use this package in a project, I set this file in the project root folder so that your project can recognize both the official NuGet packages and your/organization's custom packages.

For your custom packages, you need to provide the package source and credentials to consume the package.

You can define this file in the project root or configure it in the global NuGet file located at:
C:\Users\username\AppData\Roaming\NuGet\NuGet.Config.

Sixth Step: Github Actions

1. Create the .github Directory:

• In the root of your GitHub project repository, create a folder named .github.

2. Create the workflows Folder:

• Inside the .github folder, create another folder named workflows.

3. Add a YAML File for the Workflow:

name: Publish NuGet Package

on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
      # Step 1: Checkout the repository
      - name: Checkout code
        uses: actions/checkout@v3

      # Step 2: Setup .NET environment
      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '8.0' # Adjust based on your project

      # Step 3: Restore dependencies
      - name: Restore dependencies
        run: dotnet restore [path].Project.csproj

      # Step 4: Build the project
      - name: Build
        run: dotnet build [path].Project.csproj --configuration Release --no-restore

       # Step 5: Pack the project
      - name: Pack
        run: dotnet pack [path].Project.csproj --configuration Release --no-build -o ./packages

      # Step 6: Publish package to GitHub Packages
      - name: Publish to GitHub Packages
        run: dotnet nuget push ./packages/*.nupkg --api-key ${{ secrets.GITHUB_TOKEN }} --source "github"

Every time you commit or merge into the main branch, this will trigger the GitHub Action to publish updates to your package.

Remember to:

• Replace [path]/Project.csproj with the path to your .csproj file.
• Replace GITHUB_TOKEN with the name of your token as configured in the repository secrets.

After setting this up, you will see the job running under the Actions tab in your GitHub repository. You can review each step in the workflow log to debug any issues in case of a crash.

Seventh Step: Link the project repository to the package

1. Search for the Packages option at the top of your GitHub Profile page and click on it.
   

2. You will see somethind like this:
   

3. You can then link your package to your project repository..
   

Eighth Step: Use the package

1. Open any project where you want to use the package. In the solution folder, add the NuGet.Config file you created in the sixth step. Replace <username> and <token> with your GitHub username and token.
   

2. Open the NuGet Package Manager and click on the Settings (gear icon).
   

3. Add a new package source by providing a name and the Github link from the NuGet.Config file.
   

4. After setting the new package source, you can select the source you need and search for your package.
   

Conclusion

Now, it is easier to maintain the packages from your organization that are used across various microservices. To improve your daily workflow, you can set the GITHUB_TOKEN as a computer environment variable and link it in the NuGet.Config file.

Important: Please do not expose your GitHub token by hardcoding it in the NuGet.Config file. Instead, use environment variables for better security.

I hope this tutorial helps you!

Package Repository