feat(docker): enhance GitHub Actions runner configuration

- Adds new Docker command options for GitHub Actions runners to improve flexibility and usability.
- Introduces an entrypoint script for setup, cleanup, and configuration of runners.
- Archives old installation scripts in favor of official GitHub Actions setup actions for better management and version handling.

Improves environment variable documentation for better clarity on required configurations.

Author: winromulus

.claude/settings.local.json

@@ -12,7 +12,11 @@
       "Bash(mv:*)",
       "WebFetch(domain:learn.microsoft.com)",
       "Bash(find:*)",
-      "Bash(chmod:*)"
+      "Bash(chmod:*)",
+      "Bash(docker logs:*)",
+      "Bash(docker exec:*)",
+      "Bash(docker stop:*)",
+      "Bash(docker rm:*)"
     ],
     "deny": []
   }

README.md

@@ -29,15 +29,59 @@ docker pull ghcr.io/emberstack/github-actions-runner:latest
 ```
 
 ### Run as GitHub Actions Runner
+
+#### Using Personal Access Token (PAT)
 ```bash
 docker run -d \
   --name github-runner \
-  -e RUNNER_NAME="my-runner" \
-  -e GITHUB_TOKEN="your-github-token" \
-  -e RUNNER_REPOSITORY_URL="https://github.com/your-org/your-repo" \
+  -e GITHUB_RUNNER_URL="https://github.com/your-org/your-repo" \
+  -e GITHUB_RUNNER_PAT="your-personal-access-token" \
+  -e GITHUB_RUNNER_NAME="my-runner" \
+  -e GITHUB_RUNNER_LABELS="docker,linux" \
   emberstack/github-actions-runner:latest
 ```
 
+#### Using Registration Token
+```bash
+docker run -d \
+  --name github-runner \
+  -e GITHUB_RUNNER_URL="https://github.com/your-org/your-repo" \
+  -e GITHUB_RUNNER_TOKEN="your-registration-token" \
+  -e GITHUB_RUNNER_NAME="my-runner" \
+  emberstack/github-actions-runner:latest
+```
+
+#### With Docker Socket Access
+```bash
+docker run -d \
+  --name github-runner \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -e GITHUB_RUNNER_URL="https://github.com/your-org/your-repo" \
+  -e GITHUB_RUNNER_PAT="your-personal-access-token" \
+  -e GITHUB_RUNNER_DOCKER_SOCK="true" \
+  emberstack/github-actions-runner:latest
+```
+
+#### With Custom GID
+```bash
+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_GID="1001" \
+  emberstack/github-actions-runner:latest
+```
+
+#### 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)
+- `GITHUB_RUNNER_LABELS` (optional): Comma-separated list of labels
+- `GITHUB_RUNNER_GROUP` (optional): Runner group name
+- `GITHUB_RUNNER_WORKDIR` (optional): Working directory for jobs
+- `GITHUB_RUNNER_GID` (optional): Custom GID to create github-actions-runner group
+- `GITHUB_RUNNER_DOCKER_SOCK` (optional): Set to "true" to auto-configure Docker socket access
+
 ## Included Software
 
 ### Pre-installed in Base Image
@@ -61,13 +105,11 @@ The following tools are already available in the GitHub Actions runner base imag
 - **time** - Time command execution
 
 ### Programming Languages & Runtimes
-- **Python 3** with pip - Python interpreter and package manager
 - **PowerShell Core** - Cross-platform PowerShell
 
 ### Cloud & Infrastructure Tools
 - **Azure CLI** - Azure cloud management
 - **AzCopy** - Azure Storage data transfer (latest release)
-- **Ansible** - Infrastructure automation (latest from pip)
 
 ### Container Tools
 - **Docker Compose Plugin** - Multi-container orchestration (latest)
@@ -230,14 +272,19 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - Inspired by the need for comprehensive CI/CD environments
 - Thanks to all contributors and the open-source community
 
-## Note on .NET SDK, Node.js, and Kubernetes Tools
+## Note on Development Tools
 
-While installation scripts for these tools are available in the `src/_archive/scripts/` directory, we recommend using GitHub Actions' official setup actions or marketplace actions in your workflows:
+While installation scripts for various development tools are available in the `src/_archive/scripts/` directory, we recommend using GitHub Actions' official setup actions or marketplace actions in your workflows:
 
+### Languages & Runtimes
+- **Python/pip**: Use [`actions/setup-python`](https://github.com/actions/setup-python) - includes pip by default
 - **Node.js**: Use [`actions/setup-node`](https://github.com/actions/setup-node)
 - **.NET SDK**: Use [`actions/setup-dotnet`](https://github.com/actions/setup-dotnet)
+
+### Infrastructure Tools
 - **kubectl**: Use [`azure/setup-kubectl`](https://github.com/azure/setup-kubectl)
 - **Helm**: Use [`azure/setup-helm`](https://github.com/azure/setup-helm)
 - **Kustomize**: Use [`imranismail/setup-kustomize`](https://github.com/imranismail/setup-kustomize)
+- **Ansible**: Install via pip after setting up Python
 
 These actions provide better caching, version management, and are optimized for CI/CD environments.

src/Dockerfile

@@ -25,4 +25,15 @@ COPY setup.sh /
 # Run setup script with proper error handling
 RUN bash -e /setup.sh
 
-USER runner
+# Copy entrypoint script
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Switch back to runner user
+USER runner
+
+# Set working directory
+WORKDIR /home/runner
+
+# Set entrypoint
+ENTRYPOINT ["/entrypoint.sh"]

src/_archive/README.md

@@ -4,6 +4,10 @@ This directory contains installation scripts that have been archived in favor of
 
 ## Archived Scripts
 
+### Python/pip Installation (`scripts/install-python.sh`)
+- **Replaced by**: [`actions/setup-python`](https://github.com/actions/setup-python)
+- **Reason**: The official action includes pip by default and provides Python version management
+
 ### Node.js Installation (`scripts/install-nodejs.sh`)
 - **Replaced by**: [`actions/setup-node`](https://github.com/actions/setup-node)
 - **Reason**: The official action provides better caching, version management, and is optimized for CI/CD
@@ -19,6 +23,10 @@ This directory contains installation scripts that have been archived in favor of
   - Kustomize: [`imranismail/setup-kustomize`](https://github.com/imranismail/setup-kustomize)
 - **Reason**: These actions provide version management, caching, and are maintained by the community
 
+### Ansible Installation (`scripts/install-ansible.sh`)
+- **Replaced by**: pip install after `actions/setup-python`
+- **Reason**: Ansible is a Python package best installed via pip in workflows
+
 ## Usage
 
 These scripts are preserved for reference and can still be used if you need to install these tools directly in the Docker image. However, for GitHub Actions workflows, we recommend using the official setup actions.
@@ -51,4 +59,15 @@ steps:
     uses: azure/setup-helm@v4
     with:
       version: 'latest'
+      
+  - name: Setup Python
+    uses: actions/setup-python@v5
+    with:
+      python-version: '3.x'
+      cache: 'pip'
+      
+  - name: Install Ansible
+    run: |
+      python -m pip install --upgrade pip
+      pip install ansible
 ```

