How to Migrate GitHub-Hosted Jobs to Self-Hosted Runners in GitHub Actions

The workflow change is just runs-on, but the real work is replacing the toolchain that GitHub-hosted images pre-install for you.

Switch runs-on: ubuntu-latest to your self-hosted labels, then make sure the runner has everything the hosted image shipped (Node, Docker, build tools). Migrate one workflow first and compare results.

Steps

• Stand up and register a self-hosted runner with clear labels.
• Change runs-on on one workflow to those labels.
• Install or bake in the tools the hosted image provided.
• Compare timing and pass rate, then migrate the rest.

Before and after

# Before
jobs:
  build:
    runs-on: ubuntu-latest

# After
jobs:
  build:
    runs-on: [self-hosted, linux, x64]

Gotchas

• Hosted images preinstall dozens of tools; missing ones surface as "command not found" on the self-hosted host.
• You now own patching, scaling, and uptime; budget for that operational cost.
• Managed runners (Latchkey) keep the hosted-image convenience while giving you self-hosted economics, so you can migrate without taking on the ops.

Related guides