GitHub Runner Linux

Spin up an on-demand self-hosted GitHub action runner with multi-arch supported Ubuntu image.

Usage

Pre-built [platform agnostic]

docker run thevickypedia/github-runner-linux

Build from source [platform specific]

git clone https://github.com/thevickypedia/github-runner-linux.git
cd github-runner-linux

Imperative

docker build --platform linux/amd64 -t github-runner-linux .
docker run --platform linux/amd64 github-runner-linux

Declarative

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.

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 OR authentication 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

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 enabled.
Send a message to the bot in a group thread

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

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

docker build --build-arg RUNNER_VERSION=$RUNNER_VERSION -t runner .