A GitHub Action to start an ephemeral QEMU-based runner VM via Tailscale.

You'll need the following things:

• A Tailscale tailnet with one or more machines with QEMU installed.
• A OAuth client configured on the tailnet.
• Tailscale SSH needs to be enabled on the tailnet, with appropriate accept ACLs configured. accept must be used for SSH ACLs, check is not supported. Tailscale ephemeral nodes are automatically tagged with the value from ts-tag, this tag can be used with ACLs.
• A GitHub Personal Access Token with appropriate permissions to request a runner registration token via the GitHub REST API.

At a minimum, your workflow should look like this:

jobs:
  create-runner:
    name: Create self-hosted Actions runner
    runs-on: ubuntu-latest
    steps:
      - name: Create self-hosted Actions runner
        uses: MattKobayashi/[email protected]
        with:
          gh-api-token: ${{ secrets.GH_API_TOKEN }}
          ssh-host: 192.0.2.1
          ssh-user: matthew
          ts-oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
          ts-oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}

Ephemeral runners will remove themselves after completing a single job in a workflow. If you have multiple jobs to execute, a matrix can be used to spawn multiple runners:

jobs:
  create-runner:
    name: Create self-hosted runner VM
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      max-parallel: 1
      matrix:
        runner-name: [test]
    steps:
      - name: Create self-hosted Actions runner
        uses: MattKobayashi/[email protected]
        with:
          gh-api-token: ${{ secrets.GH_API_TOKEN }}
          ssh-host: 192.0.2.1
          ssh-user: matthew
          ts-oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
          ts-oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}

• QEMU image files are stored in /tmp/actions-runners/. If you're processing many jobs, this directory can grow quite large. It's recommended to create a cronjob on the QEMU host to regularly clean up this directory. /tmp is also cleared when the host is rebooted.
• Container-based tasks are fully supported.
• The default values for gha-runner-cpus and gha-runner-mem match those of GitHub's hosted runners, however these values are also quite large. It is important to be mindful of this, and adjust these values as necessary.

Required A GitHub Personal Access Token with repo scope, or a fine-grained access token with administration:write permission.

The APT mirror to configure in the self-hosted runner VM. Defaults to http://archive.ubuntu.com/ubuntu.

The number of CPUs to allocate to the self-hosted runner VM. Defaults to 4.

Configures debug mode on the self-hosted runner VM. Debug mode holds the CLI connection open instead of detaching the QEMU process and stopping the hosted runner. Defaults to disabled.

The size of the self-hosted runner VM disk. Defaults to 16G.

The labels to apply to the self-hosted runner VM. Defaults to self-hosted.

The amount of memory to allocate to the self-hosted runner VM in megabytes. Optionally, a suffix of “M” or “G” can be used to signify a value in megabytes or gigabytes respectively. Defaults to 16G.

The SHA256 checksum of the self-hosted runner tarball. Defaults to the SHA256 checksum for the tarball version specified in gha-runner-version.

The timezone to configure in the self-hosted runner VM. Defaults to UTC.

The version of self-hosted runner to install. Defaults to 2.321.0.

The timeout value for ssh-keyscan in seconds. Defaults to 60.

Required The Tailscale hostname or Tailscale IP address of your QEMU host.

Required The SSH username to use when logging into your QEMU host.

Required Your Tailscale OAuth Client ID.

Required Your Tailscale OAuth Client Secret.

A unique tag to apply to ephemeral Tailscale nodes. Defaults to github-actions.

The Tailscale client version to use. Defaults to latest.