RunsOn Infrastructure for GitHub Actions

The contemporary landscape of Continuous Integration and Continuous Deployment (CI/CD) often forces organizations into a compromise between the convenience of managed services and the cost-efficiency of self-hosted infrastructure. GitHub-hosted runners, while seamless, frequently introduce significant financial overhead and performance bottlenecks, particularly for resource-intensive workloads. RunsOn emerges as a specialized architectural solution designed to bridge this gap by deploying self-hosted GitHub Actions runners directly into a user's own Amazon Web Services (AWS) account. Unlike traditional self-hosting methods that require manual server management or complex Kubernetes orchestrations, RunsOn automates the lifecycle of ephemeral virtual machines, providing the agility of the cloud with the ownership and pricing advantages of private infrastructure.

The fundamental philosophy of RunsOn is the elimination of the "black box" nature of hosted runners. By utilizing a private GitHub App for organizational integration and deploying via CloudFormation templates, the system ensures that the compute environment is fully owned by the user. This architectural shift allows for the use of specific AWS instance types, custom networking models, and tailored machine images (AMIs) that are often unavailable or prohibitively expensive in standard hosted environments. The result is a system that typically reduces CI spend by 7x to 15x while simultaneously increasing raw CPU performance by up to 30%.

Architectural Implementation and Deployment

The deployment of RunsOn is engineered for rapid integration, allowing a full installation to be completed in approximately 10 minutes. The primary mechanism for this setup is a series of CloudFormation templates, which include a main installation template and several supporting public templates. This approach ensures that the infrastructure is treated as code, allowing for reproducible environments and simplified upgrades.

The integration with GitHub is handled through a private GitHub App created specifically for the user's organization. This method ensures a high level of security, as it avoids the need for broad, long-lived personal access tokens and keeps the runner infrastructure isolated within the user's AWS perimeter.

The transition from standard GitHub-hosted runners to RunsOn involves a modification of the runs-on label in the workflow YAML file.

Standard configuration:
runs-on: ubuntu-latest

RunsOn configuration:
runs-on: "runs-on=${{ github.run_id }}/runner=2cpu-linux-x64"

This syntax allows the system to dynamically assign runners based on the specific run ID and requested hardware specifications, ensuring that every job receives a fresh, ephemeral VM.

Hardware Capabilities and Environmental Support

RunsOn provides extensive flexibility regarding the operating systems and hardware accelerators available for CI jobs. This versatility is critical for teams that require specific kernels, GPU acceleration for machine learning workloads, or Windows-specific environments for legacy software testing.

The system supports the following environments:

• Linux runners for general purpose and high-performance computing.
• Windows runners for ecosystem-specific builds.
• GPU runners for CUDA-enabled workloads and AI model training.

The compute model leverages AWS Spot instances to maximize cost savings. To ensure high availability and prevent job failures due to spot interruptions, RunsOn includes an automatic on-demand fallback mechanism. If spot capacity is unavailable in a specific region, the system seamlessly transitions to on-demand instances to ensure the build pipeline remains operational.

Furthermore, the system supports multi-AZ (Availability Zone) and multi-environment configurations, which prevents a single AWS zone failure from halting the entire organization's CI/CD pipeline. For networking requirements that demand more than simple outbound access, RunsOn offers optional SSH access and static IPs, allowing developers to tunnel into runners for debugging or to whitelist specific runner IPs in corporate firewalls.

The RunsOn Action and Magic Caching

To unlock the full potential of the platform, the runs-on/action@v2 must be integrated into the workflow steps. This action is a prerequisite for "Magic Caching" and other advanced telemetry features. When the extras=s3-cache job label is used, the system activates a high-performance S3-backed caching mechanism.

The implementation for magic caching is as follows:

yaml jobs: build: runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=s3-cache steps: - uses: runs-on/action@v2 - other steps

This S3 cache backend is designed to be significantly faster and larger than the standard GitHub Actions cache, which often suffers from strict size limits and slower upload/download speeds. By utilizing the AWS S3 bucket that comes bundled with the RunsOn installation, users gain unlimited storage and blazing fast throughput.

Sccache Integration for Compiled Languages

