boxctl
DocsSign in

github-runner-jit

Registers an ephemeral self-hosted GitHub Actions runner using a just-in-time (JIT) config.

Use it on boxctl

  1. On the dashboard, pick github-runner-jit in the Template picker and click Boot box.
  2. The box boots, then runs github-runner-jit/github-runner-jit.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-jit/github-runner-jit.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 JIT_CONFIG, and boxctl cannot pass options to a template yet. Booted from the dashboard, its script runs without it.

OptionRequiredWhat it sets
JIT_CONFIGYesBase64 JIT config from the generate-jitconfig API.
SKIP_DOCKERNoSet to 1 to skip installing Docker.

GitHub Actions self-hosted runner (JIT config)

Registers an ephemeral self-hosted GitHub Actions runner on the VM using a just-in-time (JIT) runner config — a single-use, pre-scoped credential generated before the VM exists, so no registration token or other reusable credential ever touches the VM. The runner picks up exactly one job, then exits.

generate JIT config + run vm

JIT_CONFIG=$(gh api -X POST repos/<owner>/<repo>/actions/runners/generate-jitconfig \
  -f name=runner-jit -F runner_group_id=1 \
  -f 'labels[]=self-hosted' -f 'labels[]=onctl' \
  -q .encoded_jit_config)
onctl up -n runner-jit -a github-runner-jit/github-runner-jit.sh -e JIT_CONFIG=$JIT_CONFIG

Generating the JIT config requires a token with administration:write on the repo (classic PAT with repo scope, or fine-grained PAT with Administration: Read & write).

SKIP_DOCKER=1 (via -e) skips the docker install step.

use it in a workflow

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

cleanup

The runner process exits after one job — no config.sh, no systemd service, no reusable credential left on the VM. Destroy the VM once it's done:

onctl destroy runner-jit

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