Run workflows on a local machine worker

[gingur]

I want to add a "worker" on my local machine that all future agent/deploy workflow runs leverage instead of (or alongside) GitHub-hosted runners. Unsure what devkit features would be needed to expose this — research what this would take and propose what the plan would look like.

[gingur-bot]

Plan

Ask (restated): Run agent (claude.plan) and deploy workflow jobs on a local self-hosted machine instead of — or switchable alongside — GitHub-hosted runners, and determine what devkit needs to expose to make that possible. The deliverable of this turn is a researched plan.

Current state:

• Three reusable workflows already take a runner input: node.verify.yml and infisical.secrets.scan.yml (runs-on: ${{ inputs.runner }}, default ubuntu-latest) and claude.plan.yml (runs-on: ${{ inputs.runner || 'ubuntu-latest' }}).
• Four hardcode runs-on: ubuntu-latest: cf.worker.deploy.yml, cf.worker.preview.yml (its domain job; its deploy job nests cf.worker.deploy.yml), cf.worker.preview.cleanup.yml, cf.worker.rollback.yml — plus devkit's own scan.yml.
• Issue POC: self-hosted GitHub Actions runner via Cloudflare Tunnel #3 (open, May 2026) proposed a self-hosted runner POC via Cloudflare Tunnel and left open questions (where the box lives, sharing across repos, trust boundary). This plan resolves those; POC: self-hosted GitHub Actions runner via Cloudflare Tunnel #3 can be closed as superseded once this lands.

Research findings:

1. No tunnel needed. The runner long-polls GitHub over outbound HTTPS; zero inbound ports. The cloudflared premise in POC: self-hosted GitHub Actions runner via Cloudflare Tunnel #3 was unnecessary (GitHub docs — about self-hosted runners).
2. Personal accounts can't share runners across repos. Runners register at repository, organization, or enterprise level only — gingur is a user, so no runner groups. One machine serves N repos by running N runner instances, each configured in its own directory against one repo (community discussion, adding runners).
3. Public repos + self-hosted runners = fork-PR code execution risk. GitHub's guidance is to avoid them for public repos unless job routing is restricted to trusted triggers (secure use reference, community discussion). Our safe subset: issues: assigned (agent turns — gated on who can assign the bot), push to main (deploy), workflow_dispatch (rollback). PR-triggered workflows (verify, preview, cleanup, scan) must always stay on GitHub-hosted.
4. OIDC → Infisical works unchanged on self-hosted runners; the id-token is issued by GitHub regardless of where the job runs. No secrets ever live on the machine.
5. Tooling gap: GitHub-hosted images preinstall gh; a local runner does not. claude.plan.yml's report-failure/return-baton steps and the planning agent itself shell out to gh — it's a machine prerequisite. Node is not (the runner bundles its JS-action runtime; actions/setup-node tool-caches per runner — warm caches are actually a perk of a persistent runner).
6. Offline machine behavior: jobs targeting the local label queue for up to 24 hours, then fail. Routing must be flippable back to hosted without a commit — a repo variable (vars.RUNNER), not a hardcoded label, is the switch.

Approach: Thread an explicit, empty-safe runner routing expression through the operator-gated workflows only, keyed off a per-repo variable so switching local ↔ hosted is a settings change. Then document provisioning + policy. Rejected alternatives:

