Skip to content

self-hosted-runner.md

Latest commit

 

History

History
89 lines (61 loc) · 2.13 KB

self-hosted-runner.md

File metadata and controls

89 lines (61 loc) · 2.13 KB

GitHub Actions – Self-Hosted Runner

Why a self-hosted runner exists in this repo

This repository uses a self-hosted GitHub Actions runner for PR checks.

Motivation

  • GitHub-hosted runners can experience queue delays
  • PR checks are required to merge to main
  • A blocked runner blocks all development

Using a self-hosted runner:

  • guarantees availability
  • improves feedback time
  • mirrors real-world platform engineering practices

This setup is intentionally educational and operational.

When to use a self-hosted runner

Self-hosted runners are appropriate when:

  • CI reliability matters more than zero maintenance
  • Builds require special tooling or architecture (e.g. ARM64)
  • You want deterministic capacity
  • You want to learn platform operations

They are not always required and should be evaluated per team.

Runner architecture

  • Runner type: Self-hosted
  • OS: macOS
  • Architecture: ARM64 (Apple Silicon)
  • Labels used in workflows:
    • self-hosted
    • macos
    • arm64

Custom labels are intentionally avoided to remain compatible with actionlint.

How the runner is installed (local Mac)

The runner is installed outside the repository to avoid accidental commits.

mkdir -p ~/actions-runner
cd ~/actions-runner

Installation steps

Installation steps are generated by GitHub: Repo → Settings → Actions → Runners → New self-hosted runner

The runner is configured interactively and started with: ./run.sh

While running, the terminal must remain open.

Operational considerations

Capacity

  • One runner executes one job at a time
  • Jobs will queue sequentially

Availability

  • If the Mac is asleep or offline, PR checks will queue
  • Restart the runner by re-running ./run.sh

Security

  • Runner executes code from PRs
  • Only trusted collaborators should have push access
  • Secrets are injected via GitHub Actions, not stored locally

Trade-offs vs GitHub-hosted runners

Aspect GitHub-hosted Self-hosted
Availability Best effort Deterministic
Maintenance None. Required
Cost Free Local resources
Control Limited Full