Skip to main content

Tutorial: Set up a kmpkg binary cache using GitHub Packages in a GitHub Actions workflow

info

This tutorial uses NuGet feeds hosted in GitHub Packages but the same instructions can be used for other NuGet feed providers, for example: Azure Artifacts, with minimal changes.

GitHub Packages offers a convenient repository for your NuGet binary packages produced by kmpkg. In this tutorial, we show you how to set up a binary cache in your GitHub Actions workflow that uses GitHub Packages as the remote storage.

In this tutorial, you'll learn how to:

Prerequisites​

  • A code editor
  • A GitHub repository using GitHub Actions
  • A project using kmpkg

1 - Configure authentication for GitHub Packages​

This tutorial uses the built-in GITHUB_TOKEN provided by GitHub Actions. To enable both read and write access to GitHub Packages, add the following permissions block to your workflow:

permissions:
  packages: write

This grants the GITHUB_TOKEN the necessary packages:write and packages:read permissions. Using GITHUB_TOKEN has several advantages:

  • No need to create or manage additional secrets
  • Works automatically for pull requests from forks (with read-only access)
  • Scoped to the specific repository and workflow run
info

Alternatively, you can use a classic Personal Access Token (PAT) if you need cross-repository access or other advanced scenarios. Follow GitHub's instructions to generate a classic Personal Access Token (PAT) with packages:write and packages:read permissions, then add it as a secret in your repository and use ${{ secrets.YOUR_PAT_NAME }} instead of ${{ secrets.GITHUB_TOKEN }} in the examples below.

2 - Bootstrap kmpkg​

kmpkg acquires its own copy of the nuget.exe executable that it uses during binary caching operations. This tutorial uses the kmpkg-acquired nuget.exe.

Add a step to bootstrap kmpkg in your workflow:

- name: Bootstrap kmpkg
  shell: pwsh
  run: ${{ github.workspace }}/kmpkg/bootstrap-kmpkg.bat

You may need to replace the location of the kmpkg bootstrap script with the correct one for your workflow, this tutorial assumes that kmpkg is located in a kmpkg folder in the root of the repository.

3 - Set up required environment variables​

Add the following environment variables to your workflow file (replace <OWNER> with your GitHub's username or organization's name):

env: 
  USERNAME: <OWNER>
  KMPKG_EXE: ${{ github.workspace }}/kmpkg/kmpkg
  FEED_URL: https://nuget.pkg.github.com/<OWNER>/index.json
  KMPKG_BINARY_SOURCES: "clear;nuget,https://nuget.pkg.github.com/<OWNER>/index.json,readwrite"

You may need to replace the value of KMPKG_EXE with the location of the kmpkg executable generated in the bootstrap kmpkg step.

In this step you are configuring KMPKG_BINARY_SOURCES to use your GitHub Packages feed as a binary caching source, read the binary caching reference to learn more.

4 - Add GitHub Packages as a NuGet source​

The kmpkg fetch nuget command outputs the location of the kmpkg-acquired nuget.exe, downloading the executable if necessary.

Add the following step to your workflow file to configure the NuGet source with your GITHUB_TOKEN:

permissions:
  packages: write

jobs:
  build:
    runs-on: windows-latest
    steps:
    # ... other steps ...
    - name: Add NuGet sources
      shell: pwsh
      run: |
        .$(${{ env.KMPKG_EXE }} fetch nuget) `
          sources add `
          -Source "${{ env.FEED_URL }}" `
          -StorePasswordInClearText `
          -Name GitHubPackages `
          -UserName "${{ env.USERNAME }}" `
          -Password "${{ secrets.GITHUB_TOKEN }}"
        .$(${{ env.KMPKG_EXE }} fetch nuget) `
          setapikey "${{ secrets.GITHUB_TOKEN }}" `
          -Source "${{ env.FEED_URL }}"
info

The default GITHUB_TOKEN provided by GitHub Actions does not have the required permissions to upload or download cached packages.
To enable package caching to GitHub Packages, use a Personal Access Token (PAT) instead and ensure it includes the following scopes:

  • packages:read
  • packages:write

Store the PAT as a repository secret (for example, KMPKG_PAT_TOKEN) and reference it in your workflow:

-Password: "${{ secrets.KMPKG_PAT_TOKEN }}"
-Source: "${{ env.FEED_URL }}"

And that's it! kmpkg will now upload or restore packages from your NuGet feed hosted on GitHub Packages inside your GitHub Actions workflow.

Next steps​

Authenticate to private NuGet feeds

Here are other tasks to try next: