Skip to content
Latchkey home
Documentation menu

The Runners page: fleet management

Manage your runner fleet from the dashboard: what your runners are doing now, the self-heal settings, runner types and configurations, and the bulk migration tool.

In short

  1. The Runners page holds Fleet now (what your runners are doing right now), the workspace's self-heal settings, Sizes, and Latchkey on GH: runner types, your runner configurations and AI scan runners.
  2. Per-configuration enable/disable, max concurrency, and image build status for custom runners; self-healing is one workspace-wide switch, on this page and in Settings.
  3. Migrate runners (Runner types panel or Settings, Code hosts; owners/admins) opens one PR per repository, up to 20 monitored repos per pass; only runs-on lines change, plus Latchkey cache steps when added.
app.latchkey.dev / acme / runners

The Runners page, Fleet now. Runners at once reads 2 of 40 in use, with Warm 1, noted as counting every warm runner including one still running a job, Parked 1, Starting 0 and Held 0. Under it, Last hour, by minute draws a lane for each runner size from 13:55 to 14:54, your time, each minute a column of running, starting and held jobs, with the size's warm and parked runners beside it: small reads warm 1 · parked 1, and large and xlarge read No jobs in the last hour. A job finishes, and 1 of 40 is in use. Two test shards wait together: the warm runner takes the first, and the parked runner resumes for the second, so Parked drops to 0 and small reads warm 1 · parked 0. Then one more job waits with no warm or parked runner free, and a fresh machine cold-starts for it. At the end, 4 of 40 are in use, with Warm 1, Parked 0, Starting 1 and Held 0, and small's newest minute shows three jobs running and one starting.

FIG. 3.6-AFleet now counts the runners in use against your limit and splits the rest into warm, parked, starting and held; Last hour, by minute draws each size's jobs minute by minute, running, starting and held, beside its warm and parked runners.

Everything about your managed runner fleet lives on the Runners page ("What your runners are doing now, how self-heal behaves on them, what each size costs, and the runners Latchkey on GH starts for your repositories.") in the dashboard sidebar. It is the operational home for the features described in the rest of this section.

What is on the page#

Fleet now
How many runners are busy against your limit, the warm and parked runners standing by, the jobs starting and held, and the last hour by minute. It refreshes every 15 seconds.
Self-heal
The workspace's self-heal switch and the most times self-heal may run a failed step again, both also on the Self-healing tab in Settings, with links to Declined fixes and Knowledge base documents.
Sizes
This calendar month's free minutes and runner cost so far, then every size a workflow file can name, small to xlarge, with its vCPU, RAM, disk and rate a minute and a button that copies its runs-on line.
Runner types
Under Latchkey on GH, a collapsible card covering Preset runners (the four sizes with specs and per-minute pricing) and AI scan runners, with a Migrate runners shortcut in its foot.
Your runners
Every configuration in your workspace: name, image, size, max at once and on or off, plus a per-row Copy CI snippet action.

A five-minute weekly review#

The page rewards a short weekly habit. A suggested pass:

Weekly fleet review

The Your runners table#

The Your runners table ("Set up runners for your repositories: size, concurrency and on or off. AI scan runners are built from what a repository's workflows actually use.") lists every configuration in your workspace: your preset configurations plus any custom runners. Columns cover name, image, size, max at once and active, and the table header carries the AI scan runners action for owners and admins; before your first runner it shows a Set up your first runner empty state, and pending scan banners ("Ready for review") appear below it. Each row gives you:

  • Enable/disable. A disabled configuration stops accepting new jobs (jobs targeting its label will queue).
  • Copy CI snippet, so nobody types a label from memory.
  • Max at once, how many of its runners may run at once (∞ when unlimited).
  • Image build status for custom runners: you can see when a custom image is still building versus ready.
  • Delete for any configuration you no longer need, preset or custom, after a confirmation (owners and admins).

Disable and delete do different jobs. Disable is the pause button: the label keeps existing, and jobs that target it queue until you re-enable it, which makes it the right move while you investigate a configuration. Delete is for configurations you are permanently done with: once one is deleted, jobs that name its label no longer match it.

The detail drawer#

Clicking a row opens the detail drawer with the configuration: label, vCPUs, RAM, and per-minute price, with the OS and, for a custom runner, disk and base image in Pro, plus a Use in CI card with the label and a copyable GitHub Actions snippet. Owners and admins can edit the runner name, custom labels, and Max at once (0 means unlimited); members see the same details read-only, so the whole team can see what each runner provides.

Self-heal#

