README
¶
Supercharged GitHub Actions Runners
Run GitHub Actions on your own hardware — fast, secure, and fully isolated.
Visit Website • Report Issue • Discussions
⚠️ This project is under heavy development. The API, configuration, and behavior may change significantly. Use at your own risk and expect breaking changes between releases.
🚀 What Is CIHub?
CIHub is an open-source, self-hosted GitHub Actions runner orchestrator that delivers enterprise-grade isolation, speed, and control.
Unlike traditional shared runners, CIHub launches dedicated micro-VMs (using Firecracker) for each workflow job — ensuring complete isolation, predictable performance, and security.
Perfect for teams that need:
- 🔒 Security-first CI/CD – Each job runs in its own sandboxed environment
- ⚡ Predictable performance – No resource contention between jobs
- 💰 Cost efficiency – Run CI on your own infrastructure instead of paying per-minute
- 🎛️ Complete control – Full visibility and customization of your CI environment
✨ Key Features
🔐 Isolation by Design
Every job runs in its own ephemeral Firecracker micro-VM. No shared state, no side effects — just a clean sandbox.
🏃 Lightning-Fast Execution
Micro-VMs start in milliseconds. Combined with your hardware, jobs run significantly faster than cloud runners.
🔌 Zero-Friction Integration
Drop-in replacement for GitHub Actions runners. Use standard workflow syntax with simple labels:
jobs:
test:
runs-on: cihub-2cpu-4gb-amd64
📊 Full Observability
Built-in dashboard showing real-time job metrics, node health, runner status, and detailed logs.
📈 Infinitely Scalable
Start with a single machine or grow to a distributed cluster. Orchestrator handles load balancing and scheduling.
💻 Multi-Architecture Support
Support for both amd64 and arm64 architectures with automatic platform detection.
🏗️ Architecture
CIHub consists of two main components:
- Server – Central coordinator that receives GitHub webhooks, manages runner assignment, handles job scheduling, exposes REST APIs, and serves the management UI
- Agent – Runs on each worker node to manage local Firecracker micro-VMs and execute assigned jobs
Both components communicate via REST APIs. The server handles all orchestration logic, while agents operate autonomously on their assigned nodes.
📚 Documentation
- Deployment Guide – Step-by-step setup instructions
- Configuration Reference – All settings and environment variables
- Architecture Overview – System design and component interaction
- API Reference – REST API endpoints and webhooks
🧾 License
Licensed under the Mozilla Public License 2.0
🛡️ Security
We take security seriously. If you discover a vulnerability:
Please report it responsibly to contact@cihub.io instead of using public issues.
We will acknowledge receipt within 24 hours and provide updates as fixes are developed.
🤝 Contributing
We welcome contributions! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
📞 Support & Community
- GitHub Issues – Report bugs or request features
- Discussions – Ask questions and share ideas
- Website – https://cihub.io
- Email – contact@cihub.io
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
cihub-agent
command
|
|
|
cihub-server
command
|
|
|
handler
|
|
|
hook
|
|
|
Package label provides dynamic label parsing for GitHub Actions runner specifications.
|
Package label provides dynamic label parsing for GitHub Actions runner specifications. |
|
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |
|
service
|
|
|
store
|
|
|
web
|
|