Setup instructions for self-hosted runners

April 4, 2025 ยท View on GitHub

The CI/CD workflow for eBPF for Windows has two categories of tests. The first category is for the user mode tests (including the unit tests, fault injection tests etc.) that run on the GitHub runners. The other category is the kernel driver tests in that run on specialized pool of runners as discussed in 1es/README.md. It is recommended that a developer run the CI/CD tests in their local development environment before submitting a pull-request. While the user mode tests can be run on the development machine without a lot of prior setup, that is not true for the kernel tests.

This document describes step-by-step how a self-hosted runner can be configured to run the CI/CD kernel driver tests.

  1. Create the Self-Hosted Runner This section discusses how to create a new self-hosted runner for the developer's fork of the eBPF for Windows project. This requires administrator permissions in the project.
  2. From the settings menu in Github UI, select Actions->Runners and click on the New self-hosted-runner button. This will generate a token for the self-hosted runner.
  3. The self-hosted runner must be a Windows device running a 64-bit Windows OS.
    1. If the runner is a physical machine, it must satisfy the hardware requirements for installing Hyper-V.
    2. If the runner is a virtual machine, it must support nested virtualization.
  4. On the self-hosted runner download and install action runner following the instructions for Windows x64.
  5. Configure action runner as follows: ./config.cmd --url <fork URL> --labels 'ebpf_cicd_tests_ws2019' --token <action runner token> --runasservice --windowslogonaccount <account> --windowslogonpassword <password> For the --url parameter provide the URL to the fork for which self-hosted runner is being configured.
    For the --token parameter provide the token obtained in step 3.
    The value for --labels parameter must be set to self-hosted, matching the value of the environment field in the jobs named driver_tests and driver_native_only_tests in cicd.yml.
    The --runasservice parameter makes the action runner run as a Windows service. The runner service runs as NetworkService by default. However, the Kernel_Test_VM workflow performs operations on a test VM that requires administrator privilege. So, the credentials of an account with administrator privilege must be supplied in windowslogonaccount and windowslogonpassword parameters.
  6. Reboot the self-hosted runner.
  7. Run the setup.ps1 script to configure the self-hosted runner and install a test VM inside it.
    1. The script requires a VHD file for installing the Windows OS of your choice on to the test VM. The VHD file can be downloaded from the Microsoft Evaluation Center. Here are the download links for some of the latest Windows offerings. Windows 11 Enterprise Edition Windows Server 2022 Windows Server 2025
    2. The script requires the following powershell modules that are in the eBPF for Windows repository:
      • scripts\common.psm1
      • scripts\config_test_vm.psm1
    3. The script requires an unattend file. One is available in unattend.xml.
  8. Run the configure_vm.ps1 script to configure the test VM.