self-host →

Fleet configuration

Complete reference for configuring RunsOn Fleet — every input of the Terraform module.

RunsOn Fleet is installed exclusively through the Terraform / OpenTofu module — there is no CloudFormation option. This page is the full reference for every module input.

The runner and fleet catalogs (runners, fleets, images) are passed as Terraform inputs too; see Runner fleets for how to model them, and Configuration for how Fleet’s catalog-driven configuration compares to Flex.

To change a value, edit your Terraform configuration and re-apply — see the Upgrade guide.

Terraform inputs

The Terraform module ↗ (runs-on/runs-on/aws//modules/fleet) exposes the following inputs.

Required inputs

stack_name

  • Type: string
  • Required: yes
  • Description: Name of the RunsOn Fleet stack.

license_key

  • Type: string
  • Required: yes
  • Sensitive: yes
  • Description: RunsOn license key obtained from runs-on.com

email

  • Type: string
  • Required: yes
  • Description: Email address for alerts and notifications (requires confirmation)

runners

  • Type: map(any)
  • Required: yes
  • Description: Runner catalog keyed by runner name. Entries must follow the shared config module contract.

fleets

  • Type: map(any)
  • Required: yes
  • Description: Fleet catalog keyed by fleet name. Entries use the shared runner shape plus Fleet-specific settings.

vpc_id

  • Type: string
  • Required: yes
  • Description: VPC ID where the Fleet stack will run.

public_subnet_ids

  • Type: list(string)
  • Required: yes
  • Description: Public subnet IDs used for runners and Fargate when private_mode=false.

Optional inputs

github_app_id

  • Type: number
  • Default: null
  • Description: GitHub App ID used by the Fleet runtime.

github_app_private_key

  • Type: string
  • Default: null
  • Sensitive: yes
  • Description: GitHub App private key in PEM format.

github_enterprise_pat

  • Type: string
  • Default: null
  • Sensitive: yes
  • Description: Classic PAT used for enterprise-target Fleet mode. Must start with ghp_ when set.

github_base_url

  • Type: string
  • Default: "https://github.com"
  • Description: GitHub host root URL. Leave the default for github.com and set a GHES host root such as https://ghe.example.com ↗ when needed.

github_enterprise_name

  • Type: string
  • Default: null
  • Description: GitHub Enterprise slug used when github_enterprise_pat is set.

alert_slack_webhook_url

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: Slack webhook URL for alert notifications (optional)

environment

  • Type: string
  • Default: "production"
  • Description: Environment name used by the workflow targeting contract.

images

  • Type: map(any)
  • Default: {}
  • Description: Custom runner image catalog keyed by image name. Built-in image names such as ubuntu24-full-x64 do not need entries here.

private_subnet_ids

  • Type: list(string)
  • Default: []
  • Description: Private subnet IDs used for Fargate and runners when private_mode is enabled.

security_group_ids

  • Type: list(string)
  • Default: []
  • Description: Security group IDs for runners and the Fleet worker. Leave empty to create a dedicated group.

private_mode

  • Type: string
  • Default: "false"
  • Allowed values: false, true, always, only
  • Description: Private networking mode: false, true, always, or only.

ssh_allowed

  • Type: bool
  • Default: true
  • Description: Allow SSH ingress when the module creates its own security group.

ssh_cidr_range

  • Type: string
  • Default: "0.0.0.0/0"
  • Description: CIDR range allowed for SSH access when the module creates its own security group.

cost_allocation_tag

  • Type: string
  • Default: "stack"
  • Description: Tag key used for cost allocation.

tags

  • Type: map(string)
  • Default: {}
  • Description: Additional tags applied to all created AWS resources.

runtime_image

  • Type: string
  • Default: "public.ecr.aws/c5h5o9k1/runs-on/runs-on:v3.1.0@sha256:55d023bc07480956a7bae4d2218f78fdf79ca0f8027da11efdad99589b8c9954"
  • Description: RunsOn worker image containing the fleetd binary. Override with a runs-on-ci image for live validation.

extra_env_vars

  • Type: map(string)
  • Default: {}
  • Description: Additional environment variables to set on the Fleet worker service.

integration_step_security_api_key

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: API key for StepSecurity integration (optional).

app_size

  • Type: string
  • Default: "small"
  • Allowed values: small, medium, high, xhigh
  • Description: Preset for the Fleet worker service, default EC2 launch concurrency, and default registration concurrency. Allowed values: small, medium, high, xhigh.

app_capacity_provider

  • Type: string
  • Default: "fargate"
  • Allowed values: fargate, fargate_spot
  • Description: Fargate capacity provider for the Fleet worker service. Use fargate_spot to lower idle cost for small installs; interrupted in-flight assigned jobs are reconciled by the Fleet runtime.

maintenance_mode

  • Type: bool
  • Default: false
  • Description: Enable maintenance mode (disables queue processing and leader election)

bootstrap_tag

  • Type: string
  • Default: "v0.1.17"
  • Description: Bootstrap release tag used by the shared compute bootstrap template.

app_tag

  • Type: string
  • Default: "v3.1.0"
  • Description: Application/agent tag published into the cache bucket and passed to runners.

runner_max_runtime

  • Type: number
  • Default: 60
  • Description: Maximum runtime in minutes passed to the shared compute bootstrap template.

cache_expiration_days

  • Type: number
  • Default: 10
  • Description: Number of days to retain cache artifacts.

cache_bucket_namespace

  • Type: string
  • Default: "global"
  • Allowed values: global, account-regional
  • Description: S3 namespace for the cache bucket. Use account-regional when an organization SCP requires account-regional S3 bucket names.

force_destroy_buckets

  • Type: bool
  • Default: false
  • Description: Allow the cache bucket to be destroyed while non-empty.

ecr_pull_through_cache_rules

  • Type: map(object({ ecr_repository_prefix = string upstream_registry_url = string upstream_repository_prefix = optional(string) }))
  • Default: {}
  • Description: Existing ECR pull-through cache rules to reference for Fleet runner image pulls. Create or import the regional rules outside the RunsOn module.

log_retention_days

  • Type: number
  • Default: 7
  • Allowed values: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653
  • Description: CloudWatch Logs retention in days.

permission_boundary_arn

  • Type: string
  • Default: ""
  • Description: Optional IAM permission boundary ARN applied to created roles.

runner_custom_policy_arn

  • Type: string
  • Default: ""
  • Description: Optional managed policy attached to the EC2 runner role.

enable_bedrock

  • Type: bool
  • Default: false
  • Description: Enable Amazon Bedrock access for EC2 runner instances.

ipv6_enabled

  • Type: bool
  • Default: false
  • Description: Enable IPv6 on EC2 runner launch templates.

runner_custom_tags

  • Type: list(string)
  • Default: []
  • Description: Additional custom tags propagated to launched runner instances.