CloudFormation

Current CloudFormation parameters and fixed built-in behavior for RunsOn v3.

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.

RunsOn v3’s built-in CloudFormation stack is more scoped than the v2 stack. For advanced infrastructure usage such as GHES, existing VPCs, or deeper networking control, use the Terraform / OpenTofu guide instead.

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.

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

  • NoEcho: true

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.

Environment

  • Type: String
  • Default: production
  • MinLength: 1
  • Description: Make RunsOn only listen to jobs with an env job label matching this value. Only change this if you know what you are doing. See https://runs-on.com/configuration/environments/ ↗ for more details.

Networking and security [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.

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.

EnableWAF

  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Enable AWS WAF for the public ingress.

EnableAdminRoutes

  • Type: String
  • Default: true
  • AllowedValues: true, false
  • Description: Enable the admin Lambda routes (/, /setup, /setup/{proxy+}, /readyz) on the public ingress.

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.

RunnerCustomPolicy

  • 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 RunsOn service role. Can be used to e.g. allow access to KMS decryption keys for AMIs.

Runner behavior and storage [optional]

EnableBedrock

  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Enable Amazon Bedrock access for EC2 runner instances. When enabled, runners can use their instance profile credentials with Bedrock-compatible AI agents such as Claude Code or OpenCode.

EnableEfs

  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Enable EFS shared filesystem for runners. 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

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

RunnerCustomTags

RunnerMaxRuntime

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

RunnerConfigAutoExtendsFrom

  • Type: String
  • Default: .github-private
  • MinLength: 1
  • Description: When set to a repository name (e.g., ‘.github-private’), forces all repository configurations to extend from that repository. The config will be read from <repo-name>/.github/runs-on.yml. This allows you to provide a base configuration that applies to all repositories, even if they don’t have a local runs-on.yml file. Set to ’.’ to disable auto-extend and use each repository’s local extends (if any). Make sure the GitHub App has access to the specified repository.

S3CacheExpirationInDays

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

App runtime and maintenance [optional]

AppSize

  • Type: String
  • Default: small
  • AllowedValues: small, medium, high, xhigh
  • Description: Preset for the RunsOn control plane. This sets the worker service CPU/memory, queued-job concurrency, and the default EC2 launch/termination rate-limit assumptions together. Higher concurrency presets assume you have raised the relevant EC2 quotas (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.

AppRegistry

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

LoggerLevel

  • Type: String
  • Default: info
  • AllowedValues: trace, debug, info, warn
  • Description: Log level for the RunsOn server. Options: trace (most verbose), debug, info (default), warn (least verbose).

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.

MaintenanceMode

  • Type: String
  • Default: false
  • AllowedValues: true, false
  • Description: Enable maintenance mode (scales the worker service to zero)

Observability, cost, and integrations [optional]

OtelExporterEndpoint

OtelExporterHeaders

  • Type: String
  • Default:  
  • Description: Headers for OTLP endpoint in W3C Baggage format: ‘key1=value1,key2=value2’ (e.g., ‘signoz-ingestion-key=ABCD1234’). Leave empty if not required.
  • NoEcho: true

OtelExporterTemporality

  • Type: String
  • Default: cumulative
  • AllowedValues: cumulative, delta
  • Description: OTLP metrics temporality. Use cumulative (default) or delta (required by Datadog).

CostReportsEnabled

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

AlertTopicSlackWebhookUrl

  • Type: String
  • Default:  
  • Description: Slack incoming webhook URL for alert notifications.
  • NoEcho: true

AppBudgetDailyUsd

  • Type: Number
  • Default: 10
  • Description: Create a daily AWS cost budget in USD for this stack, filtered by the configured cost allocation tag. The budget evaluates UTC billing periods rather than real-time operational usage. For AWS Organizations member accounts, activate the cost allocation tag in the management account’s Billing settings.

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.

IntegrationStepSecurityApiKey