How-to: run your GitHub Actions workflows on your own box
runner.kind = "gha" executes the repo's own .github/workflows/*.yml — GitHub Actions as a bupha dialect. Push lands on bupha's queue as usual; instead of ci.sh or a dagger call, the runner parses the workflows at the pushed sha and runs every on.push-matching one in one local bash process — jobs scheduled by needs depth (independent jobs run concurrently, each in its own git worktree checkout; needs chains stay sequential), matrix legs in parallel (each in its own git worktree checkout, capped by strategy.max-parallel). The aggregate exit status drives the commit status.
Naming (T-054).
runner.kind = "gha"is the workflow dialect — bupha reads.github/workflowsYAML and executes it. The reverse direction (bupha as a GitHub self-hosted runner that repos target withruns-on: [self-hosted, bupha]) is the separategha-runnersurface — see self-hosted runner. Don't confuse the two.
[[repo]]
name = "org/app"
dir = "/srv/checkouts/app"
branch = "refs/heads/main"
[repo.runner]
kind = "gha"
# workflow = "ci.yml" # optional: pin file(s) under
# .github/workflows/ instead of
# discovering all on.push matchesThe worktree is already a checkout of the pushed sha, so actions/checkout is accepted as a verification no-op (any ref — it does not re-checkout). runs-on labels are recorded for logs; execution is always local — there is no runner fleet inside a workflow.
The supported subset — read before migrating
v1 covers the common CI shape: on.push (branches/paths filters), jobs with needs (fail-fast DAG), env, defaults.run, steps (run + uses: — actions/checkout, dtolnay/rust-toolchain, actions/setup-{node,python,go,java, dotnet}, actions/upload-artifact/download-artifact, actions/cache{,/save,/restore}, docker://<image> container steps, and composite actions via ./local/path or owner/repo[/path]@ref, with id:), job outputs: maps, job/step if: (a real expression subset — literals, ==/!=/&&/||/!, contains/startsWith/endsWith, success()/failure()/cancelled()/always(), plus needs.*.result/steps.*.conclusion/steps.*.outputs.*/ needs.*.outputs.*/inputs.*-in-composites refs), timeout-minutes (GNU timeout per step, process-group watchdog per job), the $GITHUB_ENV/ $GITHUB_OUTPUT/$GITHUB_PATH/$GITHUB_WORKSPACE/ $GITHUB_STEP_SUMMARY/RUNNER_TEMP file commands, and strategy.matrix fan-out — legs run in parallel by default (each in a private git worktree under the run's tmp dir, so workspace writes stay per-leg; max-parallel caps concurrency, 1 pins the sequential shared-worktree path).
Everything else is a hard error at spawn, naming the unsupported key — services:, container:, environment:, concurrency:, continue-on-error:, matrix.include/exclude, uses: outside the list above (JS/docker action.yml definitions, other actions/setup-* families and reusable-workflow jobs.<id>.uses: included), with: keys outside each action's declared inputs, artifact cross-run download inputs (run-id, github-token, repository, run-attempt), on.push.{tags,types,workflows}, secrets:, if: functions beyond the subset (hashFiles, fromJSON, format, …), and unknown keys at any level (including in action.yml). The full list and honest boundaries live in crates/bupha-gha/README.md — treat it as the contract.
Migrating off GHA
What you keep: the workflow files themselves, the on.push/branches/paths triggers, job needs ordering and if:/timeout-minutes, matrix dimensions, step env/working-directory/shell, $GITHUB_* file commands.
What changes:
- No marketplace — but local + composite actions work.
uses:coversactions/checkout(a verification no-op — the worktree is already at the pushed sha),dtolnay/rust-toolchain(lowers to rustup calls), theactions/setup-*toolchain family (official tarballs into a per-run toolcache), the artifact actions (per-run tar store, same-run only) andactions/cache*(persistent keyed store). Composite actions run too:uses: ./pathreads your repo'saction.yml, anduses: owner/repo[/path]@reffetches the action repo over git (GITHUB_TOKENin the runner env authenticates private repos). JS (node*) anddockeraction definitions, other setup families and reusable-workflow calls all hard-error — butuses: docker://<image>steps run: they lower todocker runon the host (workspace + run tmp bind-mounted at their paths, step/job env via--env-file,with.entrypoint/with.argssupported; needs the docker CLI on PATH, no registry credentials or port mappings).timeout-minuteson a compositeuses:step is a deadline spanning the inlined steps. Everything else installs viarun:steps (curl,cargo install, your own scripts) or is already on the box. - Parallel across independent jobs, sequential across
needs. Jobs with no mutualneedsedges share a scheduling level and run concurrently — each group in a privategit worktree, like matrix legs (files written to the workspace stay in that worktree;$BUPHA_WORKDIR/$BUPHA_GHA_TMPare the shared channels). Levels are barriers, so a job waits for its whole level rather than just its needs, and there is no cross-job fail-fast (strategy.fail-faststays per job id) — coarser than GHA's per-job scheduler but the sameneedscontract. To isolate workloads entirely, split workflows across[[repo.jobs]]entries (each gets its ownrunner.workflowpin and its ownci/bupha/<job>status context). - Statuses are bupha's — plus per-job detail. The aggregate commit status still lands once per repo/job under
ci/bupha(or your[status].context); on top of that, each expanded workflow job that reaches a verdict posts its own status under<context>/<workflow>/<job id>[/<matrix bindings>](e.g.ci/bupha/ci/build/os=ubuntu,node=18). Skipped and fail-fast-cancelled legs post nothing — commit statuses have no neutral state. - Secrets resolve the bupha way — env-var names → cuora (
cuora://bupha/<NAME>, canonical; fleet secrets migrated, T-059) →~/.config/bupha/env(dev-mode / no-cuora fallback; keyring leg dropped post-T-077);secrets:context is unsupported, so reference${{ env.NAME }}or plain$NAMEinrun:steps. - PRs are opt-in, and reuse
on.pushshapes. The dialect only selectson.pushworkflows and reportsgithub.event_name = "push"—pull_request-triggered workflows are ignored. To gate PRs, addevents = ["push", "pull_request"]to the[[repo]]: the PR head sha runs in a worktree against the base ref's filters, so your existing push workflows are the PR gate too.
If a workflow hits a hard error, the run fails loudly at spawn — the error names the key to remove or the subset to rewrite against. For pipelines outside the subset, runner.kind = "shell" + cmd remains the escape hatch.
Smoke-verified subset (PL-013 D5)
Exercised end-to-end with bupha run (runner.kind = "gha") against a scratch repo — confirms the spawn path, not GHA/act parity on a production workflow:
on.pushdiscovery +steps[].runin bash — passed.uses: actions/checkout@v4— accepted as the pushed-sha no-op.strategy.matrix2×2 fan-out — 4 legs in parallel, each in its own worktree;${{ matrix.node }}interpolation intoenv:worked.- Unsupported key —
services:under a job fails at spawn withgha: ci.yml.jobs.<id>: unsupported key 'services' (outside the gha v1 subset)— loud, names file/job/key.
Real-repo dogfood (PL-013 D5)
handl-lang/extension-vscode's .github/workflows/ci.yml — a production workflow already mirrored by that repo's ci.sh shell-runner gate — ran green end-to-end via bupha run with runner.kind = "gha" (2026-11-13, scratch clone):
on.push.branches: [main]discovery;pull_request/workflow_dispatchtriggers present but not exercised by a local push run.uses: actions/checkout@v4no-op;actions/setup-node@v4withnode-version: "20"resolved andcache: npmaccepted as a documented no-op (no cross-run npm cache).run:steps (npm ci,npm run typecheck,npm test) executed in order; vitest 32/32 passed; job reportedgha: all jobs passed.
Parity notes vs. GHA/act: single-job workflows in the supported subset are drop-in. Org repos on oven-sh/setup-bun or Swatinem/rust-cache/astral-sh/setup-uv are not yet — those uses: hard-error at spawn today (the honest-failure contract; add the action to the subset or keep kind = "shell").
A full parity pass against GHA/act output is still open — the dialect's hard-error contract means a migration is incremental: unsupported keys surface one at a time.