{"id":40677483,"url":"https://github.com/vikshrogit/bullos-runner","last_synced_at":"2026-01-21T10:03:37.208Z","repository":{"id":315357489,"uuid":"1059057291","full_name":"vikshrogit/bullos-runner","owner":"vikshrogit","description":"Github Selfhosted Runner with Ubuntu Based os can use for organisation need docker or k8s runner.","archived":false,"fork":false,"pushed_at":"2025-10-30T16:24:08.000Z","size":70,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T18:08:16.735Z","etag":null,"topics":["bullos","custom","github","runner","ubuntu","vikshro"],"latest_commit_sha":null,"homepage":"https://bullos.vikshro.in","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vikshrogit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-18T00:01:22.000Z","updated_at":"2025-10-30T16:04:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"c46747c0-9235-42f2-bb2e-6f5dc1af1c26","html_url":"https://github.com/vikshrogit/bullos-runner","commit_stats":null,"previous_names":["vikshrogit/bullos-runner"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/vikshrogit/bullos-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikshrogit%2Fbullos-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikshrogit%2Fbullos-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikshrogit%2Fbullos-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikshrogit%2Fbullos-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vikshrogit","download_url":"https://codeload.github.com/vikshrogit/bullos-runner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikshrogit%2Fbullos-runner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28631936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["bullos","custom","github","runner","ubuntu","vikshro"],"created_at":"2026-01-21T10:03:36.497Z","updated_at":"2026-01-21T10:03:37.201Z","avatar_url":"https://github.com/vikshrogit.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BullOS GitHub Self-Hosted Runner\r\n\r\nWelcome to **BullOS GitHub Self-Hosted Runner**, a robust, secure, and scalable solution for running GitHub Actions workflows on your own infrastructure. This repository provides everything you need to deploy multi-architecture (amd64 and arm64) GitHub runners inside Docker containers, complete with automation, security best practices, and production-grade deployment guidelines.\r\n\r\n---\r\n\r\n## 🚀 Overview\r\n\r\nGitHub Actions is a powerful CI/CD platform, but GitHub-hosted runners can be limited in flexibility, performance, and control. BullOS GitHub Runner solves this problem by giving you **self-hosted runners** that:\r\n\r\n- Run inside Docker containers for isolation and reproducibility.\r\n- Support **multi-architecture builds** (`amd64` and `arm64`).\r\n- Auto-register with your GitHub repository or organization.\r\n- Scale horizontally to handle concurrent workloads.\r\n- Integrate seamlessly with GitHub Actions workflows.\r\n- Provide enhanced security with controlled execution environments.\r\n\r\nBy running BullOS runners on your own servers, you can reduce costs, improve performance, and maintain full control over your workflows.\r\n\r\n---\r\n\r\n## ✨ Features\r\n\r\n- **Multi-Arch Support**: Build and deploy runners for both `linux/amd64` and `linux/arm64`.\r\n- **Ephemeral Runners**: Optionally enable short-lived runners that self-destruct after jobs finish.\r\n- **Docker-Compose Ready**: Easy setup with `.env` configuration.\r\n- **Secure by Default**: Runs with limited permissions, integrates with Trivy for vulnerability scanning.\r\n- **Scalable**: Deploy multiple containers across servers for concurrency.\r\n- **Customizable**: Configure runner groups, labels, work directories, and debug options.\r\n- **CI/CD Friendly**: Build, scan, and push images via GitHub Actions.\r\n\r\n---\r\n\r\n## 🏗️ Architecture\r\n\r\nAt a high level, BullOS Runner works like this:\r\n\r\n1. The container launches and pulls the latest version of the GitHub Actions runner binary.\r\n2. It registers itself with your GitHub repository or organization using a token.\r\n3. The runner listens for jobs from GitHub Actions.\r\n4. Jobs are executed inside the container environment.\r\n5. When configured as **ephemeral**, the runner automatically de-registers and cleans up after completion.\r\n\r\nThe architecture ensures **isolation**, **clean builds**, and **repeatability**.\r\n\r\n---\r\n\r\n## ⚙️ Installation\r\n\r\n### 1. Clone Repository\r\n```bash\r\ngit clone https://github.com/vikshrogit/bullos-runner.git\r\ncd bullos-runner\r\n````\r\n\r\n### 2. Create `.env` File\r\n\r\n```env\r\nGITHUB_URL=https://github.com/vikshrogit\r\nRUNNER_TOKEN=your-github-token-here\r\nRUNNER_NAME=bullos-runner-01\r\nRUNNER_LABELS=self-hosted,linux,bullos\r\nRUNNER_WORKDIR=_work\r\nRUNNER_EPHEMERAL=false\r\nRUNNER_RUNNERGROUP=Default\r\nRUNNER_DEBUG=true\r\nRUNNER_CONCURRENCY=4\r\n```\r\n\r\n### 3. Run with Docker Compose\r\n\r\n```bash\r\ndocker compose up -d\r\n```\r\n\r\n### 4. Verify Runner Registration\r\n\r\nGo to your GitHub repository or organization:\r\n\r\n* **Settings → Actions → Runners**\r\n  You should see `bullos-runner-01` listed.\r\n\r\n---\r\n\r\n## 🐳 Docker Images\r\n\r\nThe official container image is hosted at:\r\n\r\n```\r\nghcr.io/vikshrogit/bullos-gh-runner:latest\r\n```\r\n\r\nYou can pull it directly:\r\n\r\n```bash\r\ndocker pull ghcr.io/vikshrogit/bullos-gh-runner:latest\r\n```\r\n\r\n---\r\n\r\n## 🔧 Configuration Options\r\n\r\n| Variable             | Description                                           |\r\n| -------------------- | ----------------------------------------------------- |\r\n| `GITHUB_URL`         | The GitHub repository or organization URL.            |\r\n| `RUNNER_TOKEN`       | Registration token (from GitHub settings).            |\r\n| `RUNNER_NAME`        | Friendly name for the runner.                         |\r\n| `RUNNER_LABELS`      | Comma-separated labels for targeting jobs.            |\r\n| `RUNNER_WORKDIR`     | Directory where jobs execute.                         |\r\n| `RUNNER_EPHEMERAL`   | `true` or `false`. Ephemeral runners exit after jobs. |\r\n| `RUNNER_RUNNERGROUP` | Runner group name.                                    |\r\n| `RUNNER_DEBUG`       | Enable verbose logging.                               |\r\n| `RUNNER_CONCURRENCY` | Number of jobs the runner can handle concurrently.    |\r\n\r\n---\r\n\r\n## 🔐 Security Best Practices\r\n\r\n1. Always keep your Docker image updated with the latest version.\r\n2. Use **ephemeral runners** for untrusted workflows.\r\n3. Regularly scan images with **Trivy**:\r\n\r\n   ```bash\r\n   trivy image ghcr.io/vikshrogit/bullos-gh-runner:latest\r\n   ```\r\n4. Run containers with limited privileges (`--security-opt no-new-privileges`).\r\n5. Rotate your `RUNNER_TOKEN` periodically.\r\n6. Use dedicated infrastructure for sensitive workflows.\r\n\r\n---\r\n\r\n## 🛡️ Trivy Integration\r\n\r\nBullOS Runner integrates with **Trivy** in CI/CD pipelines:\r\n\r\n* **Vulnerability scanning** (OS packages, dependencies).\r\n* **Secret scanning** (to avoid committing secrets).\r\n* Configurable exit codes (`--exit-code 1` on critical findings).\r\n\r\n---\r\n\r\n## 🧩 Advanced Usage\r\n\r\n### Multi-Runner Deployment\r\n\r\nYou can run multiple runners by scaling with Docker Compose:\r\n\r\n```bash\r\ndocker compose up --scale runner=3 -d\r\n```\r\n\r\n### Ephemeral Mode\r\n\r\nSet in `.env`:\r\n\r\n```env\r\nRUNNER_EPHEMERAL=true\r\n```\r\n\r\nThis ensures clean, isolated runners for every workflow.\r\n\r\n### Custom Labels\r\n\r\n```env\r\nRUNNER_LABELS=self-hosted,linux,build,deploy\r\n```\r\n\r\nTarget specific jobs with these labels.\r\n\r\n---\r\n\r\n## 🛠️ Development\r\n\r\nTo build locally:\r\n\r\n```bash\r\ndocker buildx build --platform linux/amd64,linux/arm64 -t bullos-runner:test .\r\n```\r\n\r\nRun locally:\r\n\r\n```bash\r\ndocker run --rm -it bullos-runner:test bash\r\n```\r\n\r\n---\r\n\r\n## ❓ Troubleshooting\r\n\r\n* **Runner not appearing in GitHub**\r\n  → Check if the `RUNNER_TOKEN` is valid. Tokens expire quickly.\r\n* **Image fails to build**\r\n  → Make sure you’re using `docker buildx` with experimental features enabled.\r\n* **Architecture mismatch**\r\n  → Ensure you specify `--platform linux/amd64,linux/arm64` for multi-arch builds.\r\n* **Trivy OOM errors**\r\n  → Use `--scanners vuln` to disable secret scanning.\r\n\r\n---\r\n\r\n## 📚 FAQ\r\n\r\n**Q: Why use BullOS runner instead of GitHub-hosted runners?**\r\nA: Control, cost efficiency, custom environments, and support for private infrastructure.\r\n\r\n**Q: Can I use this in Kubernetes?**\r\nA: Yes! Wrap the container into a `Deployment` or `DaemonSet` for cluster-wide runners.\r\n\r\n**Q: Is it secure to run untrusted workflows?**\r\nA: Use **ephemeral mode** + restricted nodes for maximum safety.\r\n\r\n**Q: How often are images updated?**\r\nA: Images are built automatically on new GitHub runner releases.\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome!\r\n\r\n1. Fork the repository.\r\n2. Create a new branch.\r\n3. Make your changes.\r\n4. Submit a Pull Request.\r\n\r\nWe follow our [Code of Conduct](CODE_OF_CONDUCT.md).\r\n\r\n---\r\n\r\n## 📜 License\r\n\r\nThis project is licensed under the terms of the [Apache License 2.0](LICENSE.md).\r\n\r\n---\r\n\r\n## 📈 Roadmap\r\n\r\n* [ ] Add Kubernetes Helm Chart support\r\n* [ ] Enhanced monitoring with Prometheus/Grafana\r\n* [ ] Auto-scaling runner pools\r\n* [ ] Support for Windows-based runners\r\n\r\n---\r\n\r\n## 🌍 Community\r\n\r\n* **Discussions**: [GitHub Discussions](https://github.com/vikshrogit/bullos-runner/discussions)\r\n* **Issues**: [Issue Tracker](https://github.com/vikshrogit/bullos-runner/issues)\r\n\r\nJoin us to make CI/CD faster, more secure, and fully under your control!\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvikshrogit%2Fbullos-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvikshrogit%2Fbullos-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvikshrogit%2Fbullos-runner/lists"}