Skip to content

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.

GithubOrganization

Type: String

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

MinLength: 1

LicenseKey

Type: String

Description: License key. Get one at https://runs-on.com/pricing.

MinLength: 1

EmailAddress

Type: String

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.

MinLength: 1

Environment

Type: String

Default: production

MinLength: 1

Description: Environment for the RunsOn service: you can create multiple RunsOn installations and set this parameter to different values. And then target a single installation by setting the env=ENV_NAME label in the runs-on: definition in your GitHub Actions workflow. If no env label is set in job definitions, the production environment is targeted, so make sure to keep this default value if you only have one RunsOn installation.

AlertTopicSubscriptionHttpsEndpoint

Type: String

Description: HTTPS endpoint for cost and alert reports.

Default:

VpcCidrBlock

Type: String

Description: CIDR block for the VPC. Updating this value after creation will require deleting the stack and recreating it.

Default: 10.1.0.0/16

VpcCidrSubnetBits

Type: Number

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.

Default: 12

MinValue: 9

MaxValue: 16

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.

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

Description: CIDR range for inbound SSH access. By default, only repository collaborators with admin permission will be able to SSH into the runner instances.

MinLength: 1

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

NatGatewayElasticIPCount

Type: Number

Default: 1

MinValue: 1

MaxValue: 8

Description: Number of Elastic IPv4s to attach to each NAT Gateway (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.

NatGatewayAvailability

Type: String

Default: SingleAZ

AllowedValues:

  • SingleAZ
  • MultiAZ

VpcFlowLogFormat

Type: String

Default:

Description: VPC Flow Log format. If blank, the default format will be used. More details at https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html#flow-logs-fields

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.

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.

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.

AppEc2QueueSize

Type: Number

Default: 2

MinValue: 1

Description: Rate limit for launching instances, per second. New AWS accounts come with a default of 2 RunInstances call/s, so only increase this if you have requested a higher limit from AWS (https://docs.aws.amazon.com/AWSEC2/latest/APIReference/throttling.html).

AppAlarmDailyMinutes

Type: Number

Default: 4000

Description: Trigger an alarm if the cumulative number of minutes consumed during a day is over that number.

AppCPU

Type: Number

Default: 256

Description: CPU units for RunsOn service (256 or higher). If you have many workflows, you may need to increase this (512, 1024, etc.).

AppMemory

Type: Number

Default: 512

Description: Memory in MB for RunsOn service (512 or higher). If you have many workflows, you may need to increase this (1024, 2048, etc.).

AppRegistry

Type: String

Default: public.ecr.aws/c5h5o9k1/runs-on/runs-on

Description: Docker image (public) registry for the RunsOn service.

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.

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

RunnerCustomTags

Type: CommaDelimitedList

Default:

Description: Optional custom tags for the runner instances (e.g. ‘key1=value1,key2=value2’). Tag keys cannot start with runs-on, and can only use letters (a-z, A-Z), numbers (0-9), and the following characters: + - = . , _ : @ (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions)

CostReportsEnabled

Type: String

Default: true

AllowedValues:

  • “true"
  • "false”

Description: Enable or disable cost reports sent by email.

EC2InstanceCustomPolicy

Type: String

Default:

Description: Optional managed IAM Policy ARN to assign to the EC2 runner instances.

ECInstanceDetailedMonitoring

Type: String

Default: false

AllowedValues:

  • “true"
  • "false”

Description: Enable or disable detailed monitoring for EC2 instances (can incur additional costs).

ServerPassword

Type: String

Default:

Description: Password for the RunsOn server (/metrics endpoint). If blank, the endpoint(s) will be disabled.

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.