Skip to content
RunsOn - 10x cheaper self-hosted GitHub runners RunsOn
Blog

Architecture

Forget the pain of managing your own self-hosted runners, or troubleshooting your Actions Runner Controller (ARC) installation on Kubernetes. RunsOn is a simple yet scalable solution to run your GitHub Actions workflows on a dedicated, scalable, and secure infrastructure.

RunsOn comes as a software stack that you install in your own AWS account. It will spawn EC2 instances in place of official GitHub runners. It is a drop-in replacement for official or third-party GitHub Action runners, and can do its job thanks to a few fully managed AWS services:

Architecture

RunsOn stack

When you setup the RunsOn stack, you will trigger the creation of AWS resources that will be used to listen and react to GitHub webhooks triggered by your workflows.

The main components of the RunsOn stack are:

  • One VPC
  • 3 public subnets, and 3 private subnets.
  • One Security group for EC2 instances launched by RunsOn
  • One AppRunner service, which hosts the RunsOn server and is used to listen to GitHub webhooks and trigger EC2 instance deployments
  • One S3 configuration bucket, that hosts the credentials that you get when registering your private GitHub App with GitHub.
  • One S3 cache bucket, which is used for unlimited and 5x faster caching of dependencies and docker layers (see Magic Cache).
  • One SNS topic, used to send alerts and cost reports.
  • Multiple SQS queues, used internally by the AppRunner service.
  • Restricted IAM role for the AppRunner service, and instance profile for the EC2 instances.
  • Multiple CloudWatch log groups, used to store the logs of the RunsOn server, EC2 instances, and VPC flow logs.

When using Private mode, the stack will also create:

  • NAT gateway(s) with static IP(s), to allow private subnets to access the internet as well as providing static egress IPs for your self-hosted runners.
  • VPC endpoints for EC2 and ECR, to allow private access to these services.

VPC isolation

RunsOn sets up its own VPC in your AWS account, so that it is by default fully isolated from the rest of your resources. You can easily peer your existing VPCs to the RunsOn VPC if you want to use existing resources.

Multi-AZ support

RunsOn supports multi-AZ deployments across 3 availability zones, so your runner instances are distributed across multiple availability zones. This ensures high availability and redundancy, minimizing the risk of downtime and ensuring that your CI/CD pipelines can continue to run smoothly even in the event of an AZ failure.

This also increases the chance of finding spot instances at the best price possible, as the instances are not all in the same AZ.

Full VMs

Runners are started on real virtual machines (EC2 instances), which means you get full isolation between jobs, and can easily use Docker or Kubernetes tooling without requiring to docker-in-docker hacks.

Ephemeral instances

Instances are ephemeral, and are only started when there is work to do, and terminated when the work is done. So there is no idle cost, and no need to manage an extended lifecycle for the instances.

Built-in scalability

The only limit to the number of instances you can run in parallel is the number of EC2 instances (spot and on-demand) you can launch in your AWS account. This can be adjusted at any time by requesting a quota increase from AWS. If spot instances are not available, then on-demand instances will automatically be used instead.

Note that the spot and on-demand instances have their own quotas. The spot quota is the most important to increase if you have a large number of jobs to run.

Full compliance with AWS security best practices

Everything runs in your private AWS account, and the stack set up by RunsOn is fully compliant with the AWS Foundational Security Best Practices v1.0.0 ↗.