CI on managed runners
Move CI off a developer machine (or off blocked GitHub-hosted minutes) with one repository variable,
one workflow, and one commit status that both people and agents read.
1. Pick the vendor by what blocks you
| Situation |
Choice |
| Need it today, small volume |
A managed runner vendor (for example Ubicloud): install its GitHub App, use its labels, pay per minute. About 0.0025 USD a minute for 4 vCPU. |
| Cloud account with spot quota and Terraform skills |
Ephemeral spot runners from the open-source github-aws-runners/github-runner/aws module. Check the account's spot vCPU quota first: a quota below the instance size (a new or small account can read 1) starts nothing, and a quota request can be denied. |
| Public repository |
Stay on GitHub-hosted runners. A fork's pull request would otherwise run its code on your machines. |
Ask the owner before anything that costs money. Store vendor tokens in the secret manager, never in a
GitHub secret (a pull request workflow could read it).
2. Swap runners with one variable
Every runs-on in a CI workflow reads a repository variable:
runs-on: ${{ fromJSON(vars.CI_RUNNER || '["ubuntu-latest"]') }}
Set it with gh variable set CI_RUNNER --body '["<vendor-label>"]' -R <owner>/<repo>. Delete it to fall back
to GitHub-hosted runners; change it to move vendors. No workflow edit, no PR.
3. One workflow, three jobs
plan: decides the tier and the matrix, marks the commit pending through the commit status API.
run: a matrix, one runner per entry, each running the same script a developer runs locally
(scripts/ci.sh <job>), so the Mac, a cloud session and Actions cannot drift apart. fail-fast: false.
ci-result: if: ${{ !cancelled() }}, posts the final status (context local-ci) on the tested commit. For a
pull request that is the head commit, not the merge commit: github.event.pull_request.head.sha.
Tiers keep it cheap: a draft PR runs only the quick jobs and leaves the status pending; marking it ready runs
everything; a docs-only change runs the quick jobs and succeeds. Shard slow suites across runners with a
variable the script reads (for example a list of Go modules per matrix entry).
4. Gate the deploy on the status
Make the deploy workflow workflow_dispatch only (a merge deploys nothing) and have its first step fail unless
the commit has a passing local-ci status:
gh api repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/status \
--jq '.statuses[]|select(.context=="local-ci")|.state' | grep -qx success
An agent then deploys with gh workflow run deploy.yml --ref main, with no cloud key on its side: cloud
credentials stay in the workflow (OIDC role trusted for refs/heads/main only).
5. Traps
- A job-level
env: cannot read the runner context (runner.temp). The whole run fails with "workflow file
issue" and zero jobs. Set such values in a first step with echo "X=$RUNNER_TEMP/..." >> "$GITHUB_ENV".
- A workflow disabled by hand (
disabled_manually) ignores pushes. gh workflow enable <name> first.
- Lint workflows before pushing:
actionlint catches context errors locally.
- Stock images lack some tools (a browser, a database client). Install them in a setup script keyed by job, and
confirm on the first real run rather than assuming.
- Never poll CI. Read the checks once when a run should be done, or let the pull request hook wake the agent.
- Do not widen the cloud deploy role's trust to make a tag or branch trigger work; keep it on
main.
1---2name: ci-on-managed-runners3description: "Use when CI is slow, runs on a laptop, or GitHub-hosted Actions minutes are blocked or too expensive, and the job is to move CI and deploys onto cheap managed or self-hosted runners that Claude sessions can use without any cloud key. Covers choosing a vendor, the CI_RUNNER repo variable that swaps runners without a workflow edit, a plan/matrix/result workflow that posts one commit status, gating a hand-started deploy on that status, and the traps (runner context in job env, public repos, spot quotas, unpolled CI). Trigger words: self-hosted runners, Ubicloud, spot runners, CI too slow, Actions billing blocked, local-ci status, deploy gate."4metadata:5 source: https://skillmd.com/skills/ever-just/ci-on-managed-runners6---78# CI on managed runners910Move CI off a developer machine (or off blocked GitHub-hosted minutes) with one repository variable,11one workflow, and one commit status that both people and agents read.1213## 1. Pick the vendor by what blocks you1415| Situation | Choice |16|---|---|17| Need it today, small volume | A managed runner vendor (for example Ubicloud): install its GitHub App, use its labels, pay per minute. About 0.0025 USD a minute for 4 vCPU. |18| Cloud account with spot quota and Terraform skills | Ephemeral spot runners from the open-source `github-aws-runners/github-runner/aws` module. Check the account's **spot vCPU quota first**: a quota below the instance size (a new or small account can read 1) starts nothing, and a quota request can be denied. |19| Public repository | Stay on GitHub-hosted runners. A fork's pull request would otherwise run its code on your machines. |2021Ask the owner before anything that costs money. Store vendor tokens in the secret manager, never in a22GitHub secret (a pull request workflow could read it).2324## 2. Swap runners with one variable2526Every `runs-on` in a CI workflow reads a repository variable:2728```yaml29runs-on: ${{ fromJSON(vars.CI_RUNNER || '["ubuntu-latest"]') }}30```3132Set it with `gh variable set CI_RUNNER --body '["<vendor-label>"]' -R <owner>/<repo>`. Delete it to fall back33to GitHub-hosted runners; change it to move vendors. No workflow edit, no PR.3435## 3. One workflow, three jobs3637- `plan`: decides the tier and the matrix, marks the commit `pending` through the commit status API.38- `run`: a matrix, one runner per entry, each running the same script a developer runs locally39 (`scripts/ci.sh <job>`), so the Mac, a cloud session and Actions cannot drift apart. `fail-fast: false`.40- `ci-result`: `if: ${{ !cancelled() }}`, posts the final status (context `local-ci`) on the tested commit. For a41 pull request that is the **head commit, not the merge commit**: `github.event.pull_request.head.sha`.4243Tiers keep it cheap: a draft PR runs only the quick jobs and leaves the status `pending`; marking it ready runs44everything; a docs-only change runs the quick jobs and succeeds. Shard slow suites across runners with a45variable the script reads (for example a list of Go modules per matrix entry).4647## 4. Gate the deploy on the status4849Make the deploy workflow `workflow_dispatch` only (a merge deploys nothing) and have its first step fail unless50the commit has a passing `local-ci` status:5152```bash53gh api repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/status \54 --jq '.statuses[]|select(.context=="local-ci")|.state' | grep -qx success55```5657An agent then deploys with `gh workflow run deploy.yml --ref main`, with no cloud key on its side: cloud58credentials stay in the workflow (OIDC role trusted for `refs/heads/main` only).5960## 5. Traps6162- A job-level `env:` cannot read the `runner` context (`runner.temp`). The whole run fails with "workflow file63 issue" and zero jobs. Set such values in a first step with `echo "X=$RUNNER_TEMP/..." >> "$GITHUB_ENV"`.64- A workflow disabled by hand (`disabled_manually`) ignores pushes. `gh workflow enable <name>` first.65- Lint workflows before pushing: `actionlint` catches context errors locally.66- Stock images lack some tools (a browser, a database client). Install them in a setup script keyed by job, and67 confirm on the first real run rather than assuming.68- Never poll CI. Read the checks once when a run should be done, or let the pull request hook wake the agent.69- Do not widen the cloud deploy role's trust to make a tag or branch trigger work; keep it on `main`.