https://github.com/thevickypedia/github-runner-linux
Spin up an on-demand self-hosted GitHub action runner with multi-arch supported Ubuntu image.
https://github.com/thevickypedia/github-runner-linux
Last synced: about 2 months ago
JSON representation
Spin up an on-demand self-hosted GitHub action runner with multi-arch supported Ubuntu image.
- Host: GitHub
- URL: https://github.com/thevickypedia/github-runner-linux
- Owner: thevickypedia
- Created: 2024-09-01T02:16:58.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-02-24T03:31:32.000Z (3 months ago)
- Last Synced: 2025-03-29T06:04:44.488Z (2 months ago)
- Language: Shell
- Homepage: https://hub.docker.com/r/thevickypedia/github-runner-linux
- Size: 27.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# GitHub Runner Linux
[![Test Runner][badges-test]][links-test]
[![Build and Publish][badges-build]][links-build]
Spin up an on-demand self-hosted GitHub action runner with multi-arch supported Ubuntu image.
## Usage
**Pre-built [platform agnostic]**
```shell
docker run thevickypedia/github-runner-linux
```
**Build from source [platform specific]**
```shell
git clone https://github.com/thevickypedia/github-runner-linux.git
cd github-runner-linux
```
**Imperative**
```shell
docker build --platform linux/amd64 -t github-runner-linux .
docker run --platform linux/amd64 github-runner-linux
```
**Declarative**
```shell
docker compose -f docker-compose-amd64.yml up
```
### Environment Variables
**Mandatory**
- **GIT_TOKEN** - Required for authentication to add runners.
- **GIT_OWNER** - GitHub account username [OR] organization name.
**Optional**
- **GITHUB_API_URL** - GitHub API endpoint. Defaults to https://api.github.com
- **GITHUB_SERVER_URL** - GitHub server endpoint. Defaults to https://github.com
- **GIT_REPOSITORY** - Repository name _(required to create runners dedicated to a particular repo)_
- **RUNNER_VERSION** - GitHub runner version. Defaults to `2.322.0`
- **RUNNER_GROUP** - Runner group. Uses `default`
- **RUNNER_NAME** - Runner name. Defaults to a random instance ID.
- **WORK_DIR** - Work directory. Defaults to `_work`
- **LABELS** - Runner labels (comma separated). Defaults to `"docker-node,${os_name}-${architecture}"`
- **REUSE_EXISTING** - Re-use existing configuration. Defaults to `false`
> [!NOTE]
>
> `REUSE_EXISTING` flag can be useful when a container restarts due to an issue or
> when a container is reused after being terminated without shutting down gracefully.
>
> More info
>
> 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 image **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')
> ```
## Development
Set latest `RUNNER_VERSION`
```shell
RUNNER_VERSION=$(curl -sL \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/repos/actions/runner/releases/latest | jq .tag_name --raw-output)
export RUNNER_VERSION="${RUNNER_VERSION#?}"
```
#### Build
```shell
docker build --build-arg RUNNER_VERSION=$RUNNER_VERSION -t runner .
```
[badges-test]: https://github.com/thevickypedia/github-runner-linux/actions/workflows/test.yml/badge.svg
[links-test]: https://github.com/thevickypedia/github-runner-linux/actions/workflows/test.yml
[badges-build]: https://github.com/thevickypedia/github-runner-linux/actions/workflows/main.yml/badge.svg
[links-build]: https://github.com/thevickypedia/github-runner-linux/actions/workflows/main.yml
[docker-compose]: https://github.com/thevickypedia/github-runner-linux/blob/main/docker-compose.yml
[docker-compose-amd64]: https://github.com/thevickypedia/github-runner-linux/blob/main/docker-compose-amd64.yml
[docker-compose-arm64]: https://github.com/thevickypedia/github-runner-linux/blob/main/docker-compose-arm64.yml
[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
[#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