使用 GitHub Actions 和 kmpkg 测试自定义注册表端口

当你搭建好自定义 kmpkg 端口注册表后，可能需要添加持续集成（CI） 功能，以验证所有依赖项能否成功构建。

kmpkg 官方主注册表 kumose/kmpkg 由 kmpkg 团队通过 Azure DevOps 流水线进行测试，确保新增或更新包不会影响使用者。

本文将演示如何为你自己的注册表设置 CI 环境，用于测试其中的 kmpkg 端口。

通过本文，你将学会为运行在 GitHub Actions 中的注册表搭建 CI 工作流：

为 GitHub Actions 工作流配置二进制缓存和资产缓存

搭建测试注册表端口的工作流

前提条件

拥有 GitHub 账号
已创建 kmpkg Git 注册表
已阅读二进制缓存教程
已阅读资产缓存教程

为 GitHub Actions 工作流配置二进制缓存和资产缓存

测试大量端口会消耗大量时间和计算资源。因此，在为端口配置 CI 之前，强烈建议为 GitHub Actions 工作流设置二进制缓存和资产缓存：

二进制缓存：在 CI 场景中收益最大，可确保未修改的包不会在每次 CI 运行时重复构建；
资产缓存：会镜像构建过程中下载的包制品，并在后续运行中复用缓存的制品，还能缓解上游仓库不可靠的问题（例如下载 URL 失效）。

如需详细的缓存配置步骤，请参考：

示例：在 GitHub Actions 工作流中启用资产缓存和二进制缓存

env:
  FEED_URL: https://nuget.pkg.github.com/<OWNER>/index.json # <OWNER> 替换为你的 GitHub 账号/组织名

steps:
  - name: Install kmpkg ports
    run: "${{ github.workspace }}/kmpkg/kmpkg install"
    env: 
      X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,${{ secrets.SAS }},readwrite"
      KMPKG_BINARY_SOURCES: "clear;nuget,https://nuget.pkg.github.com/<OWNER>/index.json,readwrite"

本示例展示了如何在 GitHub Actions 工作流中配置二进制缓存和资产缓存。你需要根据自己的工作流 YAML 文件调整这段代码。

配置拆解说明：

1. 资产缓存（X_KMPKG_ASSET_SOURCES）

X_KMPKG_ASSET_SOURCES 是 kmpkg 中用于配置资产缓存的环境变量。本示例中其值为 x-azurl,https://my.domain.com/container,${{ secrets.SAS }},readwrite：

x-azurl：指定使用 Azure 存储容器作为资产缓存的后端存储；
该值后紧跟三个以逗号（,）分隔的参数：
1. https://my.domain.com/container：Azure 存储容器的 URL；
2. ${{ secrets.SAS }}：GitHub Actions 机密变量，存储访问该存储容器的 SAS 令牌；
3. readwrite：设置资产缓存的读写权限（既用于存储制品，也用于从缓存恢复制品）。

2. 二进制缓存（KMPKG_BINARY_SOURCES）

KMPKG_BINARY_SOURCES 是 kmpkg 中用于配置二进制缓存的环境变量。若需启用 GitHub Actions 内置缓存作为二进制缓存后端，可将其值设为 clear;x-gha,readwrite（而非示例中的 NuGet 源）。

要使 x-gha 后端正常工作，需在工作流中添加以下必需前置步骤（需原样添加，且在所有 kmpkg 任务前执行）：

- name: Enable GitHub Actions Cache backend
  uses: actions/github-script@v7
  with:
    script: |
      core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
      core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

如需了解这些配置的底层原理，请参考：

搭建测试注册表端口的工作流

完成 CI 环境的缓存配置后，下一步是搭建工作流以测试注册表中的所有端口。你可配置工作流的触发方式：

定时触发（如每日构建）
新提交/拉取请求触发（如合并到 main 分支前测试）

注意：kmpkg 官方注册表使用的 kmpkg ci 命令是为官方需求定制的，稳定性和通用性未针对第三方用户优化，不建议用于自定义注册表测试，请遵循本文下方的步骤实现。

步骤 1：使用清单文件管理所有端口

建议通过 清单文件 创建一个依赖于注册表中所有包的构建任务，而非使用 kmpkg ci 命令。

1.1 创建 kmpkg.json（清单文件）

在注册表仓库根目录创建 kmpkg.json，列出所有需要测试的端口（替换为你的实际端口名称）：

{
  "dependencies": [
    "beicode",
    "beison"
  ]
}

1.2 创建 kmpkg-configuration.json（注册表配置文件）

若你的端口依赖官方注册表或其他第三方注册表，需在 kmpkg-configuration.json 中显式声明这些注册表。尽管 kmpkg 无需额外配置即可解析官方注册表的包，但为了版本可控，强烈建议显式添加——这能确保你完全掌控底层端口的版本集。

