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.

App configuration [required]

GithubOrganization

  • Type: String
  • MinLength: 1
  • Description: For instance if your GitHub organization lives at github.com/my-org, then the value of this parameter should be: my-org

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 so make sure to use a valid address. You must confirm it if you want to receive cost and alert reports.

VPC configuration [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

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

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.

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.

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.

Security settings [optional]

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.

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

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

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.

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.

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.