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

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 must confirm the subscription by clicking the link in the email that you will receive after creating the stack.

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.

Advanced app configuration [optional]

Environment

RunnerCustomTags

RunnerDefaultDiskSize

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

RunnerDefaultVolumeThroughput

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

RunnerLargeDiskSize

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

RunnerLargeVolumeThroughput

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

AppEc2QueueSize

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.

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.