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

Stack configuration

The CloudFormation stack that RunsOn creates when installing the service has many parameters. This page lists them all and describes what each one does.

To update a parameter, simply follow the instructions in the Upgrade guide and update the parameter in the CloudFormation interface.

Main configuration [required]

GithubOrganization

  • Type: String
  • MinLength: 1
  • Description: If your GitHub organization lives at github.com/my-org, then enter: my-org. IMPORTANT: this field is case-sensitive.

GithubEnterpriseUrl

LicenseKey

  • Type: String
  • MinLength: 1
  • Description: License key for RunsOn, either as a string or SSM parameter ARN (with the format arn:aws:ssm:REGION:ACCOUNT:parameter/STACK_NAME/license-key). Get one at https://runs-on.com/pricing ↗.

EmailAddress

  • Type: String
  • MinLength: 1
  • Description: Email address for cost and alert reports. You will receive a confirmation email from AWS at this address during the installation (check your spam folder if needed) so make sure to use a valid address. You must confirm it if you want to receive cost and alert reports.

NetworkingStack

  • Type: String
  • Default: embedded
  • AllowedValues: embedded, external
  • Description: Let RunsOn manage your networking stack (embedded), or use a stack under your control (external). If you select external, you will need to provide the VPC ID, the subnet IDs, and the security group ID, and make sure your whole networking setup is compatible with RunsOn (see https://runs-on.com/networking/embedded-vs-external/ ↗ for more details). To get started quickly, we recommend using the ‘embedded’ option.

Networking: use external stack [optional]

ExternalVpcId

  • Type: String
  • Default:  
  • Description: ID of the external VPC to reuse.

ExternalVpcSubnetIds

  • Type: CommaDelimitedList
  • Default:  
  • Description: Subnet IDs (public, private, or both) of the external VPC to reuse, comma-separated. The more subnets you have, the more RunsOn will be able to find cheap spot instances, as well as balancing the load across many AZs.

ExternalVpcSecurityGroupId

  • Type: String
  • Default:  
  • Description: Security group ID of the external VPC to assign to the runners. Must allow outbound access to the GitHub IP ranges, and any other service your jobs will call.

Networking: use embedded stack [optional]

VpcCidrBlock

  • Type: String
  • Default: 10.1.0.0/16
  • Description: CIDR block for the VPC. Updating this value after creation will require deleting the stack and recreating it.

VpcCidrSubnetBits

  • Type: Number
  • Default: 12
  • MinValue: 9
  • MaxValue: 16
  • Description: Number of bits to allocate for the subnet. For example, if you specify VpcCidrBlock to a /16 (the default), and this value to 12 (the default), you will have 4 bits, i.e. max 16 subnets in the VPC. Updating this value after creation will require deleting the stack and recreating it.

VpcEndpoints

NatGatewayAvailability

  • Type: String
  • Default: SingleAZ
  • AllowedValues: SingleAZ, MultiAZ
  • Description: Create either a single NAT Gateway (SingleAZ) for all 3 availability zones, or a NAT Gateway per Availability Zone (MultiAZ). Only applies if Private mode is enabled. Each gateway incurs ~$32.4/month, plus bandwidth costs.

NatGatewayElasticIPCount

  • Type: Number
  • Default: 1
  • MinValue: 1
  • MaxValue: 8
  • Description: Number of Elastic IPv4s to attach to each NAT Gateway. Only applies if Private mode is enabled. Defaults to 1. Maximum of 8. Increasing this number is useful if you launch a large number of runners and are rate-limited by some external services due to the limited number of NAT Gateway IP addresses. Incurs ~$3.6/month additional cost for each Elastic IP. Note that by default you are limited to 2 EIPs per NAT gateway, but can request a quota increase from AWS.

VpcFlowLogFormat

VpcFlowLogS3BucketArn

  • Type: String
  • Default:  
  • Description: ARN of an S3 bucket to send VPC Flow Logs to in addition to the default CloudWatch logs group. If blank, the logs will only be sent to CloudWatch Logs.

VpcFlowLogRetentionInDays

  • Type: Number
  • Default: 7
  • MinValue: 1
  • Description: Retention period in days for VPC Flow Logs.

Network and Security settings [optional]

Private

  • Type: String
  • Default: false
  • AllowedValues: only, always, true, false
  • Description: Enable (‘true’, ‘always’, ‘only’) or disable (‘false’) private networking. If ‘true’, your jobs can opt-in to launch in private subnets with the private=true label, and they will get a static egress IP. If ‘always’, all jobs will run in private subnets, and they will all get a static egress IP, unless you manually opt-out in your job definition with the private=false label. If ‘only’, then jobs can only launch in private subnets. Note that enabling it will create 1 managed NAT gateway, with the corresponding costs. More details at https://runs-on.com/networking/static-ips/ ↗.

Ipv6Enabled

  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Enable or disable IPv6 for runners. Disabling ipv6 might help with Docker Hub rate limiting issues. If enabled and reusing a VPC, ensure the VPC is IPv6 enabled.

SSHAllowed

  • Type: String
  • Default: true
  • AllowedValues: true, false
  • Description: Allow inbound SSH connections from the specified CIDR range to the runners.

SSHCidrRange

  • Type: String
  • Default: 0.0.0.0/0
  • MinLength: 1
  • Description: CIDR range for inbound SSH access. By default, only repository collaborators with admin permission will be able to SSH into the runner instances.

EC2InstanceCustomPolicy

  • Type: String
  • Default:  
  • Description: Optional managed IAM Policy ARN to assign to the EC2 runner instances. Can be used to give runners access to AWS resources that you manage.

AppCustomPolicy

  • Type: String
  • Default:  
  • Description: Optional managed IAM Policy ARN to assign to the App runner service role. Can be used to e.g. allow access to KMS decryption keys for AMIs.

DefaultPermissionBoundaryArn

  • Type: String
  • Default:  
  • Description: ARN of an IAM policy that will be assigned as permission boundary to roles created by the stack. If blank, the roles will not have a permission boundary.

ServerPassword

DefaultAdmins

  • Type: String
  • Default:  
  • Description: Comma-separated list of GitHub usernames that will always be granted SSH access to all the runner instances (if SSH access is enabled), in addition to any repository admins. If blank, only repository collaborators with admin permission will be able to SSH into the runner instances.

EncryptEbs

  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Encrypt the EBS volumes of the runner instances. Encryption will slow the boot time of runner instances by ~10s.

Alert and monitoring settings [optional]

AppAlarmDailyMinutes

  • Type: Number
  • Default: 4000
  • Description: Trigger an alarm if the cumulative number of minutes consumed during a day is over that number.

CostReportsEnabled

  • Type: String
  • Default: true
  • AllowedValues: true, false
  • Description: Enable or disable cost reports sent by email.

AlertTopicSubscriptionHttpsEndpoint

  • Type: String
  • Default:  
  • Description: HTTPS endpoint for cost and alert reports.

ECInstanceDetailedMonitoring

  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Enable or disable detailed monitoring for EC2 instances (can incur additional costs).

Ec2LogRetentionInDays

  • Type: Number
  • Default: 7
  • MinValue: 1
  • Description: Retention period in days for EC2 instance logs.

SqsQueueOldestMessageThresholdSeconds

  • Type: Number
  • Default: 0
  • Description: Trigger an alarm per sqs queue if the oldest message in that queue is older than this time in seconds. Leave as 0 to disable SQS alarms.

Integrations [optional]

IntegrationStepSecurityApiKey

Advanced app configuration [optional]

Environment

CostAllocationTag

  • Type: String
  • Default: stack
  • Description: Cost allocation tag to use for all the deployed resources. Updating this after creation will require deleting the stack and recreating it.

SpotCircuitBreaker

  • Type: String
  • Default: 2/15/30
  • AllowedPattern: ^(false|[0-9]+/[0-9]+/[0-9]+)$
  • Description: Enable (COUNT/WINDOW_MINUTES/RECOVERY_MINUTES) or disable (false) the spot instance circuit breaker. If enabled, the circuit breaker will prevent the stack from launching new spot instances during RECOVERY_MINUTES if there was at least COUNT spot interruptions during the last WINDOW_MINUTES. For instance 2/15/30 will prevent the stack from launching new spot instances during 30 minutes if there was at least 2 spot interruptions during the last 15 minutes.

RunnerCustomTags

RunnerDefaultDiskSize

  • Type: Number
  • Default: 40
  • MinValue: 40
  • Description: Disk size in GB for disk=default runners.

RunnerDefaultDiskDeviceName

  • Type: String
  • Default: /dev/sda1
  • Description: Name of the root volume device name for the disk=default runner. Only change this if you plan on using custom AMIs that have a different root volume name.

RunnerDefaultVolumeThroughput

  • Type: Number
  • Default: 400
  • MinValue: 125
  • MaxValue: 1000
  • Description: Volume throughput in MiB/s for disk=default runners (helps with faster boot times, but costs more).

RunnerLargeDiskSize

  • Type: Number
  • Default: 80
  • MinValue: 40
  • Description: Disk size in GB for disk=large runners.

RunnerLargeDiskDeviceName

  • Type: String
  • Default: /dev/sda1
  • Description: Name of the root volume device name for the disk=large runner. Only change this if you plan on using custom AMIs that have a different root volume name.

RunnerLargeVolumeThroughput

  • Type: Number
  • Default: 750
  • MinValue: 125
  • MaxValue: 1000
  • Description: Volume throughput in MiB/s for disk=large runners (helps with faster boot times, but costs more).

AppEc2QueueSize

  • Type: Number
  • Default: 2
  • MinValue: 1
  • Description: Number of queued jobs that can be processed concurrently by RunsOn. Each job takes about 2-3s to process. Increasing this value should be done with caution, as it will increase the number of EC2 instances that will be launched at once, eating into your AWS and GitHub rate limits. New AWS accounts come with a rate-limit of 2 RunInstances call/s, although you can request a higher limit from AWS (https://docs.aws.amazon.com/AWSEC2/latest/APIReference/throttling.html ↗).

AppGithubApiStrategy

  • Type: String
  • Default: normal
  • AllowedValues: normal, conservative
  • Description: Use normal or conservative GitHub API strategy. The conservative strategy will attempt to save GitHub API tokens by not automatically de-registering runners from the GitHub API after they are no longer needed. It’s more elegant to clean them up (recommended), but in any case GitHub will eventually clean them up on their side after 24h. Especially useful if you launch tens of thousands of jobs every day.

AppCPU

  • Type: Number
  • Default: 256
  • AllowedValues: 256, 512, 1024, 2048, 4096
  • Description: CPU units for RunsOn service (256 or higher). You might only need to change this if you have 10k+ jobs per day.

AppMemory

  • Type: Number
  • Default: 512
  • AllowedValues: 512, 1024, 2048, 3072, 4096, 6144, 8192
  • Description: Memory in MB for RunsOn service (512 or higher). You might only need to change this if you have 10k+ jobs per day.

AppRegistry

  • Type: String
  • Default: public.ecr.aws/c5h5o9k1/runs-on/runs-on
  • Description: Docker image (public) registry for the RunsOn service.

AppDebug

  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Enable or disable debug mode for the RunsOn stack. Enabling this will switch off the auto-shutdown of the runner instances when they are unable to bootstrap.

S3CacheExpirationInDays

  • Type: Number
  • Default: 10
  • Description: Number of days to keep cache entries in the S3 cache bucket.