Documentation
Documentation for RunsOn, the self-hosted GitHub Actions runner for AWS.
Guides
Section titled “Guides” Installation RunsOn is the best way to run GitHub Actions in your own AWS infrastructure, and get 10x cheaper runners.
Troubleshooting Troubleshoot your RunsOn installation
Upgrade Learn how to upgrade RunsOn.
Downgrade Learn how to downgrade RunsOn.
Uninstall Learn how to uninstall RunsOn.
Terraform Deploy RunsOn using the official Terraform module
Runners
Section titled “Runners” Overview Overview of the different runner types available in RunsOn - Linux, GPU, macOS, Windows, and warm pools.
Linux Learn how to set up and use Linux self-hosted runners for your GitHub Actions workflows. Supports native x64 and arm64 architectures.
Windows Learn how to set up and use Windows self-hosted runners for your GitHub Actions workflows.
GPU 10x cheaper GPU runners with NVIDIA or AMD GPUs for GitHub Actions.
macOS Custom macOS GitHub Actions self-hosted runners on AWS.
Pools Learn how to use runner warm pools to get <10s queuing time for your GitHub Actions workflows on self-hosted runners.
Configuration
Section titled “Configuration” Overview Overview of configuration options in RunsOn - job labels, stack settings, custom images, and more.
Job labels Learn how to configure your GitHub Actions runners with specific requirements in terms of CPU, GPU, RAM, volume size, and more.
Repository configuration Learn all about .github/runs-on.yml configuration file
Stack configuration Learn how to configure your RunsOn stack.
Environments Learn how to use RunsOn environments to isolate different workflows in different environments, with different IAM permissions or stack configurations, etc.
Custom images RunsOn provides compatible images with official GitHub Actions runners, but you can also bring your own images if you want!
GitHub App Permissions Learn how to manually update permissions for your GitHub App when a RunsOn upgrade requires new permissions.
Resource tags Learn how to tag RunsOn resources with custom tags, as well as the default tags that are applied.
Caching
Section titled “Caching” Overview Overview of the different caching strategies available in RunsOn, and how to use them.
Magic Cache ✨ How to use RunsOn Magic Cache to speed up your builds and get unlimited cache on GitHub Actions runners, by swapping the cache backend to S3.
Ephemeral registry How to use the ephemeral registry with RunsOn, for incredible build speeds
runs-on/cache@v4 Use an S3 bucket as a cache backend for your actions, to enjoy faster download and upload speeds + unlimited cache sizes
Snapshots Save and restore entire folders with block-level snapshots. Helps to speed-up docker builds in your GitHub Actions workflows.
Networking
Section titled “Networking” Overview Overview of networking options in RunsOn - VPC configuration, static IPs, SSH access, and more.
Reuse existing VPC RunsOn can be configured to reuse an existing VPC, to avoid creating a new one.
SSH / SSM access RunsOn provides a dedicated SSH / SSM console to access your GitHub Action runners, for easy troubleshooting.
Static IPs Learn how RunsOn can be configured with static IPs for GitHub Action runners, ensuring secure, compliant, and reliable CI/CD workflows.
VPC peering Learn how to set up and use VPC peering with RunsOn.
Monitoring
Section titled “Monitoring” Job Metrics Monitor job performance and resource usage
Stack Metrics Monitor your RunsOn installation with OpenTelemetry and CloudWatch
Alerts Receive job errors and monitoring alarms with RunsOn
Cost report Learn how to enable the GitHub Actions cost reporting functionality with RunsOn
Job retries Jobs processed with RunsOn are regularly inspected to ensure they were able to get a runner assigned, as well as detect idle runners and remove them.
Benchmarks
Section titled “Benchmarks” GitHub Actions CPU GitHub Actions runners comparison across CPU speed, queue time, and pricing. Benchmarks x64 and arm64 runners, including self-hosted options like RunsOn and AWS CodeBuild plus third-party providers.
GitHub Actions Cache Compare actions/cache performance across GitHub Actions runners. Speed up dependency caching and Docker layer caching on your self-hosted or managed runners!
GitHub Actions I/O Compare alternatives to GitHub Actions runners across CPU speed, queuing times, and price. Includes self-hosted and third-party options such as RunsOn, AWS CodeBuild, Buildjet, Ubicloud, Namespace, Blacksmith...
AWS EC2 Instances Compare CPU speed, pricing, and spot interruption percentages of most EC2 instance types.