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:

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 built-in v3 RunsOn stack are:

• One VPC, two public subnets, two private subnets, and a security group for EC2 instances launched by RunsOn.
• API Gateway and Lambda public ingress for setup, health checks, and GitHub webhook delivery.
• One ECS worker service that processes webhooks, queues, reconciliation, and EC2 runner provisioning.
• Secrets Manager secrets for stack metadata and the private GitHub App credentials created during setup.
• 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 RunsOn control plane.
• Restricted IAM roles for the RunsOn control plane, and an instance profile for the EC2 instances.
• Multiple CloudWatch log groups, used to store the logs of the RunsOn control plane and EC2 instances.

When using Private mode, the stack will also create:

• One NAT gateway with one static IP, to allow private subnets to access the internet and provide a static egress IP for your self-hosted runners.
• The free S3 gateway VPC endpoint.

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 peer your existing VPCs to the RunsOn VPC if you want to use existing resources, or use Terraform / OpenTofu when you need to deploy RunsOn into an existing VPC.

Multi-AZ support

RunsOn supports multi-AZ deployments. The built-in v3 CloudFormation template uses two availability zones, so runner instances can be distributed across multiple capacity pools.

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 ↗.