The Self-heal section ("Workspace-wide. The same switch as the Self-healing tab in Settings: a change on either shows on the other.") holds two of the workspace's self-heal settings: the Self-heal for this workspace switch and Max retries per step, from 1 to 6. Flake Shield is only on the Self-healing tab in Settings. Self-heal does not run on a pull request from a fork. On Latchkey CI it also does not run on a step that a trial run would leave out: a step written advisory: skip, a step that can publish and writes no advisory:, and every step of a job that writes advisory: hold or names an environment and writes no advisory:. Nor, on Latchkey CI, does it run on a step that starts once its job holds more than 64 values to hide (its secrets, its service settings of 28 bytes or more and the credentials Latchkey hands its steps). Its links open Declined fixes in Settings and Knowledge base documents, and only owners and admins can change the settings. What self-heal did is shown where it happened rather than in a feed on this page: the Runs page marks a healed run on Latchkey CI, or a healed job on Latchkey on GH, Healed beside its result; on a Latchkey CI job, the healed step's record says what Latchkey did, and Open the heal opens the Heal Details drawer with the full report (what was wrong, the outcome, what Latchkey did, and for AI-diagnosed failures the agent's iterations); and the Self-heal outcome report on AI Insight counts the failures healed on the runner, the re-runs avoided and the failures left for you.

Read the healed runs as a signal, not just a rescue log. Scattered one-off network heals across many workflows are the normal background noise of registries and external services having bad moments. Patterns are more interesting: the same workflow healed repeatedly in the same category points at something durable. Recurring memory heals suggest a job that wants a bigger runner size; recurring disk heals, a job that fills its disk every run; recurring tool heals, a step that assumes a tool the workflow never installs. Those are exactly the cases where a permanent fix beats being rescued every night; see heal pull requests for how self-healing proposes those fixes itself.

Migrate Runners#

app.latchkey.dev / acme / runners

The Runners page shows the Runner types panel, whose foot reads Already have workflows on GitHub-hosted runners? Migrate them to Latchkey runners in a few clicks., beside a Migrate runners button. The Migrate runners dialog opens over the dimmed page: Pick the monitored repos you want to migrate. We'll open one PR per repo that swaps every supported runs-on: label to a Latchkey runner. Anything we can't map (Windows, exotic self-hosted) is left untouched. It lists three monitored repositories, acme/api, acme/web and acme/worker, with 0/20 selected. acme/api is picked (1/20, Open migration PR), then acme/web (2/20, Open migration PRs). The button is pressed and reads Opening PRs… while the dialog's close button waits. The dialog ends on Opened 2 pull requests. Merge each on your schedule., listing acme/api #431 and acme/web #92, each with View PR.

FIG. 3.6-BMigrate runners opens from the foot of the Runner types panel, and from Settings, Code hosts, for owners and admins. The count stops at 20 repositories a pass, and when it finishes the dialog links each pull request it opened.

The tool has two entry points, and both open the same Migrate runners dialog: the CTA in the Runner types panel footer ("Already have workflows on GitHub-hosted runners? Migrate them to Latchkey runners in a few clicks."), and Migrate runners in the Repositories panel of the Code hosts tab in Settings. This section covers the dialog itself; the full guide, including the exact label mapping, PR contents, verification, and rollback, is Migrate from GitHub-hosted runners.

01
Open the tool
From the Runner types panel footer or Settings, Code hosts (owners and admins)
02
Pick repositories
Up to 20 monitored repos, with an N/20 selected counter
03
Open migration PRs
Latchkey opens one pull request per repository
04
Review and merge
Nothing changes until your team merges each PR

Each pull request rewrites every supported runs-on label to the right Latchkey size (standard Ubuntu labels become latchkey-small) and touches nothing else; Windows and macOS jobs, unrecognized labels, and lines with ${{ }} expressions are left alone. A before and after mapping table for each file shows exactly what changed, so review takes minutes, not days.

  • Once the PRs are open, the modal lists each one with its PR number and a View PR link: "Opened N pull requests. Merge each on your schedule."
  • If a repository already has an open migration pull request, Latchkey links to it instead of opening a duplicate.
  • If there is nothing left to switch, the modal shows a Nothing to migrate state.
  • Opening migration PRs requires an admin or owner role; nothing in your repositories changes until your team merges.
Q.01What is on the Runners page?

Fleet now (what your runners are doing right now), the workspace's self-heal settings, Sizes (each size's rate a minute, with this calendar month's free minutes and runner cost), and under Latchkey on GH the runner types and your runner configurations, in one place. Each configuration can be enabled or disabled, given a maximum concurrency, and shows image build status for custom runners.

Q.02How do I migrate repositories to Latchkey runners in bulk?

Use Migrate runners, on the Runner types panel or in Settings on the Code hosts tab, available to owners and admins. It opens one pull request per repository across up to 20 monitored repositories per pass, changing only runs-on lines plus Latchkey cache steps where those are added.

Q.03Where do I turn self-healing on or off?

Workspace-wide, not per configuration: from the Self-heal section of the Runners page or the Self-healing tab in Settings, which share one switch. The Runners page also controls per-configuration enablement and concurrency; self-healing is a single workspace switch so its behaviour cannot drift between runner types.