feat(docker): enhance GitHub runner configuration and documentation

- Added support for dynamic runner names using environment variable expansion.
- Updated README with examples of configuring Docker containers and environment variables.
- Improved the safety of running configuration commands in entrypoint script by using array arguments instead of eval.
- Added gettext-base package to Dockerfile for environment variable substitution capabilities.

Author: winromulus

.claude/settings.local.json

@@ -24,7 +24,10 @@
       "Bash(git add:*)",
       "Bash(git commit:*)",
       "Bash(git rm:*)",
-      "Bash(grep:*)"
+      "Bash(grep:*)",
+      "WebSearch",
+      "Bash(docker compose:*)",
+      "Bash(docker ps:*)"
     ],
     "deny": []
   }

README.md

@@ -82,6 +82,46 @@ docker run -d \
   emberstack/github-actions-runner:latest
 ```
 
+#### Dynamic Runner Naming with Environment Variables
+The `GITHUB_RUNNER_NAME` supports safe environment variable expansion, allowing dynamic runner names based on any runtime environment variable:
+
+```bash
+# Use container hostname (container ID in Docker)
+docker run -d \
+  --name github-runner \
+  -e GITHUB_RUNNER_URL="https://github.com/your-org/your-repo" \
+  -e GITHUB_RUNNER_PAT="your-personal-access-token" \
+  -e GITHUB_RUNNER_NAME='$HOSTNAME' \
+  emberstack/github-actions-runner:latest
+
+# Combine with prefix/suffix
+docker run -d \
+  --name github-runner \
+  -e GITHUB_RUNNER_URL="https://github.com/your-org/your-repo" \
+  -e GITHUB_RUNNER_PAT="your-personal-access-token" \
+  -e GITHUB_RUNNER_NAME='runner-$HOSTNAME' \
+  emberstack/github-actions-runner:latest
+
+# Use in Docker Compose with custom hostname
+services:
+  runner:
+    image: emberstack/github-actions-runner:latest
+    hostname: worker-node-1
+    environment:
+      GITHUB_RUNNER_URL: "https://github.com/your-org/your-repo"
+      GITHUB_RUNNER_PAT: "your-personal-access-token"
+      GITHUB_RUNNER_NAME: 'runner-$HOSTNAME'  # Will be "runner-worker-node-1"
+```
+
+**Examples of Supported Variables:**
+- `$HOSTNAME` or `${HOSTNAME}` - The container's hostname (container ID by default in Docker)
+- `$USER` or `${USER}` - The current user (typically "runner")
+- `$HOME` or `${HOME}` - The user's home directory
+- `$PATH` - System PATH
+- Any custom environment variable you define
+
+**Note:** Use single quotes (`'`) to prevent variable expansion on the host shell, allowing expansion inside the container. Variable expansion is performed safely using `envsubst`, preventing code injection.
+
 In ephemeral mode, the runner will:
 - Process only one job and then automatically deregister
 - Provide a clean, isolated environment for each workflow run
@@ -91,8 +131,7 @@ In ephemeral mode, the runner will:
 #### Environment Variables
 - `GITHUB_RUNNER_URL` (required): Repository, organization, or enterprise URL
 - `GITHUB_RUNNER_PAT` or `GITHUB_RUNNER_TOKEN` (required): Authentication token
-- `GITHUB_RUNNER_NAME` (optional): Runner name (defaults to hostname, can be overridden by GITHUB_RUNNER_USE_HOSTNAME)
-- `GITHUB_RUNNER_USE_HOSTNAME` (optional): Set to "true" to always use container hostname as runner name, overriding GITHUB_RUNNER_NAME
+- `GITHUB_RUNNER_NAME` (optional): Runner name (defaults to hostname). Supports safe environment variable expansion using standard shell syntax
 - `GITHUB_RUNNER_LABELS` (optional): Comma-separated list of labels
 - `GITHUB_RUNNER_GROUP` (optional): Runner group name
 - `GITHUB_RUNNER_WORKDIR` (optional): Working directory for jobs

src/Dockerfile

@@ -8,6 +8,7 @@ RUN apt-get update && \
     apt-get install -y --no-install-recommends \
     wget \
     ca-certificates \
