git:20260906.23d8e79 to git:20261004.11832f3

117 added, 54 removed. Audit B to B.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: github-self-hosted-runner
description:
Install, register, namespace, verify, or remove one or more GitHub Actions
- self-hosted runners on a Linux host. Use when a user provides a GitHub
- repository or organization URL and wants a persistent runner managed by
- systemd, including adding another repository-specific runner to a machine that
- already has runners.
+ self-hosted runners on a Linux or macOS host. Use when a user provides a
+ GitHub repository or organization URL and wants a persistent runner managed by
+ systemd on Linux or launchd on macOS, including adding another
+ repository-specific runner to a machine that already has runners.
---
# GitHub self-hosted runner
Create one isolated runner instance per repository or organization registration.
- Determine the account that should own and run the runner instead of assuming a
- fixed username or home directory:
+ 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"
```
- Validate that all four values are non-empty and that `RUNNER_HOME` exists. When
- commands are run through `sudo`, do not accidentally use root's `$USER` or
- `$HOME` as the runner account.
+ 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>`
- - Service: `github-actions-runner@<slug>.service`
-
- For example, `https://github.com/owner/blog` becomes:
+ - Linux service: `github-actions-runner@<slug>.service`
+ - macOS launchd label: `com.github.actions.runner.<slug>`
- - `$RUNNER_ROOT/blog`
- - `<hostname>-blog`
- - label `blog`
- - `github-actions-runner@blog.service`
+ 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 `systemd` are available.
+ 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 named like:
-
- ```text
- actions-runner-linux-<arch>-<version>.tar.gz
- ```
-
- Read its `browser_download_url` and `digest`. Download to a temporary archive,
- verify the SHA-256 digest, and only then extract it into:
-
- ```text
- $RUNNER_ROOT/<slug>
- ```
+ 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`. Delete the temporary
- archive even when a command fails.
+ 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 systemd
+ ## 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. Shell variables are not expanded by systemd in `User=`,
- `Group=`, `WorkingDirectory=`, or `ExecStart=`, so expand them while writing the
- unit:
+ 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
```
- After creating or changing the template:
+ Then run:
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now github-actions-runner@<slug>.service
```
- Before replacing an existing systemd template, inspect it and confirm that its
- user and root directory match `$RUNNER_USER` and `$RUNNER_ROOT`. Do not disrupt
- existing runner instances owned by another account.
+ 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 all of the following:
+ 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
```
- The journal must show:
+ On macOS:
- ```text
- Connected to GitHub
- Listening for Jobs
+ ```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 systemd instance. Multiple instances can run concurrently but share the VM's
- CPU, memory, disk, network, and—when run as the same Linux user—filesystem trust
- boundary.
+ 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 Linux users or separate VMs for repositories that should not trust
- each other's workflow code or files.
+ 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 `github-actions-runner@<slug>.service`.
+ 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 systemd template while other runner instances use it.
+ 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 and verify
- directory ownership, registration files, network access, and the unit's
- working directory.
+ - 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.