Migrate a repo's GitHub Actions CI from the self-hosted-with-fallback pattern (detect-runner reusable workflow + jobs that consume `${{ needs.detect-runner.outputs.runner }}`) to direct Blacksmith cloud runner labels. Use when: (1) User says 'blacksmith migration', 'migrate to blacksmith', 'switch to blacksmith', 'dev-blacksmith-migration', 'drop detect-runner', (2) Repo has `.github/workflows/detect-runner.yml` or any job using `runs-on: ${{ needs.<something>.outputs.runner }}`, (3) User wants to retire a self-hosted runner and rely fully on Blacksmith or another ephemeral cloud runner. Walks the gotchas — cross-instance cache miss, missing pnpm/Node setup in deploy-only jobs, container-job dubious-ownership, leftover `set-safe-directory: false` / Clean workspace / Fix workspace permissions steps.
Migrate a repo's GitHub Actions CI from the self-hosted-with-fallback pattern (detect-runner reusable workflow + jobs that consume `${{ needs.detect-runner.outputs.runner }}`) to direct Blacksmith cloud runner labels. Use when: (1) User says 'blacksmith migration', 'migrate to blacksmith', 'switch to blacksmith', 'dev-blacksmith-migration', 'drop detect-runner', (2) Repo has `.github/workflows/detect-runner.yml` or any job using `runs-on: ${{ needs.<something>.outputs.runner }}`, (3) User wants to retire a self-hosted runner and rely fully on Blacksmith or another ephemeral cloud runner. Walks the gotchas — cross-instance cache miss, missing pnpm/Node setup in deploy-only jobs, container-job dubious-ownership, leftover `set-safe-directory: false` / Clean workspace / Fix workspace permissions steps.
Blacksmith Migration
Migrate a repo from the "detect-runner with self-hosted fallback" CI pattern — the pattern /dev-actions-self-runner installs — to direct Blacksmith cloud runner labels. The same playbook applies to other ephemeral cloud runner services (RunsOn, BuildJet, Namespace, Depot) — the runner-label syntax differs, the gotchas don't.
When this skill triggers
The repo has at least one of:
.github/workflows/detect-runner.yml (or similarly named) reusable workflow that polls the GitHub API for online self-hosted runners and emits a runner output
Consumer jobs with runs-on: ${{ needs.detect-runner.outputs.runner }}
Any runs-on: mixing self-hosted and ubuntu-latest via expressions
set-safe-directory: false on actions/checkout (a self-hosted-only optimization)
If you don't see any of those, this skill is the wrong tool — the user just needs a normal runs-on label switch.
Step 1: Audit the current state
Run the audit script to find every self-hosted-ism in .github/workflows/:
Jobs that use container: (these need extra care — see Step 6)
Inter-job data sharing patterns (actions/cache/save → actions/cache/restore across jobs, or actions/upload-artifact → download-artifact)
Read the output before making any edits.
Step 2: Ask the user the 2 decisions
Don't guess; ask. The answers determine which steps below to apply.
Drop detect-runner entirely, or keep it as a fallback?
Default recommendation: drop it. Blacksmith replaces self-hosted; the polling job always sees zero online runners (Blacksmith instances are ephemeral and don't register in the org's self-hosted runners list), fires false alarms (e.g., IFTTT), and emits an ubuntu-latest output that consumers ignore once they hardcode the Blacksmith label.
Keep only when there's a real mixed fleet: dedicated self-hosted runners that do register persistently, with Blacksmith as backup.
What Blacksmith runner spec?
Default suggestion: blacksmith-2vcpu-ubuntu-2204 (matches ubuntu-latest's 2-vCPU shape). Bigger jobs may want blacksmith-4vcpu-ubuntu-2204, blacksmith-8vcpu-ubuntu-2204, etc. — confirm with the user.
Ubuntu version: ubuntu-2204 is the safe default. Use ubuntu-2404 only if the workflow explicitly needs Ubuntu 24.04 features.
ARM variant: append -arm (e.g. blacksmith-2vcpu-ubuntu-2204-arm) when targeting arm64 builds.
Step 3: Replace runs-on: values
Every runs-on: value in .github/workflows/ becomes (using the spec from Step 2):
The repo's RUNNER_CHECK_TOKEN GitHub Actions secret becomes orphan — tell the user it can be deleted manually if desired (you can't delete secrets via gh CLI without scope they may not want to grant).
If detect-runner.yml was emitting an IFTTT "self-hosted offline" notification, that goes away with the file. The deploy-status IFTTT notification (a separate job in the consumer workflow) is a different concern — leave that alone.
Step 5: Fix self-hosted leftovers in remaining jobs
For every actions/checkout step:
# Self-hosted leftover — REMOVE the with: block (or just the one option)-uses:actions/checkout@<sha>with:set-safe-directory:false# ← DELETE this option
Default set-safe-directory: true is required for container jobs to access the workspace. Leaving it false causes mysterious fatal: detected dubious ownership errors in container subprocesses.
Delete these step types if you find them — they're all "next-run cleanup" patterns that ephemeral runners don't need:
Clean workspace (rm -rf $GITHUB_WORKSPACE/... before the rest of the job)
Fix workspace permissions (chown -R ... $GITHUB_WORKSPACE at job end)
Any step that "resets" or "prepares" the workspace before checkout
Step 6: Container jobs need a manual safe.directory step (regardless of runner)
For any job that uses container: (not runs-on:), add this step before checkout:
test:runs-on:blacksmith-2vcpu-ubuntu-2204container:image:mcr.microsoft.com/playwright:v1.58.2-noblesteps:-name:Markworkspaceassafeforgitrun:gitconfig--global--addsafe.directory"$GITHUB_WORKSPACE"-uses:actions/checkout@<sha># ... rest of the steps
Why:actions/checkout (a node action) writes safe.directory to /root/.gitconfig inside the container, but shell run: steps inside the same container have HOME=/github/home and read /github/home/.gitconfig. Without this step, lifecycle scripts like pnpm install's prepare (which runs lefthook install, husky install, etc.) hit fatal: detected dubious ownership in repository at '/__w/<repo>/<repo>'.
This is not self-hosted-specific — it's a container-on-any-runner concern. The original codebase probably had this step alongside set-safe-directory: false, and the pair looked self-hosted-only. Keep this step; drop the set-safe-directory: false.
Step 7: Inter-job data sharing — prefer artifacts on ephemeral runners
If the workflow has multiple jobs and shares files between them (typical Build → Test → Deploy split), audit the existing pattern:
actions/cache/save → actions/cache/restore keyed by ${{ github.run_id }}: works on a single self-hosted runner. Blacksmith provides an accelerated cache backend that survives across instances, but actions/cache was never designed as a job-to-job pipe — it's a "speed up next run" mechanism. Misusing it as inter-job transport is fragile (cache eviction, key collisions, container-network edge cases).
actions/upload-artifact@v4 → actions/download-artifact@v4: route through api.github.com, work cross-instance, work in containers, the documented inter-job transport.
Recommended for any Blacksmith migration with multi-job workflows: switch to artifacts.
Blacksmith's accelerated actions/cache backend is fine to keep using for its intended purpose — speeding up setup-node, the pnpm store, and build-tool caches across runs. Just don't use it as an inter-job pipe within a single run.
Step 8: Audit deploy-only jobs
Any job that does NOT have its own actions/checkout but DOES run commands like pnpm, npm, or node is a self-hosted leftover. On the persistent runner, the workspace and toolchain were inherited from a previous job; on ephemeral runners, each job starts on a fresh VM.
Symptom: pnpm: command not found in the deploy job after Build and Test pass.
Fix: add the missing setup steps at the top of the job:
deploy:steps:-name:Checkoutrepository# if the job needs package.json / pnpm-workspace.yamluses:actions/checkout@<sha>-name:Setuppnpmuses:pnpm/action-setup@<sha>-name:SetupNode.jsuses:actions/setup-node@<sha>with:node-version:<matchtheotherjobs># ... existing artifact downloads, deploy commands, etc.
If the deploy job runs pnpm add -w <pkg> or any command that needs a pnpm workspace, the actions/checkout is required (otherwise there's no package.json / pnpm-workspace.yaml for pnpm to find). Otherwise just the two setup steps may be enough.
Step 9: Validate — beware the partial-validation trap
PR-level CI (often pr-checks.yml) usually runs a single-job preview-deploy workflow. It cannot exercise the cross-job artifact passing or the container-job paths that the production deploy uses. Pre-merge green on pr-checks is necessary but not sufficient.
The full validation requires merging to the trigger branch (usually main) and watching the production deploy. Plan for one or more iteration cycles directly on main if the user is OK with that, or coordinate via short-lived hotfix PRs.
For each push, watch CI with /watch-ci <pr> (PR mode) or /watch-ci (auto-detects the merged-PR path on the target branch).
Common failure modes (one-liner fixes)
When a deploy fails post-merge, check the failing job's step name and match against the table below before re-reading logs in detail:
Failing step output
Cause
Fix
Cache not found for input keys: ...-<run_id>
actions/cache used as inter-job transport on ephemeral runners
Switch to artifacts (Step 7)
pnpm: command not found in deploy job
Deploy-only job missing setup steps
Add Setup pnpm + Setup Node.js (Step 8)
fatal: detected dubious ownership in repository at '/__w/...'
Container-job HOME mismatch between checkout and shell git
Add manual safe.directory step before checkout (Step 6)
pnpm add -w <pkg> errors with no pnpm-workspace.yaml found
Deploy job has no checkout
Add actions/checkout to the job (Step 8)
Build job's IFTTT alert "self-hosted runner offline" still firing
This skill is for the migration. Day-to-day GitHub Actions best practices (timeouts, concurrency, action pinning, security) live in /gh-actions-wisdom. Read both when starting a migration so you don't accidentally regress on those general rules while shuffling runner labels.
