https://github.com/thevickypedia/github-runners
GitHub actions runners
https://github.com/thevickypedia/github-runners
Last synced: 3 months ago
JSON representation
GitHub actions runners
- Host: GitHub
- URL: https://github.com/thevickypedia/github-runners
- Owner: thevickypedia
- License: mit
- Created: 2024-09-24T03:27:44.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-11-16T00:49:59.000Z (7 months ago)
- Last Synced: 2025-02-19T12:12:26.862Z (4 months ago)
- Language: Shell
- Size: 26.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Runner (non-dockerized)
Spin up an on-demand self-hosted GitHub action runners on `Linux`, `macOS` or `Windows`** operating systems.
> **`Windows` machines require [WSL] or [Git Bash] to be installed.
### Environment Variables
> Automatically sources `.env` file in current working directory _(if available)_
- **ARTIFACT_VERSION** - Runner version. Uses the latest version from [actions/runner].
- **ACTIONS_DIR** - Directory where the runner has to be downloaded and configured. Uses the current working directory.
- **GIT_TOKEN** - Required for authentication to add runners.
- **GIT_OWNER** - GitHub account username [OR] organization name.
- **GIT_REPOSITORY** - Repository name _(required to create runners dedicated to a particular repo)_
- **RUNNER_GROUP** - Runner group. Uses `default`
- **RUNNER_NAME** - Runner name. Uses a random instance ID.
- **WORK_DIR** - Work directory. Uses `_work`
- **LABELS** - Runner labels (comma separated). Uses `"${os_name}-${architecture}"`
> [!NOTE]
>
>
> Reusability
>
> Following files/directories are created (commonly across `macOS`, `Linux` and `Windows` runners)
> only when the runner has been configured
> - `_work`
> - `_diag`
> - `.runner`
> - `.credentials`
> - `.credentials_rsaparams`
>
> So, a simple check on one or more of these files' presence should confirm if the runner has been configured already
>
> **Note:** Warnings like the ones below are common, and GitHub typically reconnects the runner automatically.
> ```text
> A session for this runner already exists.
> ```
> ```
> Runner connect error: The actions runner i-058175xh7908r2u46 already has an active session.. Retrying until reconnected.
> ```
>
> [!WARNING]
>
> Using this script **without** the env var `GIT_REPOSITORY` will create an organization level runner.
> Using self-hosted runners in public repositories pose some considerable security threats.
> - [#self-hosted-runner-security]
> - [#restricting-the-use-of-self-hosted-runners]
> - [#configuring-required-approval-for-workflows-from-public-forks]
Env vars for notifications
> This project supports [ntfy] and [telegram bot] for startup/shutdown notifications.
**NTFY**
Choose ntfy setup instructions with [basic][ntfy-setup-basic] **OR** [authentication][ntfy-setup-auth] abilities
- **NTFY_URL** - Ntfy endpoint for notifications.
- **NTFY_TOPIC** - Topic to which the notifications have to be sent.
- **NTFY_USERNAME** - Ntfy username for authentication _(if topic is protected)_
- **NTFY_PASSWORD** - Ntfy password for authentication _(if topic is protected)_
**Telegram**
Steps for telegram bot configuration
1. Use [BotFather] to create a telegram bot token
2. Send a test message to the Telegram bot you created
3. Use the URL https://api.telegram.org/bot{token}/getUpdates to get the Chat ID
- You can also use Thread ID to send notifications to a particular thread within a group
```shell
export TELEGRAM_BOT_TOKEN="your-bot-token"
export CHAT_ID=$(curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | jq -r '.result[0].message.chat.id')
```
- **TELEGRAM_BOT_TOKEN** - Telegram Bot token
- **TELEGRAM_CHAT_ID** - Chat ID to which the notifications have to be sent.
- **THREAD_ID** - Optional thread ID to send notifications to a specific thread.
> **Note:** To send notifications to threads, the bot should be added to a group with [Topics][telegram-topics] enabled.
> Send a message to the bot in a group thread
> ```shell
> export THREAD_ID=$(curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | jq -r '.result[0]|.update_id')
> ```
## License & copyright
© Vignesh Rao
Licensed under the [MIT License][license]
[actions/runner]: https://github.com/actions/runner/releases
[license]: https://github.com/thevickypedia/github-runners/blob/main/LICENSE
[ntfy]: https://ntfy.sh/
[telegram bot]: https://core.telegram.org/bots/api
[ntfy-setup-basic]: https://docs.ntfy.sh/install/
[ntfy-setup-auth]: https://community.home-assistant.io/t/setting-up-private-and-secure-ntfy-messaging-for-ha-notifications/632952
[BotFather]: https://t.me/botfather
[telegram-topics]: https://telegram.org/blog/topics-in-groups-collectible-usernames
[telegram-threads]: https://core.telegram.org/api/threads
[WSL]: https://learn.microsoft.com/en-us/windows/wsl/
[Git Bash]: https://gitforwindows.org/
[#restricting-the-use-of-self-hosted-runners]: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#restricting-the-use-of-self-hosted-runners
[#self-hosted-runner-security]: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security
[#configuring-required-approval-for-workflows-from-public-forks]: https://docs.github.com/en/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#configuring-required-approval-for-workflows-from-public-forks