• Cloudflare Tunnel (per POC: self-hosted GitHub Actions runner via Cloudflare Tunnel #3) — solves a problem runners don't have (finding 1).
• actions-runner-controller / ephemeral k8s fleet — requires Kubernetes; overkill for one local machine.
• vars.RUNNER fallback inside every workflow's runs-on — rejected for cf.worker.deploy.yml: it's nested by the PR-triggered preview workflow, so a repo-wide var would silently route preview builds (which execute PR code) to the local machine. Deploy/rollback take the var via explicit caller input instead; only claude.plan.yml reads vars.RUNNER directly (its issues: trigger path has no caller to pass inputs).
• Adding runner to preview/cleanup — deliberately omitted; PR-triggered on a public repo.
• Creating a GitHub org for shareable runners — out of scope; per-repo instances are fine at current repo count.

Proposed tasks

1. Thread runner routing through operator-gated reusable workflows

• Depends on: nothing

• Body:

  devkit's reusable workflows should let operator-gated jobs run on a local self-hosted runner (registered per-repo with the custom label local), while PR-triggered jobs always stay on GitHub-hosted runners because the repos are public (fork-PR code execution risk). Some workflows already take a runner input (node.verify.yml, infisical.secrets.scan.yml, claude.plan.yml); the Cloudflare ones hardcode ubuntu-latest.

  Make these exact changes in gingur/devkit:

  1. .github/workflows/cf.worker.deploy.yml — add input runner (type string, required: false, default: 'ubuntu-latest', description Runner label); change the deploy job to runs-on: ${{ inputs.runner || 'ubuntu-latest' }}. Do not read vars.RUNNER here: this workflow is nested by the PR-triggered cf.worker.preview.yml, and a repo-wide var would silently route preview builds (which execute PR branch code) to the local machine.
  2. .github/workflows/cf.worker.rollback.yml — same runner input; runs-on: ${{ inputs.runner || 'ubuntu-latest' }} on the rollback job.
  3. .github/workflows/claude.plan.yml — change the plan job to runs-on: ${{ inputs.runner || vars.RUNNER || 'ubuntu-latest' }}. The vars fallback is needed here (and only here) because the direct issues: assigned trigger has no caller to pass inputs; in workflow_call mode vars resolves against the calling repository, so consumers get the same switch. Note this in a short comment on the line.
  4. .github/workflows/node.verify.yml and .github/workflows/infisical.secrets.scan.yml — change runs-on: ${{ inputs.runner }} to runs-on: ${{ inputs.runner || 'ubuntu-latest' }} so callers may pass runner: ${{ vars.RUNNER }} without breaking when the variable is unset (empty string would otherwise be an invalid label).
  5. .github/workflows/cf.worker.preview.yml and .github/workflows/cf.worker.preview.cleanup.yml — no runner input (deliberate). Add a one-line comment above each hardcoded runs-on: ubuntu-latest stating the constraint, e.g. # PR-triggered: always GitHub-hosted; never route to a self-hosted runner (public repo). The preview workflow's nested cf.worker.deploy.yml call must NOT pass a runner value.

  Follow repo conventions (CLAUDE.md): identifier runner stays camelCase/single-word; workflows remain thin glue; no defensive validation of the label value — an unknown label fails naturally by queueing.

  Acceptance criteria:

  • The five modified files contain exactly the runs-on expressions above; cf.worker.preview.yml / cf.worker.preview.cleanup.yml have no runner input and their nested/own jobs still resolve to ubuntu-latest.
  • claude.plan.yml is the only workflow referencing vars.RUNNER.
  • All workflow YAML parses (actionlint clean if available, otherwise a YAML parse check).
  • README's reusable-workflows reference table gains nothing yet (docs are a separate task) — no README/CLAUDE.md edits in this task.

2. Document local self-hosted runner provisioning and routing policy

• Depends on: 1

• Body:

  devkit's README is the human-facing usage doc; CLAUDE.md is the standards reference. Task: document how to provision a local machine as a self-hosted runner for gingur repos and which workflows may route to it. The runner-routing inputs already exist in the reusable workflows (see the runner input in cf.worker.deploy.yml, cf.worker.rollback.yml, claude.plan.yml, node.verify.yml, infisical.secrets.scan.yml).

  Add a README section ## Self-hosted runner (local) covering, with copy-paste commands:

  • Registration (per repo): personal accounts have no shareable/org runners — one runner instance per repo on the same machine, each in its own directory (e.g. ~/actions-runner/<repo>/), configured against https://github.com/gingur/<repo> with the single custom label local (Settings → Actions → Runners → New self-hosted runner). Connectivity is outbound-only HTTPS long-polling — no inbound ports, no tunnel.
  • Service setup: ./svc.sh install && ./svc.sh start (systemd) or the macOS launchd equivalent via the same script. Mention --ephemeral as a hardening option with its tradeoff (runner deregisters after each job; auto-re-registration needs a fresh registration token per job via the REST API and a PAT) — persistent is acceptable given the routing policy below.
  • Machine prerequisites: git, curl, tar, and the gh CLI (preinstalled on GitHub-hosted images but not on local machines; claude.plan.yml's report/baton steps and the agent itself shell out to it). Node/pnpm are NOT prerequisites — the runner bundles its JS-action runtime and actions/setup-node/pnpm/action-setup tool-cache per runner.
  • Routing policy (public repos): only operator-gated triggers may target local — issues: assigned (claude.plan), push to main (deploy), workflow_dispatch (rollback). PR-triggered workflows (verify, preview, preview-cleanup, secret scan) always stay on GitHub-hosted; cf.worker.preview*.yml deliberately have no runner input.
  • Consumer wiring: set repo variable RUNNER=local; pass runner: ${{ vars.RUNNER }} in the deploy/rollback caller workflows; claude.plan.yml reads vars.RUNNER on its own. Unset/empty variable falls back to ubuntu-latest, so flipping local ↔ hosted is a repo-variable change with no commit.
  • Repo settings hardening: Actions → Fork pull request workflows → "Require approval for all outside collaborators".
  • Caveats: if the machine is offline, jobs targeting local queue up to 24 hours and then fail (flip RUNNER back to empty to drain to hosted); OIDC/Infisical secret fetch works unchanged on self-hosted (tokens issued by GitHub, no secrets stored on the machine); a persistent runner keeps warm tool/pnpm caches as a side benefit.

  Also: add a short "Self-hosted runner routing" note to CLAUDE.md's consumer standards (the policy bullet + the vars.RUNNER wiring), and update the README reusable-workflows/permissions tables only if the new inputs warrant a column note.

  Acceptance criteria:

  • README has the ## Self-hosted runner (local) section covering all bullets above (registration, service, prereqs, routing policy, consumer wiring, hardening, caveats) with copy-paste commands.
  • CLAUDE.md consumer standards mention the routing policy and the vars.RUNNER switch.
  • Docs-only change: no workflow/action files modified.
  • The preview docs still state the fork-PR / same-repo-only exclusion.

Also worth doing on approval (operator action, not a task): close #3 as superseded — the tunnel premise is unnecessary and its open questions are answered here.

To approve: comment approval and re-assign me. To change: comment corrections and re-assign me.

---

What I did this turn: researched the ask (repo workflows, issue #3 prior art, GitHub self-hosted runner constraints for public repos and personal accounts) and posted this plan. No issues created yet.
What I need from you: review the plan — approve (and re-assign me) to have me create the two task issues, or comment corrections (and re-assign me) for a revised plan.

[gingur]

approved

[gingur-bot]

Plan approved — tasks materialized.

• Thread runner routing through operator-gated reusable workflows #47 — Thread runner routing through operator-gated reusable workflows (no dependencies)
• Document local self-hosted runner provisioning and routing policy #49 — Document local self-hosted runner provisioning and routing policy (depends on Thread runner routing through operator-gated reusable workflows #47)

Both are labeled claude-task, carry the plan bodies verbatim, and are linked as sub-issues of this ask. Implement #47 first; #49 documents the inputs it adds.

Reminder from the plan: once this lands, #3 (Cloudflare Tunnel runner POC) can be closed as superseded — the tunnel premise was unnecessary and its open questions are answered here. That's an operator call, so I haven't touched it.

---

What I did this turn: created task issues #47 and #49 from the approved plan and linked them as sub-issues.
What I need from you: nothing for planning — assign the implementation workflow to #47 when ready, and optionally close #3 as superseded.

[gingur]

Delivered: runner routing landed via #71 (task #47) and provisioning/routing docs via #73 (task #49). #3 was closed as superseded (no tunnel needed — runners connect outbound-only). To go live: register a runner labeled local per README → Self-hosted runner (local), then gh variable set RUNNER --body local in each repo that should route to it.