# 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.

Source: https://latchkey.dev/documentation/run-your-first-job

## Summary

- 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.

**Before you start**
- [ ] The Latchkey GitHub App is installed on my organization
- [ ] The repository is monitored in Latchkey
- [ ] My trial or subscription is active

## The one-line change

You never have to type a label from memory: every row of the **Your runners** table on the [Runners page](/documentation/runners-dashboard) 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:

## Or generate it

## Ship it and verify

1. **Commit and trigger the workflow** Push the change or trigger the workflow manually. On GitHub, the job shows as queued until a runner picks it up: seconds if a warm runner is available, about 10 seconds for a fresh runner (GitHub-hosted typically takes 30-60 seconds), with zero queue time either way.
2. **Verify where it ran** 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](/documentation/runners-overview) working as intended.
3. **Find the minutes** In the Latchkey dashboard, the [Runners page](/documentation/runners-dashboard) shows the run in your fleet activity, and its minutes appear against your free tier. Over time the same numbers surface in two more places: the billing modal (free-tier progress, billable minutes, estimated cost so far) and the [Cost Analysis](/documentation/cost-analysis) page, which tracks Latchkey runner spend alongside your GitHub spend. Details in [Runner usage and free minutes](/documentation/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](/documentation/troubleshooting) to pin down which one it is.

## Common questions

### Do 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.

### Can 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.

### Do I need to change anything besides runs-on?

For most workflows, no. The [runner image](/documentation/runner-image-software) 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.

### What 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](/documentation/runner-usage-and-free-minutes).

> **Migrating many workflows**
> The **Migrate Runners** tool (owners/admins, in the dashboard sidebar and on the [Runners page](/documentation/runners-dashboard)) opens one ready-to-review pull request per repository, up to 20 monitored repositories per pass, instead of you editing files one by one. The full guide is [Migrate from GitHub-hosted runners](/documentation/migrate-from-github-hosted).

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt