Document performance guidelines for using WSL2 runners to test code

[ssbarnea]

While WSL2 sorts lots of problems and limitations we had with WSL1, it does introduce one huge problem: disk performance between linux and the host windows filesystem (/mnt/c) is extremely slow, like 10-100x slower.

As many of those using setup-wsl action might be using it to build their codebase directly under WSL instead of under Windows, they will be facing these issues:

• actions/checkout always checks the codebase under Windows partition, likely under C:\action-runner
• using symlinks hacks like the ones describe on https://pomeroy.me/2023/12/how-i-fixed-wsl-2-filesystem-performance-issues/ article WILL NOT WORK with github runner, that is because its internals. I tried it spend a good number of hours and still failed. While the documented approach might work for a normal developer machine, it will not work with github-runner app/service and WSL. Also there are other chicken and the egg implications which make this approach not suitable: need WSL configured to setup the runner and the runner is supposed to auto-configure wsl. See https://github.com/ansible/vscode-ansible/actions/runs/13330675942/job/37233808225 for an example of simple npm packaging task that took 1h 20min instead of less than a minute. I checked and the CPU was not even high on while doing this, is something related to the FS calls that make them so slow.
• actions like archive or upload are unable to work with files from outside current workspace. All paths they receive are relative to GIT_WORKSPACE and apparently Github does not want to make any chances to allow accessing files from outside the workspace for security reasons.

Probably the solution for this problem would be to perform an rsync between the checked out source and linux user home directory, run all wsl tasks and rsync back to workspace before running other actions.

One major problem that I have is that by default all run actions run inside GITHUB_WORKSPACE which is not configurable. So even if I copy the checkout inside linux user home directory, I need to find a way to automatically CD to this folder for each action. I guess that would require changing the shell: a custom one? Would something like `"wsl-bash cd ~/code && {0}" work?

Any ideas on how to tackle these?

[Vampire]

Actually, it is very long ago, that I used my action myself. :-D
My original use-case for using the action passed by, so I mainly maintain what I have and for me the main use-case is to keep a bit used to Kotlin/JS / KMP by maintaining this action. :-)

But yes, it is a known fact, that for WSLv2 the disk-access from WSL to Windows and Windows to WSL is muuuch slower than on WSLv1 as on WSLv1 it was more or less a compatibility API similar to Cygwin, while with WSLv2 Windows and the WSL distribution are separate VMs running on the same Hypervisor and thus the file transfer is significantly slower, while all other actions are usually much faster.

actions/checkout always checks the codebase under Windows partition

Did you try to specify an absolute path pointing to a WSL location?
The action has a path parameter where you can specify where to checkout the sources.
Its description says "Relative path under $GITHUB_WORKSPACE", but that could also just mean that relative paths are resolved relative to $GITHUB_WORKSPACE, but not necessarily that you cannot specify an absolute path.
Worth a try I'd say, so for example try using checkout after this action with a path like \\wsl$\debian\root\my-project or similar.
Or if it does not work, maybe do the checkout and then use a simple copy or move operation to move over the files.

using symlinks hacks like the ones describe on https://pomeroy.me/2023/12/how-i-fixed-wsl-2-filesystem-performance-issues/ article WILL NOT WORK with github runner, that is because its internals.

Well, those symlink hacks are not too relevant, are they?
They are just to have a "local" directory on the Windows part that points to a directory within the WSL part.
That makes the WSL operations faster, but the Windows operations slower as then the Windows operations cross the slow border.
And the symlink is only necessary if you use Windows tools that cannot cope with the \\wsl$\... paths directly or if you just want to have some local folder to feel better.

What problems did you have with what was described in that article?
The essence related to your question is only "if you do many operations on WSLv2, move the files to the WSL file system.
Everything else is just sugar to work from both sides with the files, while the Windows operations will then be the slower ones.

actions like archive or upload are unable to work with files from outside current workspace. All paths they receive are relative to GIT_WORKSPACE

Are you sure?
This might be the most common case and thus what is used in the docs.
But assuming you are talking for example about upload-artifact, there is also an example the uses path: ${{ github.workspace }}/artifact/**/* which effectively resolves to an absolute path if I'm not remembering wrongly, so I'd expect any explicit path to work.
If it really does not work, well, then you have to move the files back into the workspace before using that action but I doubt it actually. :-)
From a very cursory look it doesn't seem like there is any restrictions regarding the path, as long as it is something @actions/glob can handle.

One major problem that I have is that by default all run actions run inside GITHUB_WORKSPACE which is not configurable.

Not configurable? o_O
How about something like:

defaults:
  run:
    working-directory: \\wsl$\debian\root\my-project

?
https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#defaultsrunworking-directory

[Vampire]

For the last point also see #13 for exactly this topic and also a way to do it with a custom shell command.