How to set up self-hosted CI runners

What and why

Hosted CI runners are convenient but limited in size, slow for large caches, and unable to reach private networks. Self-hosted runners run jobs on your own hardware, giving you bigger machines, persistent caches, and access to internal resources. They also carry security responsibilities. This tutorial registers and hardens one.

Prerequisites

• A machine or VM dedicated to running jobs.
• Admin access to the CI project or org.
• Basic Linux administration skills.

Steps

1. Decide when to self-host

Use self-hosted runners for GPU workloads, large builds, private-network access, or strict data residency. For public repositories accepting outside pull requests, prefer hosted runners; untrusted code on your hardware is dangerous.

2. Provision the runner host

Use a clean, dedicated host. Install the runtime and tools your jobs need, and keep the OS patched. Treat the host as security-sensitive.

3. Register the runner

Follow the project's runner setup to download the agent and register it with a registration token:

./config.sh --url https://github.com/acme/repo --token <TOKEN>
./run.sh

The runner connects out to the CI service; no inbound ports are needed.

4. Target jobs with labels

jobs:
  build:
    runs-on: [self-hosted, linux, gpu]

Labels route specific jobs to specific runners, so only the right work lands on each host.

5. Harden and isolate

Run each job in a fresh container or ephemeral VM so one job cannot affect the next. Limit the runner's permissions, never store long-lived cloud keys on it, and disable it for untrusted forks.

Verification

Queue a job targeting your label and confirm it runs on the self-hosted machine. Check the runner shows as online in the CI settings. Confirm a second job starts from a clean environment, proving isolation.

Next Steps

Use ephemeral, autoscaling runners so each job gets a fresh instance. Monitor runner health and capacity. Rotate registration tokens and audit which workflows can use self-hosted runners.