你可通过 kmpkg x-update-baseline 命令管理注册表的基线版本。

{
  "default-registry": null,
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/kumose/kmpkg",
      "baseline": "42bb0d9e8d4cf33485afb9ee2229150f79f61a1f",
      "packages": ["*"]
    }
  ]
}

如需了解更多配置细节，请参考：

步骤 2：在 GitHub Actions 工作流中获取 kmpkg

需在工作流中安装 kmpkg 可执行文件，添加以下步骤：

steps:
- uses: actions/checkout@v4
  with:
    repository: "kumose/kmpkg" # 拉取 kmpkg 源码
    path: "kmpkg" # 下载到工作目录的 kmpkg 子目录

- name: Bootstrap kmpkg
  run: "${{ github.workspace }}/kmpkg/bootstrap-kmpkg.sh"
  shell: bash # Linux/macOS 用 sh，Windows 用 cmd/pwsh

完成这些步骤后，你将获得可在工作流中使用的 kmpkg 可执行文件。

步骤 3：运行 kmpkg install 构建端口

最后一步是让 kmpkg 构建所有端口。你可能注意到，前文的 kmpkg-configuration.json 中未包含你自己的注册表——这是因为我们需要测试工作目录中当前版本的端口（而非注册表中已发布的版本）。

为此，需将注册表的 ports 目录设置为覆盖端口（Overlay Ports）：通过 KMPKG_OVERLAY_PORTS 环境变量指定该目录即可（覆盖端口优先级高于注册表端口）。

核心任务配置示例

  - name: Build kmpkg ports
    run: "${{ github.workspace }}/kmpkg/kmpkg install"
    env: 
      # 资产缓存配置
      X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,${{ secrets.SAS }},readwrite"
      # 二进制缓存（使用 GitHub Actions 内置缓存）
      KMPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
      # 配置覆盖端口
      KMPKG_OVERLAY_PORTS: "${{ github.workspace }}/ports"

完整工作流 YAML 示例

将所有步骤整合后，你的工作流文件（.github/workflows/test-ports.yml）应如下所示：

name: Test kmpkg ports

# 触发条件：main 分支推送/拉取请求
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]

jobs:
  build:
    runs-on: ubuntu-latest # 构建代理：Ubuntu 最新版（也可选 windows-latest/macos-latest）

    steps:
    # 拉取自定义注册表源码
    - uses: actions/checkout@v4
    
    # 拉取 kmpkg 源码
    - name: Acquire kmpkg
      uses: actions/checkout@v4
      with:
        repository: "kumose/kmpkg"
        path: kmpkg

    # 引导安装 kmpkg
    - name: Bootstrap kmpkg
      run: "${{ github.workspace }}/kmpkg/bootstrap-kmpkg.sh"
      shell: bash

    # 启用 GitHub Actions 缓存后端（二进制缓存依赖）
    - name: Enable GitHub Actions Cache backend
      uses: actions/github-script@v7
      with:
        script: |
          core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

    # 构建并测试所有端口
    - name: Build ports
      run: ${{ github.workspace }}/kmpkg/kmpkg install
      env:
        X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://your.domain.com/container,${{ secrets.SAS }},readwrite"
        KMPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
        KMPKG_OVERLAY_PORTS: "${{ github.workspace }}/ports"
      shell: bash

补充说明

这是测试注册表端口的 CI 工作流基础结构，你可能还需要根据实际场景补充以下配置：

私有 Git 注册表认证（若端口依赖私有仓库）；
NuGet 源认证（若使用私有 NuGet 作为二进制缓存）。

此外，你还可添加以下优化步骤：

自动生成 kmpkg.json 文件（避免新增端口遗漏测试）；
校验步骤（检查新增端口是否已加入测试清单）；
多平台测试（如同时测试 x64-windows/x64-linux/x64-macos）。

后续步骤

以下文档可帮助你完善 CI 环境配置：

前提条件​

为 GitHub Actions 工作流配置二进制缓存和资产缓存​

示例：在 GitHub Actions 工作流中启用资产缓存和二进制缓存​

配置拆解说明：​

1. 资产缓存（X_KMPKG_ASSET_SOURCES）​

2. 二进制缓存（KMPKG_BINARY_SOURCES）​

搭建测试注册表端口的工作流​

步骤 1：使用清单文件管理所有端口​

1.1 创建 kmpkg.json（清单文件）​

1.2 创建 kmpkg-configuration.json（注册表配置文件）​

步骤 2：在 GitHub Actions 工作流中获取 kmpkg​

步骤 3：运行 kmpkg install 构建端口​

核心任务配置示例​

完整工作流 YAML 示例​

补充说明​

后续步骤​