github-self-hosted-runner

# GitHub self-hosted runner Create one isolated runner instance per repository or organization registration. Detect the operating system first and use the matching service manager: systemd on Linux or launchd on macOS. Determine the account that should own and run the runner instead of assuming a fixed username or home directory. On Linux, resolve the account and paths with: ```bash RUNNER_USER="${RUNNER_USER:-${SUDO_USER:-$USER}}" RUNNER_GROUP="$(id -gn "$RUNNER_USER")" RUNNER_HOME="$(getent passwd "$RUNNER_USER" | cut -d: -f6)" RUNNER_ROOT="$RUNNER_HOME/actions-runners" ``` On macOS, resolve the account without relying on `getent`: ```bash RUNNER_USER="${RUNNER_USER:-${SUDO_USER:-$USER}}" RUNNER_GROUP="$(id -gn "$RUNNER_USER")" RUNNER_HOME="$(dscl . -read "/Users/$RUNNER_USER" NFSHomeDirectory | awk '{print $2}')" RUNNER_ROOT="$RUNNER_HOME/actions-runners" ``` Validate that the values are non-empty and `RUNNER_HOME` exists. When commands run through `sudo`, do not accidentally use root's `$USER` or `$HOME` as the runner account. Namespace every instance by target slug: - Directory: `$RUNNER_ROOT/<slug>` - Runner name: `<hostname>-<slug>` - Custom label: `<slug>` - Linux service: `github-actions-runner@<slug>.service` - macOS launchd label: `com.github.actions.runner.<slug>` For example, `https://github.com/owner/blog` uses directory `$RUNNER_ROOT/blog`, runner name `<hostname>-blog`, and label `blog`. ## Required inputs Obtain: 1. A repository URL such as `https://github.com/owner/repository`, or an organization URL such as `https://github.com/organization`. 2. A GitHub credential authorized to manage self-hosted runners: - classic PAT with `repo` scope for a repository, or - an appropriately scoped fine-grained token. GitHub does not support account-wide runners for a personal user URL. If a one-segment GitHub URL belongs to a personal account rather than an organization, ask for a repository URL. Treat credentials as secrets: - Never print a token. - Never include it in a service unit, repository, skill file, or persistent environment file. - Put it in a mode-`0600` temporary file only for the registration operation, then securely delete it. - Recommend rotating any token pasted into chat after setup. ## Preflight 1. Detect the hostname and architecture. 2. Convert architecture names for GitHub assets: - `x86_64` → `x64` - `aarch64` or `arm64` → `arm64` 3. Derive a lowercase filesystem-safe slug from the repository name or organization name. Allow only letters, digits, `_`, and `-`. 4. Check whether the destination directory, runner registration, or service already exists. 5. Check for active jobs before stopping, replacing, or removing an existing runner. Do not interrupt a job without user confirmation. 6. Ensure `curl`, `tar`, `python3`, and the platform service manager (`systemd` on Linux, `launchd` on macOS) are available. If the instance already exists and is healthy, report that instead of creating a duplicate. If reconfiguration is requested, unregister the old instance before replacing it. ## Install the runner Fetch release metadata from GitHub's official API: ```bash curl -fsSL https://api.github.com/repos/actions/runner/releases/latest ``` Select the asset matching both operating system and architecture, named like `actions-runner-linux-<arch>-<version>.tar.gz` on Linux or `actions-runner-osx-<arch>-<version>.tar.gz` on macOS. Read its `browser_download_url` and `digest`. Download to a temporary archive, verify the SHA-256 digest, and only then extract it into `$RUNNER_ROOT/<slug>`. Set ownership recursively to `$RUNNER_USER:$RUNNER_GROUP` (on macOS, use the resolved group, commonly `staff`). Delete the temporary archive even when a command fails. Always use a fresh runner distribution for a new instance. Do not copy `.runner`, `.credentials`, `_diag`, or `_work` from another instance. ## Register Run `config.sh` as `$RUNNER_USER` from inside the instance directory. The working directory matters because runner scripts use relative paths. Use: ```bash ./config.sh \ --url '<github-url>' \ --pat "$GITHUB_TOKEN" \ --unattended \ --name '<hostname>-<slug>' \ --labels '<slug>' \ --replace ``` Pass the PAT from the protected temporary file and securely remove that file immediately afterward. Do not persist the PAT; GitHub exchanges it for runner credentials during registration. Do not use `--replace` to overwrite an unrelated live runner. Confirm that an existing runner with the same name belongs to this VM and target. ## Configure the service manager ### Linux: systemd Render a reusable template unit at `/etc/systemd/system/github-actions-runner@.service` using the resolved runner account values. Expand shell variables while writing the unit; systemd does not expand them in these fields: ```bash sudo tee /etc/systemd/system/github-actions-runner@.service >/dev/null <<EOF [Unit] Description=GitHub Actions self-hosted runner (%i) After=network-online.target Wants=network-online.target [Service] Type=simple User=${RUNNER_USER} Group=${RUNNER_GROUP} WorkingDirectory=${RUNNER_ROOT}/%i ExecStart=${RUNNER_ROOT}/%i/run.sh Restart=always RestartSec=5 KillSignal=SIGINT TimeoutStopSec=90 [Install] WantedBy=multi-user.target EOF ``` Then run: ```bash sudo systemctl daemon-reload sudo systemctl enable --now github-actions-runner@<slug>.service ``` Before replacing an existing template, inspect it and confirm its user and root directory match the resolved values. Do not disrupt instances owned by another account. ### macOS: launchd Create a per-instance LaunchDaemon plist at `/Library/LaunchDaemons/com.github.actions.runner.<slug>.plist`. Set `UserName`, `GroupName`, `WorkingDirectory`, and `ProgramArguments` to the resolved account, group, and instance path. Use `<RUNNER_ROOT>/<slug>/run.sh` as the program, set `RunAtLoad` and `KeepAlive` to true, and do not put credentials in the plist. Make the plist root-owned with mode `0644`, then load it with `sudo launchctl bootstrap system <plist-path>`. Use `sudo launchctl kickstart -k system/<label>` to start or restart the instance after confirming it has no active job. If the service is already bootstrapped, inspect it before replacing it; do not unload unrelated runners. Do not configure a Linux runner with systemd on macOS or a macOS runner with launchd on Linux. ## Verify Verify the matching service manager. On Linux: ```bash systemctl is-enabled github-actions-runner@<slug>.service systemctl is-active github-actions-runner@<slug>.service journalctl -u github-actions-runner@<slug>.service --no-pager -n 20 ``` On macOS: ```bash sudo launchctl print system/com.github.actions.runner.<slug> tail -n 20 '<RUNNER_ROOT>/<slug>/_diag/Runner_*.log' ``` The runner log must show `Connected to GitHub` and `Listening for Jobs`. Read `.runner` using UTF-8 with BOM support and confirm: - `agentName` is `<hostname>-<slug>` - `gitHubUrl` is the requested target - `workFolder` is `_work` Tell the user they can target the instance with: ```yaml runs-on: [self-hosted, <slug>] ``` Report the runner name, directory, label, service, version, and active/listening status. Do not repeat the token. ## Multiple runners on one VM Each runner needs its own directory, local credentials, listener process, label, and platform service instance. Multiple instances can run concurrently but share the machine's CPU, memory, disk, network, and—when run as the same user— filesystem trust boundary. Use separate operating system users or separate machines for repositories that should not trust each other's workflow code or files. ## Removal or renaming To remove or rename an instance: 1. Confirm it is not running a job. 2. Disable and stop the platform service: `systemctl disable --now github-actions-runner@<slug>.service` on Linux, or `launchctl bootout system/<label>` on macOS. 3. Obtain a short-lived removal token through GitHub's repository or organization runner API using the PAT. 4. Run `./config.sh remove --token '<removal-token>'` from the runner directory as `$RUNNER_USER`. 5. For a rename, register again with the new runner name and restart the service. 6. For permanent removal, delete only that explicit instance directory after registration removal succeeds and the user confirms deletion. Never delete the shared Linux systemd template while other instances use it. On macOS, remove only the specific instance plist after unloading that instance. ## Full uninstall Use this when removing every runner managed by this skill from the machine. First inventory the registrations, instance directories, and services or plists; do not assume every runner under a shared directory belongs to this setup. 1. Confirm that no runner is executing a job. Do not stop a busy runner without user confirmation. 2. Stop and disable each service. On Linux, run `sudo systemctl disable --now github-actions-runner@<slug>.service` for every instance, then confirm those units are inactive. On macOS, run `sudo launchctl bootout system/com.github.actions.runner.<slug>` for every loaded instance, then confirm those labels are no longer present. 3. For each instance, obtain a short-lived removal token from its GitHub repository or organization, then run `./config.sh remove --token '<removal-token>'` from that instance directory as `$RUNNER_USER`. Remove the token from memory and securely delete any temporary credential file. 4. Remove only the matching service configuration. On Linux, remove `/etc/systemd/system/github-actions-runner@.service` only after confirming that no other runner instances use it, then run `sudo systemctl daemon-reload`. On macOS, remove each matching plist from `/Library/LaunchDaemons/` after it has been unloaded. 5. Delete the explicit runner instance directories only after GitHub removal succeeds and the user confirms deleting the runner data. This removes binaries, credentials, diagnostics, and workspaces. Preserve unrelated files in `$RUNNER_ROOT`; remove that parent directory only if it is empty and the user confirms it should be removed. 6. Verify that the runner registrations are gone from GitHub, the services are absent or inactive, and no targeted instance directories or plists remain. This procedure does not delete `$RUNNER_USER` or its home directory. Remove an OS account only if it was created specifically for these runners, it owns no other data or services, and the user explicitly requests account deletion. Never remove system-wide dependencies such as Homebrew, Xcode, or command-line tools as part of runner cleanup. ## Failure handling - If registration fails, do not enable a restart-looping service. - Preserve downloaded binaries when useful for retry, but remove all temporary credential files. - A `404` from an organization registration endpoint often means the supplied one-segment URL is a personal account, the token lacks access, or the target is incorrect. Verify the target type before retrying. - If extraction or checksum verification fails, remove the incomplete destination or clearly mark it incomplete; never start it. - If the service starts but does not listen, inspect its journal on Linux or runner diagnostic logs on macOS; verify directory ownership, registration files, network access, and the service's working directory.