github-runner

Registers an ephemeral self-hosted GitHub Actions runner.

Use it on boxctl

1. On the dashboard, pick github-runner in the Template picker and click Boot box.
2. The box boots, then runs github-runner/github-runner.sh on itself. The button reads Booting… until the script has finished.
3. Open the box's Terminal and follow the guide below. The box's row keeps a link back to this page under the template's name.

The guide is shared with the onctl CLI, so it starts from an onctl up -a github-runner/github-runner.sh command. Booting a box with this template replaces that command; everything the guide runs on the VM itself applies as written.

Options

This template needs GH_REPO and RUNNER_TOKEN, and boxctl cannot pass options to a template yet. Booted from the dashboard, its script runs without them.

GitHub Actions self-hosted runner

Registers an ephemeral self-hosted GitHub Actions runner on the VM. The runner picks up exactly one job, then deregisters itself.

run vm + install docker + register runner

TOKEN=$(gh api -X POST repos/<owner>/<repo>/actions/runners/registration-token -q .token)
onctl up -n runner -a docker/docker.sh -a github-runner/github-runner.sh \
  -e GH_REPO=<owner>/<repo> -e RUNNER_TOKEN=$TOKEN

Registration tokens expire after 1 hour — generate one right before onctl up.

use it in a workflow

jobs:
  build:
    runs-on: [self-hosted, onctl]

Set RUNNER_LABELS (default onctl) to add custom comma-separated labels.

cleanup

The runner deregisters itself after one job. Destroy the VM once it's done:

onctl destroy runner

See the template's source for exactly what it runs.