+    gettext-base \
     && rm -rf /var/lib/apt/lists/*
 
 # Install yq with architecture detection

src/entrypoint.sh

@@ -77,55 +77,58 @@ cleanup_runner() {
 # Function to configure runner
 configure_runner() {
     echo "Configuring GitHub Actions runner..."
-    
-    # Build configuration command
-    CONFIG_CMD="./config.sh --url \"${GITHUB_RUNNER_URL}\" --unattended --replace"
-    
+
+    # Build configuration command using array for safety (no eval needed)
+    CONFIG_ARGS=(
+        "--url" "${GITHUB_RUNNER_URL}"
+        "--unattended"
+        "--replace"
+    )
+
     # Add authentication (prefer PAT over TOKEN)
     if [ -n "${GITHUB_RUNNER_PAT}" ]; then
-        CONFIG_CMD="${CONFIG_CMD} --pat \"${GITHUB_RUNNER_PAT}\""
+        CONFIG_ARGS+=("--pat" "${GITHUB_RUNNER_PAT}")
     elif [ -n "${GITHUB_RUNNER_TOKEN}" ]; then
-        CONFIG_CMD="${CONFIG_CMD} --token \"${GITHUB_RUNNER_TOKEN}\""
+        CONFIG_ARGS+=("--token" "${GITHUB_RUNNER_TOKEN}")
     else
         echo "ERROR: Either GITHUB_RUNNER_PAT or GITHUB_RUNNER_TOKEN must be provided"
         exit 1
     fi
-    
-    # Add runner name (with hostname preference option)
-    if [ "${GITHUB_RUNNER_USE_HOSTNAME}" = "true" ]; then
-        # When flag is true, always use hostname regardless of GITHUB_RUNNER_NAME
-        CONFIG_CMD="${CONFIG_CMD} --name \"$(hostname)\""
-    elif [ -n "${GITHUB_RUNNER_NAME}" ]; then
-        # Use provided name if flag is not true and name is provided
-        CONFIG_CMD="${CONFIG_CMD} --name \"${GITHUB_RUNNER_NAME}\""
+
+    # Add runner name (with safe environment variable expansion)
+    if [ -n "${GITHUB_RUNNER_NAME}" ]; then
+        # Safely expand environment variables using envsubst
+        # This prevents code injection while allowing any env var to be used
+        EXPANDED_NAME=$(echo "${GITHUB_RUNNER_NAME}" | envsubst)
+        CONFIG_ARGS+=("--name" "${EXPANDED_NAME}")
     else
-        # Fall back to hostname if no name provided and flag is not true
-        CONFIG_CMD="${CONFIG_CMD} --name \"$(hostname)\""
+        # Fall back to hostname if no name provided
+        CONFIG_ARGS+=("--name" "$(hostname)")
     fi
-    
+
     # Add labels if provided
     if [ -n "${GITHUB_RUNNER_LABELS}" ]; then
-        CONFIG_CMD="${CONFIG_CMD} --labels \"${GITHUB_RUNNER_LABELS}\""
+        CONFIG_ARGS+=("--labels" "${GITHUB_RUNNER_LABELS}")
     fi
-    
+
     # Add runner group if provided
     if [ -n "${GITHUB_RUNNER_GROUP}" ]; then
-        CONFIG_CMD="${CONFIG_CMD} --runnergroup \"${GITHUB_RUNNER_GROUP}\""
+        CONFIG_ARGS+=("--runnergroup" "${GITHUB_RUNNER_GROUP}")
     fi
-    
+
     # Add work directory if provided
     if [ -n "${GITHUB_RUNNER_WORKDIR}" ]; then
-        CONFIG_CMD="${CONFIG_CMD} --work \"${GITHUB_RUNNER_WORKDIR}\""
+        CONFIG_ARGS+=("--work" "${GITHUB_RUNNER_WORKDIR}")
     fi
-    
+
     # Add ephemeral flag if requested
     if [ "${GITHUB_RUNNER_EPHEMERAL}" = "true" ]; then
-        CONFIG_CMD="${CONFIG_CMD} --ephemeral"
+        CONFIG_ARGS+=("--ephemeral")
         echo "Configuring runner in ephemeral mode (will process only one job)"
     fi
-    
-    # Execute configuration
-    eval ${CONFIG_CMD}
+
+    # Execute configuration safely without eval
+    ./config.sh "${CONFIG_ARGS[@]}"
 }
 
 # Function to setup groups