src/scripts/install-ansible.sh renamed to src/_archive/scripts/install-ansible.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+set -e
+
+# Switch to runner user home directory
+cd /home/runner
+
+# Function to handle runner cleanup
+cleanup_runner() {
+    echo "Attempting to remove existing runner configuration..."
+    if [ -n "${GITHUB_RUNNER_PAT}" ]; then
+        ./config.sh remove --pat "${GITHUB_RUNNER_PAT}" || true
+    elif [ -n "${GITHUB_RUNNER_TOKEN}" ]; then
+        ./config.sh remove --token "${GITHUB_RUNNER_TOKEN}" || true
+    else
+        echo "No PAT or TOKEN provided for runner removal, skipping cleanup"
+    fi
+}
+
+# Function to configure runner
+configure_runner() {
+    echo "Configuring GitHub Actions runner..."
+    
+    # Build configuration command
+    CONFIG_CMD="./config.sh --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}\""
+    elif [ -n "${GITHUB_RUNNER_TOKEN}" ]; then
+        CONFIG_CMD="${CONFIG_CMD} --token \"${GITHUB_RUNNER_TOKEN}\""
+    else
+        echo "ERROR: Either GITHUB_RUNNER_PAT or GITHUB_RUNNER_TOKEN must be provided"
+        exit 1
+    fi
+    
+    # Add runner name (use hostname as default)
+    if [ -n "${GITHUB_RUNNER_NAME}" ]; then
+        CONFIG_CMD="${CONFIG_CMD} --name \"${GITHUB_RUNNER_NAME}\""
+    else
+        CONFIG_CMD="${CONFIG_CMD} --name \"$(hostname)\""
+    fi
+    
+    # Add labels if provided
+    if [ -n "${GITHUB_RUNNER_LABELS}" ]; then
+        CONFIG_CMD="${CONFIG_CMD} --labels \"${GITHUB_RUNNER_LABELS}\""
+    fi
+    
+    # Add runner group if provided
+    if [ -n "${GITHUB_RUNNER_GROUP}" ]; then
+        CONFIG_CMD="${CONFIG_CMD} --runnergroup \"${GITHUB_RUNNER_GROUP}\""
+    fi
+    
+    # Add work directory if provided
+    if [ -n "${GITHUB_RUNNER_WORKDIR}" ]; then
+        CONFIG_CMD="${CONFIG_CMD} --work \"${GITHUB_RUNNER_WORKDIR}\""
+    fi
+    
+    # Execute configuration
+    eval ${CONFIG_CMD}
+}
+
+# Function to setup groups
+setup_groups() {
+    # Handle custom GID if specified
+    if [ -n "${GITHUB_RUNNER_GID}" ]; then
+        echo "Creating github-actions-runner group with GID ${GITHUB_RUNNER_GID}..."
+        sudo groupadd -f -g ${GITHUB_RUNNER_GID} github-actions-runner || true
+        sudo usermod -aG github-actions-runner runner
+        echo "Added runner user to github-actions-runner group"
+    fi
+    
+    # Handle Docker socket access if requested
+    if [ "${GITHUB_RUNNER_DOCKER_SOCK}" = "true" ]; then
+        if [ -S /var/run/docker.sock ]; then
+            DOCKER_GID=$(stat -c '%g' /var/run/docker.sock)
+            echo "Docker socket detected with GID ${DOCKER_GID}"
+            echo "Creating github-actions-runner-dockersock group..."
+            sudo groupadd -f -g ${DOCKER_GID} github-actions-runner-dockersock || true
+            sudo usermod -aG github-actions-runner-dockersock runner
+            echo "Added runner user to github-actions-runner-dockersock group"
+        else
+            echo "WARNING: GITHUB_RUNNER_DOCKER_SOCK=true but /var/run/docker.sock not found"
+        fi
+    fi
+}
+
+# Main execution
+main() {
+    # Validate required environment variables
+    if [ -z "${GITHUB_RUNNER_URL}" ]; then
+        echo "ERROR: GITHUB_RUNNER_URL environment variable is required"
+        echo "Example: https://github.com/myorg/myrepo"
+        exit 1
+    fi
+    
+    # Setup groups if needed
+    setup_groups
+    
+    # Cleanup any existing runner configuration
+    cleanup_runner
+    
+    # Configure the runner
+    configure_runner
+    
+    # Start the runner
+    echo "Starting GitHub Actions runner..."
+    exec ./run.sh
+}
+
+# Execute main function
+main

src/scripts/install-python.sh renamed to src/_archive/scripts/install-python.sh

@@ -11,10 +11,6 @@ setup:
       script: "scripts/install-archive-tools.sh"
       description: "Installs compression and archive tools (p7zip, zip)"
 
-    - name: "Install Python and pip"
-      script: "scripts/install-python.sh"
-      description: "Installs pip and Python dev tools (Python3 is pre-installed)"
-      
     - name: "Install PowerShell"
       script: "scripts/install-powershell.sh"
       description: "Installs PowerShell Core"
@@ -27,18 +23,10 @@ setup:
       script: "scripts/install-azcopy.sh"
       description: "Installs AzCopy for Azure Storage"
 
-    - name: "Install Ansible"
-      script: "scripts/install-ansible.sh"
-      description: "Installs Ansible using pip"
-      
     - name: "Install Docker tools"
       script: "scripts/install-docker-tools.sh"
       description: "Installs Docker Compose plugin"
 
-    - name: "Install yamllint"
-      script: "scripts/install-yamllint.sh"
-      description: "Installs yamllint for YAML validation"
-      
     - name: "Install GitHub CLI"
       script: "scripts/install-github-cli.sh"
       description: "Installs GitHub CLI (gh)"