Skip to content
RunsOn - 10x cheaper self-hosted GitHub Actions 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]

Section titled “Main configuration [required]”

GithubOrganization

Section titled “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

Section titled “GithubEnterpriseUrl”

LicenseKey

Section titled “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

Section titled “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

Section titled “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]

Section titled “Networking: use external stack [optional]”

ExternalVpcId

Section titled “ExternalVpcId”
  • Type: String
  • Default:  
  • Description: ID of the external VPC to reuse.

ExternalVpcSubnetIds

Section titled “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

Section titled “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, EFS (if enabled), and any other service your jobs will call.

Networking: use embedded stack [optional]

Section titled “Networking: use embedded stack [optional]”

VpcCidrBlock

Section titled “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

Section titled “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

Section titled “VpcEndpoints”

NatGatewayAvailability

Section titled “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

Section titled “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

Section titled “VpcFlowLogFormat”

VpcFlowLogS3BucketArn

Section titled “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

Section titled “VpcFlowLogRetentionInDays”
  • Type: Number
  • Default: 7
  • MinValue: 1
  • Description: Retention period in days for VPC Flow Logs.

Network and Security settings [optional]

Section titled “Network and Security settings [optional]”

Private

Section titled “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

Section titled “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

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

SSHCidrRange

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “ServerPassword”

DefaultAdmins

Section titled “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

Section titled “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.

EnableEfs

Section titled “EnableEfs”
  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Enable EFS shared filesystem for runners (only available with ‘embedded’ networking). If enabled, an EFS volume will be created and made available to runners. Runners will need appropriate permissions and tools (e.g., nfs-utils) to mount it.

EnableEphemeralRegistry

Section titled “EnableEphemeralRegistry”
  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: If enabled, create an ECR ephemeral registry that can be used as a type=registry cache backend for Docker BuildKit. The registry will be created with a 10-day lifecycle policy, and runners will automatically be granted push/pull access.

Alert and monitoring settings [optional]

Section titled “Alert and monitoring settings [optional]”

AppAlarmDailyMinutes

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

CostReportsEnabled

Section titled “CostReportsEnabled”
  • Type: String
  • Default: true
  • AllowedValues: true, false
  • Description: Enable or disable cost reports sent by email.

AlertTopicSubscriptionHttpsEndpoint

Section titled “AlertTopicSubscriptionHttpsEndpoint”
  • Type: String
  • Default:  
  • Description: HTTPS endpoint for cost and alert reports.

ECInstanceDetailedMonitoring

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

Ec2LogRetentionInDays

Section titled “Ec2LogRetentionInDays”
  • Type: Number
  • Default: 7
  • MinValue: 1
  • Description: Retention period in days for EC2 instance logs.

SqsQueueOldestMessageThresholdSeconds

Section titled “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]

Section titled “Integrations [optional]”

IntegrationStepSecurityApiKey

Section titled “IntegrationStepSecurityApiKey”

Advanced app configuration [optional]

Section titled “Advanced app configuration [optional]”

Environment

Section titled “Environment”

CostAllocationTag

Section titled “CostAllocationTag”
  • Type: String
  • Default: stack
  • Description: Cost allocation tag key to use for all the deployed resources. The value for this tag will be set to the stack name. Updating this after creation will require deleting the stack and recreating it.

SpotCircuitBreaker

Section titled “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

Section titled “RunnerCustomTags”

RunnerDefaultDiskSize

Section titled “RunnerDefaultDiskSize”
  • Type: Number
  • Default: 40
  • MinValue: 40
  • Description: Disk size in GB for disk=default runners.

RunnerDefaultDiskDeviceName

Section titled “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

Section titled “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

Section titled “RunnerLargeDiskSize”
  • Type: Number
  • Default: 80
  • MinValue: 40
  • Description: Disk size in GB for disk=large runners.

RunnerLargeDiskDeviceName

Section titled “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

Section titled “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).

RunnerMaxRuntime

Section titled “RunnerMaxRuntime”
  • Type: Number
  • Default: 720
  • MinValue: 30
  • Description: Maximum runtime in minutes for runners. After this time, the runner will be forcefully terminated.

AppEc2QueueSize

Section titled “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

Section titled “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

Section titled “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

Section titled “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

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

AppDebug

Section titled “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

Section titled “S3CacheExpirationInDays”
  • Type: Number
  • Default: 10
  • Description: Number of days to keep cache entries in the S3 cache bucket.