GitHub Runners

Scripts to simplify the management of multiple self-hosted GitHub 操作 runners on a local macOS machine.

Why?

GitHub's model for managing multiple self-hosted runners is designed around 组织. If you have a personal account and want to run dedicated runners for several of your personal repositories, the process can be cumbersome.

This project was created to solve that problem. It provides a simple, automated way to install, register, and manage multiple self-hosted runners on a single machine, with each runner dedicated to a specific personal repository.

What It Does

This repository contains two primary Python scripts:

• bootstrap_runner.py: Automates the entire setup process. For each repository you specify, it:
  • Fetches a registration token from the GitHub API.
  • Downloads the latest official GitHub 操作 runner for macOS (Apple Silicon).
  • Configures the runner and installs it as a system service that starts on boot.
• runners.py: A simple command-line tool to manually start or stop all the runner services you've installed.

Requirements

1. A Mac with Apple Silicon (arm64).
2. Python 3 installed.
3. A GitHub Personal Access Token (PAT).
   • You can create a PAT here.
   • The token requires the repo scope to allow the script to register runners for your private and public repositories.

Setup and Installation

关注 these steps to get your runners configured and installed.

1. Clone This 仓库

First, clone this repository to your local machine.

git clone https://github.com/DanielStormApps/github-runners.git
cd github-runners

2. Configure the Bootstrap Script

Open the bootstrap_runner.py file in a text editor. You need to edit the three configuration variables at the top of the file:

• PAT: Your GitHub Personal Access Token you created earlier.
• OWNER: Your GitHub username.
• REPOS: A Python list of the repository names you want to create runners for.

# ──────────────────────────────────────────────────────────────────────────────
# CONFIGURATION – change these three lines to suit your repos / account
# ──────────────────────────────────────────────────────────────────────────────
PAT: str   = os.getenv("GITHUB_PAT") or "ghp_YourPersonalAccessTokenHere"
OWNER: str = "YourGitHubUserName"
REPOS: list[str] = [
    "my-awesome-repo",
    "my-other-cool-project",
    "a-third-repo",
]
# ──────────────────────────────────────────────────────────────────────────────

Note: The script will automatically create a gh-runners directory in your home folder (~/gh-runners) to store the runner files. You do not need to create this directory yourself.

3. Run the Bootstrap Script

Once configured, run the bootstrap script from your terminal.

python3 bootstrap_runner.py

The script will loop through your list of repositories, downloading, configuring, and installing a dedicated runner for each one. You'll see output confirming that each runner was installed successfully.

Usage

The bootstrap_runner.py script installs the runners as services, which means they will automatically start when you boot your machine. However, you can manually control them without a restart using the runners.py script.

To Start All Runners:

This will start any runners that are currently stopped.

python3 runners.py start

To Stop All Runners:

This will stop all running self-hosted runners.

python3 runners.py stop

License

This project is released under the MIT License. See the LICENSE file for more information.