Skip to content

Commit d828367

Browse files
jonpughjonpugh
committed
"Write me a README."
1 parent 1628c9d commit d828367

1 file changed

Lines changed: 163 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 163 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,164 @@
11
# github-runner-starter
2-
A single script to install, configure, launch, and cleanup GitHub runners.
2+
3+
A single Bash script to install, configure, optionally launch, and clean up GitHub self-hosted runners. It automates:
4+
- Downloading the proper Actions Runner build for your OS/arch
5+
- Getting a registration token via the GitHub API
6+
- Configuring the runner with your repository, name, and labels
7+
- Optionally launching `run.sh` and handling cleanup on exit
8+
9+
This project also includes a minimal Docker setup for local testing and examples.
10+
11+
## Features
12+
- One-command setup for a self-hosted runner
13+
- Works with environment variables or CLI flags (or a `.env` file)
14+
- Automatically detects architecture (x64/arm64) and latest runner release
15+
- Graceful stop/cancel handlers that can remove the runner and unregister it
16+
- Optional Docker compose example for running/scaling multiple runners
17+
18+
## Requirements
19+
- Bash, curl, tar
20+
- jq (used to parse GitHub API responses)
21+
- Network access to GitHub
22+
- A GitHub Personal Access Token (classic) or PAT with appropriate scopes: needs `repo` access and "self-hosted runners" administration for the target repository. Practically, you’ll want a token that can create registration tokens on the repository (often described here as admin:write on the repo in this script’s messages).
23+
24+
Note: The script currently downloads Linux runners. If running on another OS, adapt accordingly.
25+
26+
## Installation
27+
You can use the script directly, or install it via Composer so `github-runner-starter` is available on your PATH.
28+
29+
### Option A: Use the script directly
30+
- Clone or download this repository.
31+
- From the project root, run:
32+
- `./github-runner-starter --help`
33+
34+
### Option B: Composer
35+
If Composer is available in your environment:
36+
- Add as a dependency or install globally. The package exposes a bin named `github-runner-starter`.
37+
38+
composer.json excerpt:
39+
```
40+
"bin": [
41+
"github-runner-starter"
42+
]
43+
```
44+
45+
## Quick start
46+
1) Ensure you have a suitable PAT and know the `owner/repo` you want to register the runner to.
47+
2) In a working directory, create a `.env` file or pass flags (see below).
48+
3) Run the script.
49+
50+
Example with flags, including launching the runner immediately:
51+
```
52+
./github-runner-starter \
53+
--repo=owner/repo \
54+
--token=ghp_... \
55+
--labels=my-runner,linux \
56+
--run
57+
```
58+
59+
If you omit `--run`, the script will download and configure the runner, but not launch `run.sh`. You can start it later manually from the runner directory.
60+
61+
## CLI options and environment variables
62+
All options can be provided either as CLI flags or via environment variables. A `.env` file in the current working directory will be sourced automatically.
63+
64+
- --runner-path (env: RUNNER_PATH)
65+
- The path where the runner files will be downloaded/extracted (default: `runner`).
66+
- --cleanup-runner (env: RUNNER_CLEANUP)
67+
- When canceling with Ctrl+C, remove the downloaded runner directory. Set value to `yes` to enable.
68+
- --token (env: GITHUB_TOKEN)
69+
- GitHub API token used to obtain the registration token for the runner. Required when configuring.
70+
- --repo (env: GITHUB_REPOSITORY)
71+
- Target repository, e.g., `owner/repo`. Required when configuring.
72+
- --name (env: RUNNER_CONFIG_NAME)
73+
- Runner name. Defaults to `$(whoami)@$(hostname -f)`.
74+
- --labels (env: RUNNER_CONFIG_LABELS)
75+
- Comma-separated labels. Defaults to `$(whoami)@$(hostname -f)` and the runner name is also appended.
76+
- --run (env: RUNNER_RUN)
77+
- If set, the script will launch `run.sh` after configuration completes.
78+
- --config-sh-options (env: RUNNER_CONFIG_OPTIONS)
79+
- Extra options to append to the runner’s `config.sh` command.
80+
- --no-config (env: RUNNER_CONFIG)
81+
- Skip the `config.sh` step. Useful if you only want to download/extract the runner.
82+
- --help
83+
- Show inline help.
84+
85+
See `.env.example` for a full set of variables and inline documentation.
86+
87+
## How it works
88+
At a high level the script does the following:
89+
1) Verify inputs, source `.env` if present, and compute defaults.
90+
2) Request a short-lived registration token from the GitHub API for the given repository.
91+
3) Determine the latest runner version and your architecture.
92+
4) Download the appropriate runner tarball if not already present and extract it.
93+
5) Run the runner’s `config.sh` with your parameters and labels.
94+
6) Optionally start `run.sh` and wait on it.
95+
96+
On SIGTERM (stop) the script attempts to stop the runner and unregister it using `config.sh remove` with the same registration token. On SIGINT (Ctrl+C/cancel) it can optionally delete the runner directory if `RUNNER_CLEANUP=yes` is set.
97+
98+
## Examples
99+
- Configure only (no immediate run):
100+
```
101+
./github-runner-starter --repo=owner/repo --token=ghp_...
102+
```
103+
104+
- Configure and run:
105+
```
106+
./github-runner-starter --repo=owner/repo --token=ghp_... --run
107+
```
108+
109+
- Custom path and labels:
110+
```
111+
./github-runner-starter \
112+
--repo=owner/repo \
113+
--token=ghp_... \
114+
--runner-path=/opt/gh-runner \
115+
--labels=linux,x64
116+
```
117+
118+
- Pass extra options to config.sh:
119+
```
120+
./github-runner-starter \
121+
--repo=owner/repo \
122+
--token=ghp_... \
123+
--config-sh-options="--ephemeral"
124+
```
125+
126+
## Docker usage (optional)
127+
This repository includes a Dockerfile and docker-compose.yml for testing/development.
128+
129+
- Build and run with docker compose:
130+
```
131+
docker compose up --build
132+
```
133+
The compose file passes through `GITHUB_TOKEN` and targets this repo by default. You can override env vars via your shell or a `.env` file.
134+
135+
- Scaling multiple runners:
136+
The `whichami` helper in this repo, used by `docker-entrypoint`, creates a unique suffix for the runner name when scaling services:
137+
```
138+
docker compose up --build --scale runner=3
139+
```
140+
Each container will get a distinct `RUNNER_CONFIG_NAME` like `runner1@hostname`, `runner2@hostname`, etc.
141+
142+
Note: The provided Docker image is for development. It installs dependencies and runs as the `runner` user in `/github-runner-starter`.
143+
144+
## Troubleshooting
145+
- "GITHUB_REPOSITORY is required": Provide `--repo=owner/repo` or set `GITHUB_REPOSITORY`.
146+
- "GITHUB_TOKEN is required": Provide `--token=...` or set `GITHUB_TOKEN`. Ensure it has sufficient permissions to create a registration token for the repo.
147+
- "Unable to get registration token": Often indicates insufficient token scope, wrong repo, or network issues. The script will echo the API response for details.
148+
- "Unable to determine CLI version": Ensure your token can access the `actions/runner` releases API endpoint and network egress is available.
149+
- Architecture errors: The script detects `uname -m` as `x86_64` (x64) or `arm64`. Other architectures are not handled.
150+
151+
## Security considerations
152+
- Treat `GITHUB_TOKEN` as sensitive. Avoid committing it to source control or baking it into images.
153+
- When using Docker, prefer passing the token via environment at runtime, not building it into the image.
154+
155+
## Notes
156+
157+
I wrote the shell script. JetBrains Junie AI wrote the README from that.
158+
159+
## License
160+
MIT License. See LICENSE for details.
161+
162+
## Author
163+
- Jon Pugh (@jonpugh)
164+
- Junie AI in PHPStorm.

0 commit comments

Comments
 (0)