# CI On Managed Runners

> CI on managed runners

- Skill: `ever-just/ci-on-managed-runners` (Agent Skill)
- Install (CLI): `npx get-skill add ever-just/ci-on-managed-runners`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ever-just/ci-on-managed-runners/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ever-just (https://skillmd.com/u/ever-just)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/ever-just/ci-on-managed-runners

---


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

```yaml
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:

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

