self-host →

Flex Terraform inputs

Every input of the RunsOn Flex Terraform / OpenTofu module, with types, defaults, and allowed values.

The Terraform module ↗ (runs-on/runs-on/aws//modules/flex) exposes the inputs below. It also works with OpenTofu ↗. Setup steps are in Install Flex.

The module deploys into an existing VPC, so vpc_id and public_subnet_ids are required. It also covers setups the CloudFormation stack does not, such as GHES and IAM permission boundaries. Input names differ from the CloudFormation parameters: app_size instead of AppSize, for example.

To change a value, edit the input in your Terraform configuration and re-apply, as described in Upgrades.

Required inputs#

github_organization#

  • Type: string
  • Required: yes
  • Description: GitHub organization or username for RunsOn integration

license_key#

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

vpc_id#

  • Type: string
  • Required: yes
  • Description: VPC ID where RunsOn infrastructure will be deployed

public_subnet_ids#

  • Type: list(string)
  • Required: yes
  • Description: List of public subnet IDs for runner instances. Required unless private_mode is “only”.

email#

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

Optional inputs#

stack_name#

  • Type: string
  • Default: "runs-on"
  • Description: Name for the RunsOn stack (used for resource naming)

environment#

  • Type: string
  • Default: "production"
  • Description: Environment name used for resource tagging and RunsOn job filtering. RunsOn will only process jobs with an ‘env’ label matching this value. See https://runs-on.com/configuration/environments/ ↗ for details.

cost_allocation_tag#

  • Type: string
  • Default: "stack"
  • Description: Name of the tag key used for cost allocation and tracking

tags#

  • Type: map(string)
  • Default: {}
  • Description: Tags to apply to all resources. Note: ‘runs-on-stack-name’ is added automatically for resource discovery.

github_enterprise_url#

  • Type: string
  • Default: ""
  • Description: GitHub Enterprise web URL for GHE.com data residency or GitHub Enterprise Server (optional, leave empty for github.com)

private_subnet_ids#

  • Type: list(string)
  • Default: []
  • Description: List of private subnet IDs for runner instances (required if private_mode is not ‘false’)

private_mode#

  • Type: string
  • Default: "false"
  • Allowed values: false, true, always, only
  • Description: Private networking mode: ‘false’ (disabled), ‘true’ (opt-in with label), ‘always’ (default with opt-out), ‘only’ (forced, no public option)

private_mode_delay#

  • Type: string
  • Default: "0s"
  • Description: Delay before starting the worker service in private mode, to allow NAT gateways to become ready. Set to ”60s” or higher for fresh NAT gateway deployments.

security_group_ids#

  • Type: list(string)
  • Default: []
  • Description: Security group IDs for runner instances and the worker service. If empty list provided, security groups will be created automatically.

ssh_allowed#

  • Type: bool
  • Default: false
  • Description: Allow SSH access to runner instances

ssm_allowed#

  • Type: bool
  • Default: true
  • Description: Enable SSM access for runner instances. When true, this attaches AmazonSSMManagedEC2InstanceDefaultPolicy to the runner instance role.

ssh_cidr_range#

  • Type: string
  • Default: "0.0.0.0/0"
  • Description: CIDR range allowed for SSH access to runner instances (only applies if ssh_allowed is true)

cache_expiration_days#

  • Type: number
  • Default: 10
  • Description: Number of days to retain cache artifacts in S3 before expiration

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 S3 buckets to be destroyed even when not empty. Set to false for production environments to prevent accidental data loss.

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: Number of days to retain CloudWatch logs for EC2 instances

permission_boundary_arn#

  • Type: string
  • Default: ""
  • Description: IAM permissions boundary ARN to attach to all IAM roles (optional)

ipv6_enabled#

  • Type: bool
  • Default: false
  • Description: Enable IPv6 support for runner instances

ebs_encryption_key_id#

  • Type: string
  • Default: ""
  • Description: KMS key ID for explicit EBS volume encryption. Leave empty to omit explicit EBS encryption fields, use alias/aws/ebs for the AWS-managed EBS key, or provide a customer-managed key ID, alias, or ARN. Prefer a full ARN for customer-managed keys, especially cross-account keys. Customer-managed keys must also trust the generated RunsOn worker task role in their key policy.

app_image#

  • Type: string
  • Default: "public.ecr.aws/c5h5o9k1/runs-on/runs-on:v3.3.2@sha256:53df89ebc3396f87b88790807fe6be04b01242bad0c52122fab9795690d18533"
  • Description: Container image for the RunsOn worker service. Published module releases inject a pinned public default during mirror publication.

app_tag#

  • Type: string
  • Default: "v3.3.2"
  • Description: Application version tag for RunsOn service. Published module releases inject the released default during mirror publication.

bootstrap_tag#

  • Type: string
  • Default: "v0.1.12"
  • Description: Bootstrap script version tag

maintenance_mode#

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

app_size#

  • Type: string
  • Default: "small"
  • Allowed values: small, medium, high, xhigh
  • Description: Preset for the 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 RunsOn worker service. Use fargate_spot to lower idle cost for small installs; interrupted in-flight queue messages retry after the SQS visibility timeout.

app_force_new_deployment#

  • Type: bool
  • Default: false
  • Description: Force a new ECS deployment of the RunsOn control-plane service. Set to true for one apply when migrating existing installs across the v3.0.6 ECS capacity provider change or when changing app_capacity_provider.

app_ecr_repository_url#

  • Type: string
  • Default: ""
  • Description: Private ECR repository URL for RunsOn image (e.g., 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:tag). When specified, the worker service will pull from this private ECR instead of public ECR.

app_custom_policy_arns#

  • Type: list(string)
  • Default: []
  • Description: Optional managed IAM policy ARNs to attach to the RunsOn service role.

github_app_id#

  • Type: number
  • Default: null
  • Description: GitHub App ID. If provided along with other github_app_* variables, creates a Secrets Manager secret and skips the web-based GitHub App setup flow.

github_app_private_key#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: GitHub App private key (PEM format)

github_app_webhook_secret#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: GitHub App webhook secret

github_app_client_id#

  • Type: string
  • Default: ""
  • Description: GitHub App client ID

github_app_client_secret#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: GitHub App client secret

github_api_boost_apps#

  • Type: map(object({ github_app_id = number github_app_private_key = string github_app_client_id = string github_app_client_secret = string github_app_label = optional(string, "") }))
  • Default: {}
  • Sensitive: yes
  • Description: Additional same-org GitHub Apps used only for API boost capacity. These entries omit webhook secrets and are written under the shared GitHub apps secret.

github_api_strategy#

  • Type: string
  • Default: "normal"
  • Allowed values: normal, conservative
  • Description: Strategy for GitHub API calls (normal, conservative)

runner_max_runtime#

  • Type: number
  • Default: 720
  • Description: Maximum runtime in minutes for runners before forced termination

runner_custom_policy_arns#

  • Type: list(string)
  • Default: []
  • Description: Optional managed IAM policy ARNs to attach to the EC2 runner instance role. Use this when policy ARNs are computed by other resources.

runner_config_auto_extends_from#

  • Type: string
  • Default: ".github-private"
  • Description: Auto-extend runner configuration from this base config

runner_custom_tags#

  • Type: list(string)
  • Default: []
  • Description: Custom tags to apply to runner instances (comma-separated list)

enable_cost_reports#

  • Type: string
  • Default: "daily"
  • Allowed values: no, daily, weekly, monthly
  • Description: Cost report email cadence: no, daily, weekly, or monthly. Legacy true/false values must be replaced with daily/no when upgrading.

spot_circuit_breaker#

  • Type: string
  • Default: "2/15/30"
  • Description: Spot instance circuit breaker configuration (e.g., ‘2/15/30’ = 2 failures in 15min, block for 30min)

app_budget_daily_usd#

  • Type: number
  • Default: 10
  • Description: Daily AWS cost budget in USD for this stack, filtered by the configured cost allocation tag. Set to 0 to disable the budget. For AWS Organizations member accounts, activate the cost allocation tag in the management account’s Billing settings.

enable_default_dashboard#

  • Type: bool
  • Default: true
  • Description: Create the default RunsOn CloudWatch dashboard. Set to false when managing a custom dashboard separately.

integration_step_security_api_key#

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

otel_exporter_endpoint#

  • Type: string
  • Default: ""
  • Description: OpenTelemetry exporter endpoint for observability (optional)

otel_exporter_headers#

  • Type: string
  • Default: ""
  • Sensitive: yes
  • Description: OpenTelemetry exporter headers (optional)

otel_exporter_temporality#

  • Type: string
  • Default: "cumulative"
  • Allowed values: cumulative, delta
  • Description: OTLP metrics temporality: cumulative (default) or delta

otel_logs_enabled#

  • Type: bool
  • Default: true
  • Description: Enable OpenTelemetry log export

otel_traces_enabled#

  • Type: bool
  • Default: true
  • Description: Enable OpenTelemetry trace export

logger_level#

  • Type: string
  • Default: "info"
  • Allowed values: debug, info, warn, error
  • Description: Logging level for RunsOn service (debug, info, warn, error)

extra_env_vars#

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

alert_slack_webhook_url#

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

mandatory_extras#

  • Type: list(string)
  • Default: []
  • Description: Runner extras (e.g. s3-cache, otel) that are always enabled for every runner, regardless of label or repo config overrides.

enable_efs#

  • Type: bool
  • Default: false
  • Description: Enable EFS file system for shared storage across runners

enable_ecr#

  • Type: bool
  • Default: false
  • Description: Enable ECR repository for ephemeral Docker image storage

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 runner image pulls. Create or import the regional rules outside the RunsOn module.

enable_bedrock#

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

prevent_destroy_optional_resources#

  • Type: bool
  • Default: true
  • Description: Prevent destruction of durable optional resources such as EFS. ECR contains ephemeral runner images and is force-deleted by default.

enable_waf#

  • Type: bool
  • Default: false
  • Description: Enable AWS WAF for the public ingress

enable_admin_routes#

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

public_ingress_web_acl_arn#

  • Type: string
  • Default: ""
  • Description: Optional user-managed AWS WAFv2 Web ACL ARN to associate with the public ingress. When set, RunsOn will not manage webhook IP synchronization.

enable_cache_isolation#

  • Type: bool
  • Default: false
  • Description: Enable brokered, per-repository/per-branch credentials for Magic Cache data under scoped-cache/. Direct S3 cache integrations keep instance-profile access to the stack-shared cache/ namespace and are not repository-isolated. Opt-in

enable_stickydisk_isolation#

  • Type: bool
  • Default: false
  • Description: Remove the legacy EBS volume/snapshot permissions from the runner instance role, so all sticky-disk EBS operations happen exclusively on the control plane. Breaks the legacy v1 runs-on/snapshot action. Opt-in