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

Artikel
01/10/2024

Note

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 vcpkg. 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:

Provide a GitHub Personal Access Token
Bootstrap vcpkg
Set up required environment variables
Add GitHub Packages as a NuGet source

Prerequisites

A code editor
A GitHub repository using GitHub Actions
A project using vcpkg

1 - Provide a GitHub Personal Access Token

Follow GitHub's instructions to generate a classic Personal Access Token (PAT) for your repository, make sure to give it the packages:write and packages:read permissions.

Then add your GitHub PAT as a secret available in your repository's GitHub Action's workflows. In this tutorial we assume that you name your secret as GH_PACKAGES_TOKEN.

The built-in PAT provided by GITHUB_TOKEN only has the packages:read permission, you can use it if you plan to have a read-only binary cache in your workflow.

2 - Bootstrap vcpkg

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

Add a step to bootstrap vcpkg in your workflow:

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

- name: Bootstrap vcpkg
  shell: bash
  run: ${{ github.workspace }}/vcpkg/bootstrap-vcpkg.sh

You may need to replace the location of the vcpkg bootstrap script with the correct one for your workflow, this tutorial assumes that vcpkg is located in a vcpkg 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>
  VCPKG_EXE: ${{ github.workspace }}/vcpkg/vcpkg
  FEED_URL: https://nuget.pkg.github.com/<OWNER>/index.json
  VCPKG_BINARY_SOURCES: "clear;nuget,https://nuget.pkg.github.com/<OWNER>/index.json,readwrite"

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

In this step you are configuring VCPKG_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 vcpkg fetch nuget command outputs the location of the vcpkg-acquired nuget.exe, downloading the executable if necessary.

Add the following step in your GitHub Actions workflow file:

- name: Add NuGet sources
  shell: pwsh
  run: |
    .$(${{ env.VCPKG_EXE }} fetch nuget) `
      sources add `
      -Source "${{ env.FEED_URL }}" `
      -StorePasswordInClearText `
      -Name GitHubPackages `
      -UserName "${{ env.USERNAME }}" `
      -Password "${{ secrets.GH_PACKAGES_TOKEN }}"
    .$(${{ env.VCPKG_EXE }} fetch nuget) `
      setapikey "${{ secrets.GH_PACKAGES_TOKEN }}" `
      -Source "${{ env.FEED_URL }}"

On Linux, you need mono to execute nuget.exe. GitHub Actions runners using Ubuntu come with mono preinstalled. Otherwise, you can install mono using your distribution's system package manager.

- name: Add NuGet sources
  shell: bash
  env: 
    VCPKG_EXE: ${{ github.workspace }}/vcpkg/vcpkg
    USERNAME: <OWNER>
    FEED_URL: https://nuget.pkg.github.com/<OWNER>/index.json
  run: |
    mono `${{ env.VCPKG_EXE }} fetch nuget | tail -n 1` \
      sources add \
      -Source "${{ env.FEED_URL }}" \
      -StorePasswordInClearText \
      -Name GitHubPackages \
      -UserName "${{ env.USERNAME }}" \
      -Password "${{ secrets.GH_PACKAGES_TOKEN }}"
    mono `${{ env.VCPKG_EXE }} fetch nuget | tail -n 1` \
      setapikey "${{ secrets.GH_PACKAGES_TOKEN }}" \
      -Source "${{ env.FEED_URL }}"

You may need to replace GH_PACKAGES_TOKEN with the correct secret name you gave to the PAT generated in the provide a GitHub Personal Access Token step.

And that's it! vcpkg 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:

Delen via