PHPackages jonpugh/github-runner - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [DevOps & Deployment](/categories/devops) 4. / 5. jonpugh/github-runner ActiveLibrary[DevOps & Deployment](/categories/devops) jonpugh/github-runner ===================== A shell script for installing, configuring, and launching github runners in a single process. v1.2.1(9mo ago)01.4k—2.8%MITShellCI passing Since Nov 20Pushed 9mo ago1 watchersCompare [ Source](https://github.com/operations-project/github-runner-starter)[ Packagist](https://packagist.org/packages/jonpugh/github-runner)[ RSS](/packages/jonpugh-github-runner/feed)WikiDiscussions main Synced 3w ago READMEChangelog (5)DependenciesVersions (10)Used By (0) github-runner-starter ===================== [](#github-runner-starter) [![image](https://private-user-images.githubusercontent.com/106420/494412350-63705306-b13c-4bfe-b5c3-91ab26a7b20a.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODIzNTQwMDcsIm5iZiI6MTc4MjM1MzcwNywicGF0aCI6Ii8xMDY0MjAvNDk0NDEyMzUwLTYzNzA1MzA2LWIxM2MtNGJmZS1iNWMzLTkxYWIyNmE3YjIwYS5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwNjI1JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDYyNVQwMjE1MDdaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1kZGRiNTFhODU3NmVlNzNkM2NmZDZiMTEzNDUxMmJjYmFhNzY1NDhlNWI4MGZhMjVhZjI3NTE1OWIyZWYyNmVjJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZyZXNwb25zZS1jb250ZW50LXR5cGU9aW1hZ2UlMkZwbmcifQ.ILgmcTluqrGGfZHsK5JsfY1U-c4zKD__WN2kBuH2zFg)](https://private-user-images.githubusercontent.com/106420/494412350-63705306-b13c-4bfe-b5c3-91ab26a7b20a.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODIzNTQwMDcsIm5iZiI6MTc4MjM1MzcwNywicGF0aCI6Ii8xMDY0MjAvNDk0NDEyMzUwLTYzNzA1MzA2LWIxM2MtNGJmZS1iNWMzLTkxYWIyNmE3YjIwYS5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwNjI1JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDYyNVQwMjE1MDdaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1kZGRiNTFhODU3NmVlNzNkM2NmZDZiMTEzNDUxMmJjYmFhNzY1NDhlNWI4MGZhMjVhZjI3NTE1OWIyZWYyNmVjJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZyZXNwb25zZS1jb250ZW50LXR5cGU9aW1hZ2UlMkZwbmcifQ.ILgmcTluqrGGfZHsK5JsfY1U-c4zKD__WN2kBuH2zFg)A single Bash script to install, configure, optionally launch, and clean up GitHub self-hosted runners. It automates: - Downloading the proper Actions Runner build for your OS/arch - Getting a registration token via the GitHub API - Configuring the runner with your repository, name, and labels - Optionally launching `run.sh` and handling cleanup on exit This project also includes a minimal Docker setup for local testing and examples. Features -------- [](#features) - One-command setup for a self-hosted runner - Works with environment variables or CLI flags (or a `.env` file) - Automatically detects architecture (x64/arm64) and latest runner release - Graceful stop/cancel handlers that can remove the runner and unregister it - Optional Docker compose example for running/scaling multiple runners Requirements ------------ [](#requirements) - Bash, curl, tar - jq (used to parse GitHub API responses) - Network access to GitHub - 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). Installation ------------ [](#installation) You can use the script directly, or install it via Composer so `github-runner-starter` is available on your PATH. ### Option A: Use the script directly [](#option-a-use-the-script-directly) - Clone or download this repository. - From the project root, run: - `./github-runner-starter --help` ### Option B: Composer [](#option-b-composer) If Composer is available in your environment: - Add as a dependency or install globally. The package exposes a bin named `github-runner-starter`. composer.json excerpt: ``` "bin": [ "github-runner-starter" ] ``` Quick start ----------- [](#quick-start) 1. Ensure you have a suitable PAT and know the `owner/repo` you want to register the runner to. 2. In a working directory, create a `.env` file or pass flags (see below). 3. Run the script. Example with flags, including launching the runner immediately: ``` export GITHUB_REPOSITORY=operations-project/github-runner-starter export GITHUB_TOKEN=ghp_*** ./github-runner-starter \ --labels=my-runner,linux \ --run ``` 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. CLI options and environment variables ------------------------------------- [](#cli-options-and-environment-variables) 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. - --runner-path (env: RUNNER\_PATH) - The path where the runner files will be downloaded/extracted (default: `runner`). - --cleanup-runner (env: RUNNER\_CLEANUP) - When canceling with Ctrl+C, remove the downloaded runner directory. Set value to `yes` to enable. - --token (env: GITHUB\_TOKEN) - GitHub API token used to obtain the registration token for the runner. Required when configuring. - --repo (env: GITHUB\_REPOSITORY) - Target repository, e.g., `owner/repo`. Required when configuring. - --name (env: RUNNER\_CONFIG\_NAME) - Runner name. Defaults to `$(whoami)@$(hostname -f)`. - --labels (env: RUNNER\_CONFIG\_LABELS) - Comma-separated labels. Defaults to `$(whoami)@$(hostname -f)` and the runner name is also appended. - --run (env: RUNNER\_RUN) - If set, the script will launch `run.sh` after configuration completes. - --config-sh-options (env: RUNNER\_CONFIG\_OPTIONS) - Extra options to append to the runner’s `config.sh` command. - --no-config (env: RUNNER\_CONFIG) - Skip the `config.sh` step. Useful if you only want to download/extract the runner. - --help - Show inline help. See `.env.example` for a full set of variables and inline documentation. How it works ------------ [](#how-it-works) At a high level the script does the following: 1. Verify inputs, source `.env` if present, and compute defaults. 2. Request a short-lived registration token from the GitHub API for the given repository. 3. Determine the latest runner version and your architecture. 4. Download the appropriate runner tarball if not already present and extract it. 5. Run the runner’s `config.sh` with your parameters and labels. 6. Optionally start `run.sh` and wait on it. 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. Examples -------- [](#examples) - Configure only (no immediate run): ``` ./github-runner-starter ``` - Configure and run: ``` ./github-runner-starter --run ``` - Custom path and labels: ``` ./github-runner-starter \ --runner-path=/opt/gh-runner \ --labels=linux,x64 ``` - Pass extra options to config.sh: ``` ./github-runner-starter \ --config-sh-options="--ephemeral" ``` Docker usage (optional) ----------------------- [](#docker-usage-optional) This repository includes a Dockerfile and docker-compose.yml for testing/development. - Build and run with docker compose: ``` docker compose up --build ``` 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. - Scaling multiple runners: The `whichami` helper in this repo, used by `docker-entrypoint`, creates a unique suffix for the runner name when scaling services: ``` docker compose up --build --scale runner=3 ``` Each container will get a distinct `RUNNER_CONFIG_NAME` like `runner1@hostname`, `runner2@hostname`, etc. Note: The provided Docker image is for development. It installs dependencies and runs as the `runner` user in `/github-runner-starter`. Troubleshooting --------------- [](#troubleshooting) - "GITHUB\_REPOSITORY is required": Provide `--repo=owner/repo` or set `GITHUB_REPOSITORY`. - "GITHUB\_TOKEN is required": Provide `--token=...` or set `GITHUB_TOKEN`. Ensure it has sufficient permissions to create a registration token for the repo. - "Unable to get registration token": Often indicates insufficient token scope, wrong repo, or network issues. The script will echo the API response for details. - "Unable to determine CLI version": Ensure your token can access the `actions/runner` releases API endpoint and network egress is available. - Architecture errors: The script detects `uname -m` as `x86_64` (x64) or `arm64`. Other architectures are not handled. Security considerations ----------------------- [](#security-considerations) - Treat `GITHUB_TOKEN` as sensitive. Avoid committing it to source control or baking it into images. - When using Docker, prefer passing the token via environment at runtime, not building it into the image. Notes ----- [](#notes) I wrote the shell script. JetBrains Junie AI wrote the README from that. License ------- [](#license) MIT License. See LICENSE for details. Author ------ [](#author) - Jon Pugh (@jonpugh) - Junie AI in PHPStorm. ### Health Score 35 — LowBetter than 77% of packages Maintenance58 Moderate activity, may be stable Popularity19 Limited adoption so far Community9 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 95.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~52 days Recently: every ~19 days Total 7 Last Release 274d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/10539fb9e887c35b626eba70c97dd9d53ba14e987d4f129b55a488664a834eca?d=identicon)[jonpugh](/maintainers/jonpugh) --- Top Contributors [![jonpugh](https://avatars.githubusercontent.com/u/106420?v=4)](https://github.com/jonpugh "jonpugh (43 commits)")[![jpugh-miax](https://avatars.githubusercontent.com/u/182253973?v=4)](https://github.com/jpugh-miax "jpugh-miax (2 commits)") ### Embed Badge ![Health badge](/badges/jonpugh-github-runner/health.svg) ``` [![Health](https://phpackages.com/badges/jonpugh-github-runner/health.svg)](https://phpackages.com/packages/jonpugh-github-runner) ``` ### Alternatives [ryoluo/sail-ssl Laravel Sail plugin to enable SSL (HTTPS) connection with Nginx. 192739.0k3](/packages/ryoluo-sail-ssl)[sarfraznawaz2005/servermonitor Laravel package to periodically monitor the health of your server and website. 19613.5k1](/packages/sarfraznawaz2005-servermonitor)[tiamo/phpas2 PHPAS2 is a php-based implementation of the EDIINT AS2 standard 4676.9k](/packages/tiamo-phpas2)[wapmorgan/php-rpm-packager RPM packager for PHP applications. 106.5k](/packages/wapmorgan-php-rpm-packager) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)