For developers working with C, C++, Rust, or NVIDIA CUDA, RunsOn provides specialized support for sccache. This allows for the caching of compiled objects across different jobs and runs, drastically reducing the time spent in the compilation phase.

To enable this, the sccache parameter is set to s3 within the runs-on/action@v2 configuration:

yaml jobs: build: runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=s3-cache steps: - uses: runs-on/action@v2 with: sccache: s3 - uses: mozilla-actions/[email protected] - run: # your slow rust compilation

Under the hood, the action automatically configures the environment variables necessary for sccache to communicate with the S3 backend. The system executes the following logic:

bash echo "SCCACHE_GHA_ENABLED=false" >> $GITHUB_ENV echo "SCCACHE_BUCKET=${{ env.RUNS_ON_S3_BUCKET_CACHE}}" >> $GITHUB_ENV echo "SCCACHE_REGION=${{ env.RUNS_ON_AWS_REGION}}" >> $GITHUB_ENV

Telemetry, Cost Analysis, and Monitoring

One of the primary advantages of RunsOn is the transparency it provides regarding resource utilization and financial expenditure. Unlike hosted runners, where costs are abstracted into "minutes," RunsOn provides granular data based on actual AWS pricing.

Financial Reporting

The runs-on/action@v2 can calculate the exact cost of a workflow job by querying https://ec2-pricing.runs-on.com. This service provides real-time data for both on-demand and spot pricing across all AWS regions and zones.

The action can display these costs in two formats:
- inline: Costs are printed directly in the action log.
- summary: Costs are added to the GitHub job summary page.

A typical cost report includes the following metrics:

Performance Metrics and CloudWatch Integration

For deep technical analysis, RunsOn allows the streaming of telemetry data via the CloudWatch agent. This enables developers to see exactly how their code interacts with the hardware during a build.

The available metrics are categorized as follows:

• cpu: usageuser, usagesystem
• network: bytesrecv, bytessent
• memory: used_percent
• disk: usedpercent, inodesused
• io: io_time, reads, writes

These metrics can be enabled by passing a comma-separated list to the action:

yaml - uses: runs-on/action@v2 with: metrics: cpu,network,memory,disk,io

Upon completion, the action generates live charts in the post-execution summary, providing visual representations of CPU spikes, memory saturation, and network throughput.

Comparison with Alternative Solutions

RunsOn is positioned as a high-performance alternative to several common runner management strategies.

While ARC (Actions Runner Controller) provides scalability on Kubernetes, it introduces significant complexity in terms of cluster maintenance and networking. RunsOn eliminates the Kubernetes layer entirely, utilizing the native AWS EC2 API for faster startup times and stronger isolation between jobs.

Operational Impact and User Testimonials

The implementation of RunsOn has demonstrated measurable impacts on organizational productivity and budgets. For instance, Corentin Smith, CTO at Dashdoc, reported that costs were divided by four. Similarly, Théophile Dunoyer de Segonzac, Lead DevOps Engineer at Lingoda, noted a 70% reduction in costs and a CI runtime improvement of up to 80%.

The efficiency gains are primarily attributed to three factors:
1. The use of Spot instances, which significantly lowers the hourly rate of compute.
2. The removal of the virtualization overhead associated with GitHub's shared hosted environment, leading to a 30% increase in raw CPU performance.
3. The implementation of the S3 cache backend, which minimizes the time spent downloading and uploading dependencies.

Conclusion

The transition to RunsOn represents a strategic shift for organizations that have outgrown the limitations of hosted CI environments. By combining the automation of a managed service with the cost and control of a private AWS account, it solves the primary pain points of GitHub Actions: unpredictable costs and performance throttling. The integration of specialized tools like the S3-backed magic cache and sccache support makes it particularly potent for systems programming and large-scale binary compilation. Ultimately, RunsOn transforms the CI runner from a costly commodity into a high-performance, transparent piece of infrastructure that scales linearly with the needs of the organization without the accompanying financial inflation.

Sources

1. RunsOn GitHub Repository
2. RunsOn Organization
3. RunsOn Action Repository
4. RunsOn Official Website