{"id":21905104,"url":"https://github.com/emberstack/github-actions-runner","last_synced_at":"2026-05-13T07:05:44.837Z","repository":{"id":245695859,"uuid":"818950936","full_name":"emberstack/github-actions-runner","owner":"emberstack","description":null,"archived":false,"fork":false,"pushed_at":"2024-06-23T18:12:46.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-01-27T07:28:22.305Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emberstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-23T10:46:54.000Z","updated_at":"2024-06-23T18:12:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"3583fff3-c787-4de5-8a00-a774bf30deb0","html_url":"https://github.com/emberstack/github-actions-runner","commit_stats":null,"previous_names":["emberstack/github-actions-runner-images"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberstack%2Fgithub-actions-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberstack%2Fgithub-actions-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberstack%2Fgithub-actions-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberstack%2Fgithub-actions-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emberstack","download_url":"https://codeload.github.com/emberstack/github-actions-runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244918710,"owners_count":20531686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-28T16:29:24.724Z","updated_at":"2026-05-13T07:05:44.831Z","avatar_url":"https://github.com/emberstack.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Actions Runner Images\n\n[![Docker Hub](https://img.shields.io/docker/pulls/emberstack/github-actions-runner.svg)](https://hub.docker.com/r/emberstack/github-actions-runner)\n[![GitHub Container Registry](https://img.shields.io/badge/ghcr.io-emberstack%2Fgithub--actions--runner-blue)](https://github.com/emberstack/github-actions-runner/pkgs/container/github-actions-runner)\n[![License](https://img.shields.io/github/license/emberstack/github-actions-runner)](LICENSE)\n\n## Overview\n\nThis repository provides enhanced Docker images for GitHub Actions self-hosted runners with a comprehensive suite of pre-installed development and operations tools. Built on top of the official GitHub Actions runner base image, it includes essential tools for CI/CD workflows, making it ideal for enterprise and development environments.\n\n### Key Features\n- 🚀 Based on official [GitHub Actions runner](https://github.com/actions/runner) image\n- 🏗️ Multi-architecture support (AMD64 and ARM64)\n- 📦 Comprehensive tool suite pre-installed\n- 🔧 YAML-driven installation system for easy customization\n- 🎯 Automated CI/CD pipeline with semantic versioning\n- 🐳 Published to both Docker Hub and GitHub Container Registry\n\n## Quick Start\n\n### Pull from Docker Hub\n```bash\ndocker pull emberstack/github-actions-runner:latest\n```\n\n### Pull from GitHub Container Registry\n```bash\ndocker pull ghcr.io/emberstack/github-actions-runner:latest\n```\n\n### Run as GitHub Actions Runner\n\n#### Using Personal Access Token (PAT)\n```bash\ndocker run -d \\\n  --name github-runner \\\n  -e GITHUB_RUNNER_URL=\"https://github.com/your-org/your-repo\" \\\n  -e GITHUB_RUNNER_PAT=\"your-personal-access-token\" \\\n  -e GITHUB_RUNNER_NAME=\"my-runner\" \\\n  -e GITHUB_RUNNER_LABELS=\"docker,linux\" \\\n  emberstack/github-actions-runner:latest\n```\n\n#### Using Registration Token\n```bash\ndocker run -d \\\n  --name github-runner \\\n  -e GITHUB_RUNNER_URL=\"https://github.com/your-org/your-repo\" \\\n  -e GITHUB_RUNNER_TOKEN=\"your-registration-token\" \\\n  -e GITHUB_RUNNER_NAME=\"my-runner\" \\\n  emberstack/github-actions-runner:latest\n```\n\n#### With Docker Socket Access\n```bash\ndocker run -d \\\n  --name github-runner \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -e GITHUB_RUNNER_URL=\"https://github.com/your-org/your-repo\" \\\n  -e GITHUB_RUNNER_PAT=\"your-personal-access-token\" \\\n  -e GITHUB_RUNNER_DOCKER_SOCK=\"true\" \\\n  emberstack/github-actions-runner:latest\n```\n\n#### With Custom GID\n```bash\ndocker run -d \\\n  --name github-runner \\\n  -e GITHUB_RUNNER_URL=\"https://github.com/your-org/your-repo\" \\\n  -e GITHUB_RUNNER_PAT=\"your-personal-access-token\" \\\n  -e GITHUB_RUNNER_GID=\"1001\" \\\n  emberstack/github-actions-runner:latest\n```\n\n#### Ephemeral Mode (Single Job)\n```bash\ndocker run -d \\\n  --name github-runner \\\n  -e GITHUB_RUNNER_URL=\"https://github.com/your-org/your-repo\" \\\n  -e GITHUB_RUNNER_PAT=\"your-personal-access-token\" \\\n  -e GITHUB_RUNNER_EPHEMERAL=\"true\" \\\n  emberstack/github-actions-runner:latest\n```\n\n#### Dynamic Runner Naming with Environment Variables\nThe `GITHUB_RUNNER_NAME` supports safe environment variable expansion, allowing dynamic runner names based on any runtime environment variable:\n\n```bash\n# Use container hostname (container ID in Docker)\ndocker run -d \\\n  --name github-runner \\\n  -e GITHUB_RUNNER_URL=\"https://github.com/your-org/your-repo\" \\\n  -e GITHUB_RUNNER_PAT=\"your-personal-access-token\" \\\n  -e GITHUB_RUNNER_NAME='$HOSTNAME' \\\n  emberstack/github-actions-runner:latest\n\n# Combine with prefix/suffix\ndocker run -d \\\n  --name github-runner \\\n  -e GITHUB_RUNNER_URL=\"https://github.com/your-org/your-repo\" \\\n  -e GITHUB_RUNNER_PAT=\"your-personal-access-token\" \\\n  -e GITHUB_RUNNER_NAME='runner-$HOSTNAME' \\\n  emberstack/github-actions-runner:latest\n\n# Use in Docker Compose with custom hostname\nservices:\n  runner:\n    image: emberstack/github-actions-runner:latest\n    hostname: worker-node-1\n    environment:\n      GITHUB_RUNNER_URL: \"https://github.com/your-org/your-repo\"\n      GITHUB_RUNNER_PAT: \"your-personal-access-token\"\n      GITHUB_RUNNER_NAME: 'runner-$HOSTNAME'  # Will be \"runner-worker-node-1\"\n```\n\n**Examples of Supported Variables:**\n- `$HOSTNAME` or `${HOSTNAME}` - The container's hostname (container ID by default in Docker)\n- `$USER` or `${USER}` - The current user (typically \"runner\")\n- `$HOME` or `${HOME}` - The user's home directory\n- `$PATH` - System PATH\n- Any custom environment variable you define\n\n**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.\n\nIn ephemeral mode, the runner will:\n- Process only one job and then automatically deregister\n- Provide a clean, isolated environment for each workflow run\n- Be ideal for autoscaling scenarios and enhanced security\n- Ensure no job state or secrets persist between runs\n\n#### Environment Variables\n- `GITHUB_RUNNER_URL` (required): Repository, organization, or enterprise URL\n- `GITHUB_RUNNER_PAT` or `GITHUB_RUNNER_TOKEN` (required): Authentication token\n- `GITHUB_RUNNER_NAME` (optional): Runner name (defaults to hostname). Supports safe environment variable expansion using standard shell syntax\n- `GITHUB_RUNNER_LABELS` (optional): Comma-separated list of labels\n- `GITHUB_RUNNER_GROUP` (optional): Runner group name\n- `GITHUB_RUNNER_WORKDIR` (optional): Working directory for jobs\n- `GITHUB_RUNNER_GID` (optional): Custom GID to create github-actions-runner group\n- `GITHUB_RUNNER_DOCKER_SOCK` (optional): Set to \"true\" to auto-configure Docker socket access\n- `GITHUB_RUNNER_DOCKER_SOCK_GID` (optional): Explicit GID for Docker socket group (overrides auto-detection when socket exists)\n- `GITHUB_RUNNER_EPHEMERAL` (optional): Set to \"true\" to configure runner in ephemeral mode (single job only)\n\n##### Pre-configured Environment Variables\nThe following environment variables are set in the Docker image:\n- `DOTNET_INSTALL_DIR`: Set to `/home/runner/.dotnet` to avoid permission issues when using actions/setup-dotnet\n\n#### Graceful Shutdown\nThe container handles shutdown signals (SIGTERM, SIGINT) gracefully:\n- Stops the running job (if any)\n- Removes the runner registration from GitHub\n- Ensures clean termination\n\nThis automatic cleanup prevents orphaned runner registrations when containers are stopped.\n\n## Included Software\n\n### Pre-installed in Base Image\nThe following tools are already available in the GitHub Actions runner base image:\n- **Python 3** - Python interpreter\n- **Git** - Version control system\n- **Docker** with **Docker Buildx** - Container platform\n- **jq** - JSON processor\n- **curl** - Data transfer tool\n- **SSH/SCP** - Secure shell and copy\n- **tar** - Archive utility\n- **unzip** - ZIP extraction\n- **sudo** - Privilege escalation\n- **Core Unix tools** - find, grep, sed, awk, perl, etc.\n- **GNU Coreutils** - Essential Unix utilities (ls, cp, mv, cat, etc.)\n\n### File Utilities\n- **file** - File type identification\n- **findutils** - Find files and directories\n- **tree** - Directory tree visualization\n- **time** - Time command execution\n\n### Programming Languages \u0026 Runtimes\n- **PowerShell Core** - Cross-platform PowerShell\n\n### Cloud \u0026 Infrastructure Tools\n- **Azure CLI** - Azure cloud management\n- **AzCopy** - Azure Storage data transfer (latest release)\n\n### Container Tools\n- **Docker Compose Plugin** - Multi-container orchestration (latest)\n- **Docker Buildx** - Advanced Docker builds (pre-installed in base image)\n\n### Development Tools\n- **Git** - Version control (pre-installed in base image)\n- **GitHub CLI** (`gh`) - GitHub operations (latest)\n- **jq** - JSON processor (pre-installed in base image)\n- **yq** - YAML processor (latest)\n- **yamllint** - YAML linter (latest from pip)\n\n### Archive \u0026 Compression Tools\n- **tar** - Tape archive utility (pre-installed in base image)\n- **unzip** - ZIP decompression (pre-installed in base image)\n- **zip** - ZIP compression\n- **p7zip-full** (7z) - 7-Zip archiver\n\n### Network Tools\n- **DNS Utilities**\n  - `dig` - DNS lookup\n  - `nslookup` - Query DNS servers\n  - `nsupdate` - Dynamic DNS updates\n- **IP Utilities**\n  - `ping` - Network connectivity test\n  - `tracepath` - Network path discovery\n  - `arping` - ARP level ping\n  - `ip` - Show/manipulate routing, network devices\n  - `ss` - Socket statistics\n- **Legacy Network Tools**\n  - `ifconfig` - Network interface configuration\n  - `netstat` - Network statistics\n  - `route` - Routing table manipulation\n- **Connection Tools**\n  - `ssh` - Secure Shell client (pre-installed in base image)\n  - `scp` - Secure copy (pre-installed in base image)\n  - `ftp` - File Transfer Protocol client\n  - `telnet` - Telnet client\n  - `netcat` (`nc`) - Network debugging\n  - `sshpass` - Non-interactive SSH authentication\n\n## Architecture\n\n### Build System\nThe image uses a YAML-driven installation system:\n- `src/setup.yaml` - Defines installation steps\n- `src/setup.sh` - Orchestrates the installation process\n- `src/scripts/` - Individual installation scripts for each tool group\n\n### Multi-Architecture Support\n- Automatic architecture detection during build\n- Platform-specific binaries for AMD64 and ARM64\n- Unified multi-arch manifests in registries\n\n## Building Locally\n\n### Prerequisites\n- Docker or Docker Desktop\n- Docker Buildx (for multi-platform builds)\n\n### Build for Current Platform\n```bash\ndocker build -t github-actions-runner -f src/Dockerfile src/\n```\n\n### Build for Specific Platform\n```bash\ndocker buildx build --platform linux/amd64 -t github-actions-runner -f src/Dockerfile src/\n```\n\n### Build Multi-Platform\n```bash\ndocker buildx build --platform linux/amd64,linux/arm64 -t github-actions-runner -f src/Dockerfile src/\n```\n\n## Customization\n\n### Adding New Tools\n\n1. Create an installation script in `src/scripts/`:\n```bash\n#!/bin/bash\n# src/scripts/install-newtool.sh\napt-get update\napt-get install -y newtool\n# Add verification\nif ! command -v newtool \u0026\u003e /dev/null; then\n    echo \"ERROR: newtool installation failed\"\n    exit 1\nfi\n```\n\n2. Add to `src/setup.yaml`:\n```yaml\n- name: \"Install New Tool\"\n  script: \"scripts/install-newtool.sh\"\n  description: \"Description of the tool\"\n```\n\n3. Make the script executable:\n```bash\nchmod +x src/scripts/install-newtool.sh\n```\n\n## CI/CD Pipeline\n\nThe repository uses GitHub Actions for automated building and releasing:\n\n- **Automatic Builds**: Triggered on push to any branch\n- **Multi-Architecture Builds**: Parallel builds for AMD64 and ARM64\n- **Semantic Versioning**: Using GitVersion\n- **Container Registries**: Publishes to Docker Hub and GitHub Container Registry\n- **Release Management**: Automatic GitHub releases on main branch\n\n### Version Control\n- Commit messages control version bumps:\n  - `feat:` - Minor version bump\n  - `fix:` - Patch version bump\n  - `feat!:` or `+semver:major` - Major version bump\n\n## Repository Structure\n```\n├── .github/\n│   └── workflows/\n│       └── pipeline.yaml      # CI/CD pipeline\n├── src/\n│   ├── Dockerfile            # Main Docker image definition\n│   ├── setup.yaml           # Tool installation configuration\n│   ├── setup.sh            # Installation orchestrator\n│   └── scripts/            # Individual tool installation scripts\n├── GitVersion.yaml         # Semantic versioning configuration\n├── LICENSE                # Repository license\n├── README.md             # This file\n└── CLAUDE.md            # AI assistant guidance\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n### Development Guidelines\n1. Follow the existing script patterns\n2. Ensure tools work on both AMD64 and ARM64\n3. Add verification steps in installation scripts\n4. Update documentation for new tools\n5. Test builds locally before submitting PR\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- 🐛 [Report Issues](https://github.com/emberstack/github-actions-runner/issues)\n- 💬 [Discussions](https://github.com/emberstack/github-actions-runner/discussions)\n\n## Acknowledgments\n\n- Built on top of [actions/runner](https://github.com/actions/runner) official images\n- Inspired by the need for comprehensive CI/CD environments\n- Thanks to all contributors and the open-source community\n\n## Note on Development Tools\n\nWhile 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:\n\n### Languages \u0026 Runtimes\n- **Python/pip**: Use [`actions/setup-python`](https://github.com/actions/setup-python) - includes pip by default\n- **Node.js**: Use [`actions/setup-node`](https://github.com/actions/setup-node)\n- **.NET SDK**: Use [`actions/setup-dotnet`](https://github.com/actions/setup-dotnet)\n\n### Infrastructure Tools\n- **kubectl**: Use [`azure/setup-kubectl`](https://github.com/azure/setup-kubectl)\n- **Helm**: Use [`azure/setup-helm`](https://github.com/azure/setup-helm)\n- **Kustomize**: Use [`imranismail/setup-kustomize`](https://github.com/imranismail/setup-kustomize)\n- **Ansible**: Install via pip after setting up Python\n\nThese actions provide better caching, version management, and are optimized for CI/CD environments.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femberstack%2Fgithub-actions-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femberstack%2Fgithub-actions-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femberstack%2Fgithub-actions-runner/lists"}