Test your custom registry ports using kmpkg with Azure DevOps

Once you have set up a custom registry of kmpkg ports, you may want to add continous integration to validate that all your dependencies can be built successfully.

The main kmpkg registry at kumose/kmpkg is tested by the kmpkg team using a continuous integration (CI) pipeline with Azure DevOps. This ensures that adding new packages or updating existing ones does not break consumers.

In this article, we show you how to set up a CI environment to test the kmpkg ports in your own registry.

In this article, you'll learn to:

• Set up a binary cache and asset cache for your Azure DevOps pipeline
• Set up a pipeline to test your registry's ports

Prerequisites

• An Azure DevOps account
• Your own kmpkg Git registry
• Completion of the binary caching and asset caching tutorials.
• Knowledge about ADO pipelines

Set up a binary cache and asset cache for your Azure DevOps pipelines

Building a large collection of ports is an expensive task both in terms of time and computing power. We strongly recommend that before engaging CI for your ports, you invest in setting up a binary cache and an asset cache for your Azure DevOps pipelines.

A binary cache provides the most benefit for CI scenarios by ensuring that unmodified packages aren't rebuilt on every CI run. An asset cache mirrors artifacts downloaded for your packages during a run and uses the cached artifacts in subsequent runs. It can also help mitigate issues where the upstream repository is unreliable: for example, a broken download URL.

For detailed instructions on how to set up these caches read our binary caching and asset caching articles.

Example: Enable asset and binary caching in an Azure DevOps pipeline

steps: 
- task: NuGetAuthenticate@1

- script: $(Build.Repository.LocalPath)/kmpkg/kmpkg install --triplet=x64-windows
  displayName: some kmpkg task
  env:
    X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(KmpkgAssetCache),readwrite"
    KMPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/kmpkgBinaryCache/nuget/v3/index.json,readwrite"

This example shows how to set up a binary cache and asset cache in an Azure DevOps pipeline. You should adapt this snippet to use on your own pipeline's YAML file.

Breaking down this snippet:

X_KMPKG_ASSET_SOURCES is the environment variable used to configure asset caches in kmpkg. In this example, it is set to x-azurl,https://my.domain.com/container,$(KmpkgAssetCache),readwrite. The x-azurl backend instructs kmpkg to use an Azure Storage container as the storage provider. The x-azurl is followed by three parameters separated by commas (,).

• https://my.domain.com/container is a storage container URL.
• $(KmpkgAssetCache) is a pipeline secret variable that contains a SAS token to authenticate to the storage container.
• readwrite sets read and write permissions for the asset cache. This means that this asset cache is used to store artifacts as well as to restore artifacts from it.

KMPKG_BINARY_SOURCES is the environment variable used to configure binary caches in kmpkg. In this example, it is set to clear;nuget,https://my.domain.com/kmpkgBinaryCache/nuget/v3/index.json,readwrite. This enables the NuGet backend for the binary cache using the NuGet feed at https://my.domain.com/kmpkgBinaryCache/nuget/v3/index.json. Some additional steps may be required to authenticate to your NuGet feed, read the tutorial for instructions to set up NuGet authentication with ADO.

The following task should be added as-is in your pipeline in order to authenticate to your Azure Artifacts NuGet feeds. This task should also run before any task involving kmpkg.

- task: NuGetAuthenticate@1

If you're using a different host for your NuGet feeds read the documentation on how to authenticate NuGet.

Learn more about how all of these work by reading the documentation on the asset cache and binary cache features.

Set up a pipeline to test your registry's ports

After you have set up a binary cache and asset cache for your CI environment, the next step is to set up a pipeline to test all your registry's ports. You can decide whether this pipeline runs on a schedule or if it is triggered by new commits or pull requests.

The main kmpkg registry uses the kmpkg ci command, which has been tailored to the kmpkg project's needs and is not intended to remain stable or be used by consumers of kmpkg. As such, it is not suited to use for testing your own kmpkg registries. We recommend to follow the steps outlined in this article instead.

Use a manifest file to include all your ports

Instead of using the kmpkg ci command, we suggest using a manifest file to create a build that depends on all the packages in your registry.

The following example, creates a manifest file to test all the ports in a hypothetical kmpkg registry. Replace the list of dependencies to include all the ports in your registry and place it in the root of your repository.

kmpkg.json

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

Your own ports may have dependencies on the main kmpkg registry or other third-party registries, in which case, you need to add those registries in a kmpkg-configuration.json file. While kmpkg can resolve packages from the main registry without additional configuration, we strongly recommend that you explicitly add it to the registries list for version control purposes. This ensures that you have control of the set of underlying port versions. Check out the kmpkg x-update-baseline command to help managing the baseline of your registries.

kmpkg-configuration.json

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

Read the kmpkg.json and kmpkg-configuration.json reference articles to learn more. And the manifest mode documentation to learn how these work together.

Run kmpkg install to build your ports

The last step is to tell kmpkg to build all your ports. You may have noticed that your own registry is absent from the kmpkg-configuration.json created a couple of steps above. The reason is that you want to test the version of the ports currently in the working directory as opposed to the versions published in your repository.

To that goal, you need to add your registry's ports as overlay ports by setting the KMPKG_OVERLAY_PORTS environment variable to your registry's ports directory.

The snippet below shows how to set up your registry's ports as overlay ports and runs kmpkg install in manifest mode to install all of your custom ports.

steps:
- script: $(Build.Repository.LocalPath)/kmpkg/kmpkg install
  env:
    X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(KmpkgAssetCache),readwrite"
    KMPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    KMPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

In this example we assume that the kmpkg.json file is created in the root of your registry's repository and that the kmpkg repository is added as a submodule.

Putting it all together your pipelines's YAML file should look similar to this:

.azure-pipelines/test-ports.yml

trigger:
- main

pool:
  vmImage: windows-latest

steps:
- checkout: self
  submodules: true

- task: NuGetAuthenticate@1

- script: $(Build.Repository.LocalPath)/kmpkg/bootstrap-kmpkg.bat
  displayName: Bootstrap kmpkg

- script: $(Build.Repository.LocalPath)/kmpkg/kmpkg install --triplet=x64-windows
  env:
    X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(KmpkgAssetCache),readwrite"
    KMPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    KMPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

This is the basic structure for a CI pipeline to test your registry's ports. You may require some extra work to authenticate to private repositories or to your NuGet feed.

You may also want to add steps to automate the generation of the kmpkg.json file or a step that verifies that ports newly added to your registry are not left out of the tests.

Next steps

The following articles may be useful to you when setting up a CI environment.

• Authenticate to private Git registries
• Set up a binary cache using NuGet Cache
• Set up an asset cache
• Binary cache reference
• Asset cache reference
• Overlay ports
• Manifest mode
• kmpkg.json
• kmpkg-configuration.json
• kmpkg configuration environment variables