跳到主要内容

教程：在 GitHub Actions 工作流中使用 GitHub Packages 搭建 kmpkg 二进制缓存

信息

本教程使用托管于 GitHub Packages 的 NuGet 源，但只需稍作修改，这些步骤也适用于其他 NuGet 源提供程序（例如 Azure Artifacts）。

GitHub Packages 可为 kmpkg 生成的 NuGet 二进制包提供便捷的存储库。本教程将指导你在 GitHub Actions 工作流中搭建二进制缓存，并使用 GitHub Packages 作为远程存储。

前提条件​

  • 代码编辑器
  • 使用 GitHub Actions 的 GitHub 仓库
  • 使用 kmpkg 的项目

1 - 配置 GitHub Packages 认证​

本教程使用 GitHub Actions 提供的内置 GITHUB_TOKEN。要为其授予对 GitHub Packages 的读写权限，请在工作流中添加以下 permissions 块：

permissions:
  packages: write

这会为 GITHUB_TOKEN 赋予必要的 packages:write 和 packages:read 权限。使用 GITHUB_TOKEN 有以下优势：

  • 无需创建或管理额外的密钥
  • 对来自复刻仓库的拉取请求自动生效（仅只读权限）
  • 权限范围限定于特定仓库和工作流运行
信息

若需要跨仓库访问或其他高级场景，也可使用经典个人访问令牌（PAT）。请按照 GitHub 的说明 生成带有 packages:write 和 packages:read 权限的经典个人访问令牌（PAT）， 然后将其添加为仓库密钥， 并在以下示例中将 ${{ secrets.GITHUB_TOKEN }} 替换为 ${{ secrets.YOUR_PAT_NAME }}。

2 - 引导初始化 kmpkg​

kmpkg 会自行获取 nuget.exe 可执行文件，用于二进制缓存操作。本教程使用 kmpkg 获取的 nuget.exe。

在工作流中添加引导初始化 kmpkg 的步骤：

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

你可能需要根据工作流调整 kmpkg 引导脚本的路径，本教程假设 kmpkg 位于仓库根目录的 kmpkg 文件夹中。

3 - 设置所需的环境变量​

在工作流文件中添加以下环境变量（将 <OWNER> 替换为你的 GitHub 用户名或组织名）：

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"

你可能需要根据引导初始化 kmpkg 步骤生成的 kmpkg 可执行文件路径，修改 KMPKG_EXE 的值。

此步骤中，你将 KMPKG_BINARY_SOURCES 配置为使用 GitHub Packages 源作为二进制缓存源。如需了解更多信息，请参阅二进制缓存参考文档。

4 - 添加 GitHub Packages 作为 NuGet 源​

kmpkg fetch nuget 命令会输出 kmpkg 获取的 nuget.exe 路径（必要时会自动下载该可执行文件）。

在工作流文件中添加以下步骤，使用 GITHUB_TOKEN 配置 NuGet 源：

permissions:
  packages: write

jobs:
  build:
    runs-on: windows-latest
    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 }}"
信息

GitHub Actions 提供的默认 GITHUB_TOKEN 不具备 上传或下载缓存包所需的权限。 若要启用向 GitHub Packages 缓存包的功能，请改用个人访问令牌（PAT），并确保其包含以下权限范围：

  • packages:read
  • packages:write

将该 PAT 存储为仓库密钥（例如 KMPKG_PAT_TOKEN），并在工作流中引用：

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

至此配置完成！kmpkg 现在会在你的 GitHub Actions 工作流中，从托管于 GitHub Packages 的 NuGet 源上传或还原包。

后续步骤​

认证私有 NuGet 源

你可尝试完成以下后续操作：