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.

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.

public_subnet_ids#

  • Type: list(string)
  • Default: []
  • Description: Public subnet IDs used for runners and Fargate. Required unless private_mode is “only”.

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: false
  • 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.3@sha256:4e464e38792a8838c2847a0c0393dba4f504065249b257d38f85df4bd7c81ce6"
  • 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.3"
  • 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.

cache_bucket_versioning_enabled#

  • Type: bool
  • Default: false
  • Description: Enable S3 object versioning for the cache bucket.

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.