GitHub Actions runners
A runner is a GitHub Actions runner the host keeps registered for one repository. MIOSA installs and supervises the runner process on your machine, so a workflow job runs on hardware you control.
Use this when a build needs a GPU, a large local cache, software that only exists on your machine, or a network path that GitHub-hosted runners cannot reach.
Register a runner
| Field | Type | Required | Description |
|---|---|---|---|
repo_url | string | Yes | Repository URL; must be on github.com or a *.github.com host |
name | string | Yes | Runner name, 1 to 128 characters; unique per host |
labels | string[] | No | Runner labels; default [] |
ephemeral | boolean | No | Deregister the runner after one job; default false |
pat_secret_id | string | One of | ID of an existing host secret holding a GitHub token |
pat_value | string | One of | Inline token; MIOSA stores it as a host secret for you |
The CLI flag names differ from the API field names: --repo maps to repo_url, --token to pat_value (sent to the host and not stored), and --token-secret to pat_secret_id. --label is repeatable, and --name defaults to a generated name.
Runner states
| State | Meaning |
|---|---|
provisioning | MIOSA is installing and starting the runner |
idle | Registered and waiting for a job |
running_job | Executing a workflow job |
offline | Registered but not reachable |
failed | Installation or registration failed |
removed | Deregistered |
current_job is set while the runner is executing, and last_activity_at tells you when it last did anything.
Watch a runner
Repair and remove
miosa host gha-runner refresh <host> <runner>
miosa host gha-runner rm <host> <runner> --yes| Action | REST | Notes |
|---|---|---|
| Refresh | POST .../gha-runners/{runner_id}/refresh | Reinstalls and restarts the runner; returns {"ok": true} |
| Remove | DELETE .../gha-runners/{runner_id} | Stops the runner and deregisters it from GitHub; returns 204 |
refresh is the fix for a runner stuck in failed or offline after an upgrade, rather than deleting and re-registering.
Both actions can return 429 if the GitHub API rate-limits the registration calls.
Reference it in a workflow
Point a workflow job at the runner’s labels:
jobs:
build:
runs-on: [self-hosted, gpu, linux]A job runs on your machine only while the host agent is connected and the runner is idle.
If the host goes offline mid-job, the workflow fails on GitHub’s side; check miosa host gha-runner get and the runner events before retrying.