How to run your WSL GitHub workflow on Azure

Most of the time, what works on Ubuntu desktop works on WSL as well. However, there are some exceptions. Furthermore, you may want to test software that lives both on Windows and inside WSL. In these cases, you may want to run your automated testing on a Windows machine with WSL rather than a regular ubuntu machine.

There exist Windows GitHub runners, but they do not support the latest version of WSL. The reason is that WSL is now a Microsoft Store application, which requires a logged-in user. GitHub runners, however, run as a service. This means that they are not on a user session, hence they cannot run WSL (or any other store application).

Summary

We propose you run your automated tests on a Windows virtual machine hosted on Azure. This machine will run the GitHub actions runner not as a service, but as a command-line application.

Step-by-step

This guide will show you how to set up an Azure VM to run your WSL workflows.

  1. Create a Windows 11 VM on Azure: follow Azure’s instructions, no special customisation is necessary.

    Note: You can use any other hosting service. We use Azure in this guide because that is what we use for our CI.

  2. Install WSL with wsl --install.

  3. Enable automatic logon: use the registry to set up your machine to log on automatically. Explanation here.

  4. Add your runner to your repository: head to your repository’s page on GitHub > Settings > Actions > Runners > New self-hosted runner. Follow the instructions. Make sure you do not enable running it as a service.

  5. Set up your runner as a startup application:

    1. Go to the directory you installed the GitHub runner.

    2. Right-click on the run.cmd file, and click Show more options > Send to > Desktop (create shortcut).

    3. Press Win+R, type shell:startup and press OK. A directory will open.

    4. Find the shortcut in the desktop and drag it to the startup directory.

  6. Set up your repository secrets To add a new secret, head to your repository’s page on GitHub > Settings > Secrets > Actions > New repository secret. You’ll need the following secret:

    • AZURE_VM_CREDS: See the documentation here.

  7. Create your GitHub workflow. This workflow must have at least three jobs which depend each on the previous one.

    1. Start up the VM

    2. Your workflow(s)

    3. Stop the VM

    It is also recommended to add a concurrency directive to prevent different workflows from interleaving steps 1 and 3.

  8. Use our actions. We developed some actions to help you build your workflow. They are documented in the WSL GitHub actions reference.

Example repositories

The following repositories use some variation of the workflow explained here.