Documentation menu
Dashboard & analytics
Managed runners
Team & notifications
Billing & plans
Workflow files
Run your first job on a Latchkey runner
Switch a GitHub Actions job to a managed runner by changing one line of YAML, watch it get picked up, and verify it in the dashboard.
In short
- Change one line:
runs-on: latchkey-small(the[self-hosted, latchkey-small]array form works identically). - Verify via the runner name on the GitHub run and the fleet activity on the Runners page.
- A job that stays queued means a routing or billing issue, not an error; see Troubleshooting.
The one-line change#
jobs: test: runs-on: ubuntu-latest runs-on: latchkey-small
You never have to type a label from memory: every row of the Your runners table on the Runners page has a Copy CI snippet action, and each runner's detail drawer includes a Use in CI card with the label and a copyable snippet.
Both label forms route identically; use whichever your conventions prefer:
name: CI on: [push] jobs: test: runs-on: latchkey-small steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '22' - run: npm ci - run: npm test
name: CI on: [push] jobs: test: runs-on: [self-hosted, latchkey-small] steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '22' - run: npm ci - run: npm test
Sizes are chosen per job, not per workflow: give the heavy job more machine and keep everything else on latchkey-small. Moving up a size doubles the per-minute rate, so it pays for itself when it at least halves the job's duration; see the sizing guidance.
jobs: heavy-build: runs-on: latchkey-large # 8 vCPU / 32 GB for the heavy job quick-lint: runs-on: latchkey-small # keep cheap jobs on small
runs-on accepts expressions, so a matrix can route each leg to the size it needs: light legs stay on the small rate while only the heavy leg pays for the bigger machine.
jobs: test: strategy: matrix: include: - suite: unit runner: latchkey-small - suite: integration runner: latchkey-large runs-on: ${{ matrix.runner }} steps: - uses: actions/checkout@v4 - run: npm run test:${{ matrix.suite }}
Or generate it#
jobs: build: runs-on: latchkey-small
Ship it and verify#
Push the change or trigger the workflow manually. On GitHub, the job shows as queued until a runner picks it up: about two seconds if a warm runner is already online, longer if a fresh runner has to cold-start.
In the GitHub run view, the job's runner name confirms a Latchkey machine took it rather than a GitHub-hosted one. Because every runner is destroyed after one job, do not expect a familiar name from run to run: a fresh machine takes each job, which is the ephemeral design working as intended.
In the Latchkey dashboard, the Runners page counts the job in Fleet now while it runs. Its minutes count against your free minutes and show in two places: the Billing page (free-tier progress, billable minutes, estimated cost so far) and the Cost page, which tracks Latchkey runner spend. Details in Runner usage and free minutes.
If the job just sits in "queued"#
A job that never gets picked up is the standard symptom for every routing problem: the repository is not monitored, managed runners are not enabled, the label has a typo, a custom runner's image is still building, or runner launches are blocked by billing. There is no explicit error in the GitHub UI in these cases. Walk through Troubleshooting: job stays queued to pin down which one it is.
Common questions#
Q.01Do my GitHub-hosted labels keep working?
Yes. ubuntu-latest and friends keep working side by side; installing Latchkey changes nothing about them. You can migrate one job at a time and leave the rest untouched for as long as you like.
Q.02Can I mix Latchkey and GitHub-hosted runners in one workflow?
Yes, freely. runs-on is decided per job, so a workflow can run its Linux jobs on latchkey-* labels while jobs that need GPU, Windows, macOS, or arm64 hosts stay on GitHub-hosted or other runners.
Q.03Do I need to change anything besides runs-on?
For most workflows, no. The runner image is designed to match or exceed GitHub-hosted runners, and actions/setup-* steps resolve from the same toolcache layout, so the rest of the job stays as it is.
Q.04What does this first run cost me?
Minutes are billed per minute, rounded up per job, at the size's rate, and every plan includes free minutes each month. Unless you have already used up your free tier, a short test run costs nothing. See Runner usage and free minutes.