From a675bd2dc0f70886612c0c6d09fcf332456cefa5 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 4 Dec 2025 14:45:34 +0100
Subject: [PATCH 01/46] feat: add support to use custom scale errors

---
 .../control-plane/src/aws/runners.d.ts        |  2 +-
 .../control-plane/src/aws/runners.test.ts     | 15 ++++++++--
 .../control-plane/src/aws/runners.ts          | 18 ++++++++++-
 .../functions/control-plane/src/pool/pool.ts  |  2 +-
 .../src/scale-runners/scale-up.test.ts        | 13 ++++----
 .../src/scale-runners/scale-up.ts             |  4 +--
 main.tf                                       |  2 +-
 modules/multi-runner/runners.tf               |  2 +-
 modules/multi-runner/variables.tf             | 30 +++++++------------
 modules/runners/pool.tf                       |  2 +-
 modules/runners/pool/variables.tf             |  2 +-
 modules/runners/scale-up.tf                   |  2 +-
 modules/runners/variables.tf                  | 16 ++--------
 13 files changed, 58 insertions(+), 52 deletions(-)

diff --git a/lambdas/functions/control-plane/src/aws/runners.d.ts b/lambdas/functions/control-plane/src/aws/runners.d.ts
index f57652d491..e5b4e67d80 100644
--- a/lambdas/functions/control-plane/src/aws/runners.d.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.d.ts
@@ -69,5 +69,5 @@ export interface RunnerInputParameters {
   amiIdSsmParameterName?: string;
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
-  scaleErrors: string[];
+  customScaleErrors?: string[];
 }
diff --git a/lambdas/functions/control-plane/src/aws/runners.test.ts b/lambdas/functions/control-plane/src/aws/runners.test.ts
index 2f1b05792e..7dd69765a6 100644
--- a/lambdas/functions/control-plane/src/aws/runners.test.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.test.ts
@@ -717,6 +717,17 @@ describe('create runner with errors', () => {
     expect(mockSSMClient).not.toHaveReceivedCommand(PutParameterCommand);
   });
 
+  it('test ScaleError with custom scale error.', async () => {
+    createFleetMockWithErrors(['CustomAWSError']);
+    
+    await expect(createRunner(createRunnerConfig({ ...defaultRunnerConfig, customScaleErrors: ['CustomAWSError'] }))).rejects.toBeInstanceOf(ScaleError);
+    expect(mockEC2Client).toHaveReceivedCommandWith(
+      CreateFleetCommand,
+      expectedCreateFleetRequest(defaultExpectedFleetRequestValues),
+    );
+    expect(mockSSMClient).not.toHaveReceivedCommand(PutParameterCommand);
+  });
+
   it('test ScaleError with multiple error.', async () => {
     createFleetMockWithErrors(['UnfulfillableCapacity', 'MaxSpotInstanceCountExceeded', 'NotMappedError']);
 
@@ -962,7 +973,7 @@ interface RunnerConfig {
   amiIdSsmParameterName?: string;
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
-  scaleErrors: string[];
+  customScaleErrors?: string[];
   source: LambdaRunnerSource;
 }
 
@@ -983,7 +994,7 @@ function createRunnerConfig(runnerConfig: RunnerConfig): RunnerInputParameters {
     amiIdSsmParameterName: runnerConfig.amiIdSsmParameterName,
     tracingEnabled: runnerConfig.tracingEnabled,
     onDemandFailoverOnError: runnerConfig.onDemandFailoverOnError,
-    scaleErrors: runnerConfig.scaleErrors,
+    customScaleErrors: runnerConfig.customScaleErrors,
     source: runnerConfig.source,
   };
 }
diff --git a/lambdas/functions/control-plane/src/aws/runners.ts b/lambdas/functions/control-plane/src/aws/runners.ts
index 61edf99af6..3f9b921359 100644
--- a/lambdas/functions/control-plane/src/aws/runners.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.ts
@@ -205,8 +205,24 @@ async function processFleetResult(
     return instances;
   }
 
-  const scaleErrors = runnerParameters.scaleErrors;
+  // Educated guess of errors that would make sense to retry based on the list
+  // https://docs.aws.amazon.com/AWSEC2/latest/APIReference/errors-overview.html
+  const defaultScaleErrors = [
+    'UnfulfillableCapacity',
+    'MaxSpotInstanceCountExceeded',
+    'TargetCapacityLimitExceededException',
+    'RequestLimitExceeded',
+    'ResourceLimitExceeded',
+    'MaxSpotInstanceCountExceeded',
+    'MaxSpotFleetRequestCountExceeded',
+    'InsufficientInstanceCapacity',
+  ];
 
+  const scaleErrors =
+      runnerParameters.customScaleErrors && runnerParameters.customScaleErrors.length > 0
+        ? runnerParameters.customScaleErrors
+        : defaultScaleErrors;
+  
   const failedCount = countScaleErrors(errors, scaleErrors);
   if (failedCount > 0) {
     logger.warn('Create fleet failed, ScaleError will be thrown to trigger retry for ephemeral runners.');
diff --git a/lambdas/functions/control-plane/src/pool/pool.ts b/lambdas/functions/control-plane/src/pool/pool.ts
index cece8d9951..b370e2e4b7 100644
--- a/lambdas/functions/control-plane/src/pool/pool.ts
+++ b/lambdas/functions/control-plane/src/pool/pool.ts
@@ -102,7 +102,7 @@ export async function adjust(event: PoolEvent): Promise<void> {
         amiIdSsmParameterName,
         tracingEnabled,
         onDemandFailoverOnError,
-        scaleErrors,
+        customScaleErrors
       },
       topUp,
       githubInstallationClient,
diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
index 2245f29b90..fa2bca6cc4 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
@@ -112,8 +112,8 @@ const EXPECTED_RUNNER_PARAMS: RunnerInputParameters = {
   subnets: ['subnet-123'],
   tracingEnabled: false,
   onDemandFailoverOnError: [],
-  scaleErrors: ['UnfulfillableCapacity', 'MaxSpotInstanceCountExceeded', 'TargetCapacityLimitExceededException'],
-  source: 'scale-up-lambda',
+  customScaleErrors: [],
+  source: 'scale-up-lambda',  
 };
 let expectedRunnerParams: RunnerInputParameters;
 
@@ -131,8 +131,7 @@ function setDefaults() {
   process.env.INSTANCE_TYPES = 'm5.large';
   process.env.INSTANCE_TARGET_CAPACITY_TYPE = 'spot';
   process.env.ENABLE_ON_DEMAND_FAILOVER = undefined;
-  process.env.SCALE_ERRORS =
-    '["UnfulfillableCapacity","MaxSpotInstanceCountExceeded","TargetCapacityLimitExceededException"]';
+  process.env.CUSTOM_SCALE_ERRORS = undefined;
 }
 
 beforeEach(() => {
@@ -1354,11 +1353,11 @@ describe('scaleUp with public GH', () => {
 
     it('creates a runner with correct config and labels and custom scale errors enabled.', async () => {
       process.env.RUNNER_LABELS = 'label1,label2';
-      process.env.SCALE_ERRORS = JSON.stringify(['RequestLimitExceeded']);
-      await scaleUpModule.scaleUp(TEST_DATA);
+      process.env.CUSTOM_SCALE_ERRORS = JSON.stringify(['RequestLimitExceeded']);
+      await scaleUpModule.scaleUp('aws:sqs', TEST_DATA);
       expect(createRunner).toBeCalledWith({
         ...expectedRunnerParams,
-        scaleErrors: ['RequestLimitExceeded'],
+        customScaleErrors: ['RequestLimitExceeded'],
       });
     });
 
diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
index b51731f180..6756d9792d 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
@@ -98,7 +98,7 @@ interface CreateEC2RunnerConfig {
   amiIdSsmParameterName?: string;
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
-  scaleErrors: string[];
+  customScaleErrors?: string[];
 }
 
 function generateRunnerServiceConfig(githubRunnerConfig: CreateGitHubRunnerConfig, token: string) {
@@ -582,7 +582,7 @@ export async function scaleUp(payloads: ActionRequestMessageSQS[]): Promise<stri
         amiIdSsmParameterName,
         tracingEnabled,
         onDemandFailoverOnError,
-        scaleErrors,
+        customScaleErrors,
       },
       newRunners,
       githubInstallationClient,
diff --git a/main.tf b/main.tf
index 63b5725d06..6f5dd62421 100644
--- a/main.tf
+++ b/main.tf
@@ -190,7 +190,7 @@ module "runners" {
   enable_job_queued_check              = var.enable_job_queued_check
   enable_jit_config                    = var.enable_jit_config
   enable_on_demand_failover_for_errors = var.enable_runner_on_demand_failover_for_errors
-  scale_errors                         = var.scale_errors
+  ccustom_scale_errors                 = var.custom_scale_errors
   disable_runner_autoupdate            = var.disable_runner_autoupdate
   enable_managed_runner_security_group = var.enable_managed_runner_security_group
   enable_runner_detailed_monitoring    = var.enable_runner_detailed_monitoring
diff --git a/modules/multi-runner/runners.tf b/modules/multi-runner/runners.tf
index 32251eb1bc..b60801cba8 100644
--- a/modules/multi-runner/runners.tf
+++ b/modules/multi-runner/runners.tf
@@ -32,7 +32,7 @@ module "runners" {
   github_app_parameters                = local.github_app_parameters
   ebs_optimized                        = each.value.runner_config.ebs_optimized
   enable_on_demand_failover_for_errors = each.value.runner_config.enable_on_demand_failover_for_errors
-  scale_errors                         = each.value.runner_config.scale_errors
+  custom_scale_errors                  = each.value.runner_config.custom_scale_errors
   enable_organization_runners          = each.value.runner_config.enable_organization_runners
   enable_ephemeral_runners             = each.value.runner_config.enable_ephemeral_runners
   enable_dynamic_labels                = var.enable_dynamic_labels
diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index 191f60fd28..94f75ea090 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -71,25 +71,15 @@ variable "multi_runner_config" {
         id_ssm_parameter_arn = optional(string, null)
         kms_key_arn          = optional(string, null)
       }), null)
-      create_service_linked_role_spot      = optional(bool, false)
-      credit_specification                 = optional(string, null)
-      delay_webhook_event                  = optional(number, 30)
-      disable_runner_autoupdate            = optional(bool, false)
-      ebs_optimized                        = optional(bool, false)
-      enable_ephemeral_runners             = optional(bool, false)
-      enable_job_queued_check              = optional(bool, null)
-      enable_on_demand_failover_for_errors = optional(list(string), [])
-      scale_errors = optional(list(string), [
-        "UnfulfillableCapacity",
-        "MaxSpotInstanceCountExceeded",
-        "TargetCapacityLimitExceededException",
-        "RequestLimitExceeded",
-        "ResourceLimitExceeded",
-        "MaxSpotInstanceCountExceeded",
-        "MaxSpotFleetRequestCountExceeded",
-        "InsufficientInstanceCapacity",
-        "InsufficientCapacityOnHost",
-      ])
+      create_service_linked_role_spot         = optional(bool, false)
+      credit_specification                    = optional(string, null)
+      delay_webhook_event                     = optional(number, 30)
+      disable_runner_autoupdate               = optional(bool, false)
+      ebs_optimized                           = optional(bool, false)
+      enable_ephemeral_runners                = optional(bool, false)
+      enable_job_queued_check                 = optional(bool, null)
+      enable_on_demand_failover_for_errors    = optional(list(string), [])
+      custom_scale_errors                     = optional(list(string), [])
       enable_organization_runners             = optional(bool, false)
       enable_runner_binaries_syncer           = optional(bool, true)
       enable_ssm_on_runners                   = optional(bool, false)
@@ -212,7 +202,7 @@ variable "multi_runner_config" {
         enable_dynamic_labels: "Experimental! Can be removed / changed without trigger a major release. Enable dynamic labels with 'ghr-' prefix. When enabled, jobs can use 'ghr-ec2-<config>:<value>' labels to dynamically configure EC2 instances (e.g., 'ghr-ec2-instance-type:t3.large') and 'ghr-run-<label>' to add unique labels dynamically to runners."
         enable_job_queued_check: Enables JIT configuration for creating runners instead of registration token based registraton. JIT configuration will only be applied for ephemeral runners. By default JIT configuration is enabled for ephemeral runners an can be disabled via this override. When running on GHES without support for JIT configuration this variable should be set to true for ephemeral runners."
         enable_on_demand_failover_for_errors: "Enable on-demand failover. For example to fall back to on demand when no spot capacity is available the variable can be set to `InsufficientInstanceCapacity`. When not defined the default behavior is to retry later."
-        scale_errors: "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"
+        custom_scale_errors: "List of custom aws error codes that should trigger retry during scale up."
         enable_organization_runners: "Register runners to organization, instead of repo level"
         enable_runner_binaries_syncer: "Option to disable the lambda to sync GitHub runner distribution, useful when using a pre-build AMI."
         enable_ssm_on_runners: "Enable to allow access the runner instances for debugging purposes via SSM. Note that this adds additional permissions to the runner instances."
diff --git a/modules/runners/pool.tf b/modules/runners/pool.tf
index 53c5d1c2cd..28fa6b2ea6 100644
--- a/modules/runners/pool.tf
+++ b/modules/runners/pool.tf
@@ -44,7 +44,7 @@ module "pool" {
       ephemeral                            = var.enable_ephemeral_runners
       enable_jit_config                    = var.enable_jit_config
       enable_on_demand_failover_for_errors = var.enable_on_demand_failover_for_errors
-      scale_errors                         = var.scale_errors
+      custom_scale_errors                  = var.custom_scale_errors
       boot_time_in_minutes                 = var.runner_boot_time_in_minutes
       labels                               = var.runner_labels
       launch_template                      = aws_launch_template.runner
diff --git a/modules/runners/pool/variables.tf b/modules/runners/pool/variables.tf
index 4bfdd68010..c397c2803f 100644
--- a/modules/runners/pool/variables.tf
+++ b/modules/runners/pool/variables.tf
@@ -34,7 +34,7 @@ variable "config" {
       ephemeral                            = bool
       enable_jit_config                    = bool
       enable_on_demand_failover_for_errors = list(string)
-      scale_errors                         = list(string)
+      custom_scale_errors                  = list(string)
       boot_time_in_minutes                 = number
       labels                               = list(string)
       launch_template = object({
diff --git a/modules/runners/scale-up.tf b/modules/runners/scale-up.tf
index d360520965..0999fca9f2 100644
--- a/modules/runners/scale-up.tf
+++ b/modules/runners/scale-up.tf
@@ -61,7 +61,7 @@ resource "aws_lambda_function" "scale_up" {
       SSM_PARAMETER_STORE_TAGS                 = local.parameter_store_tags
       SUBNET_IDS                               = join(",", var.subnet_ids)
       ENABLE_ON_DEMAND_FAILOVER_FOR_ERRORS     = jsonencode(var.enable_on_demand_failover_for_errors)
-      SCALE_ERRORS                             = jsonencode(var.scale_errors)
+      CUSTOM_SCALE_ERRORS                      = jsonencode(var.custom_scale_errors)
       JOB_RETRY_CONFIG                         = jsonencode(local.job_retry_config)
     }
   }
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index fbedc77f19..63f5f3333d 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -729,20 +729,10 @@ variable "enable_on_demand_failover_for_errors" {
   default     = []
 }
 
-variable "scale_errors" {
-  description = "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"
+variable "custom_scale_errors" {
+  description = "List of custom aws error codes that should trigger retry during scale up."
   type        = list(string)
-  default = [
-    "UnfulfillableCapacity",
-    "MaxSpotInstanceCountExceeded",
-    "TargetCapacityLimitExceededException",
-    "RequestLimitExceeded",
-    "ResourceLimitExceeded",
-    "MaxSpotInstanceCountExceeded",
-    "MaxSpotFleetRequestCountExceeded",
-    "InsufficientInstanceCapacity",
-    "InsufficientCapacityOnHost",
-  ]
+  default     = []
 }
 
 variable "lambda_tags" {

From 81f0095e4bc5d1f969c48cac32171081e6addc3c Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 4 Dec 2025 14:49:47 +0100
Subject: [PATCH 02/46] chore: update variable description

---
 modules/multi-runner/variables.tf | 2 +-
 modules/runners/variables.tf      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index 94f75ea090..5335a0a267 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -202,7 +202,7 @@ variable "multi_runner_config" {
         enable_dynamic_labels: "Experimental! Can be removed / changed without trigger a major release. Enable dynamic labels with 'ghr-' prefix. When enabled, jobs can use 'ghr-ec2-<config>:<value>' labels to dynamically configure EC2 instances (e.g., 'ghr-ec2-instance-type:t3.large') and 'ghr-run-<label>' to add unique labels dynamically to runners."
         enable_job_queued_check: Enables JIT configuration for creating runners instead of registration token based registraton. JIT configuration will only be applied for ephemeral runners. By default JIT configuration is enabled for ephemeral runners an can be disabled via this override. When running on GHES without support for JIT configuration this variable should be set to true for ephemeral runners."
         enable_on_demand_failover_for_errors: "Enable on-demand failover. For example to fall back to on demand when no spot capacity is available the variable can be set to `InsufficientInstanceCapacity`. When not defined the default behavior is to retry later."
-        custom_scale_errors: "List of custom aws error codes that should trigger retry during scale up."
+        custom_scale_errors: "List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"
         enable_organization_runners: "Register runners to organization, instead of repo level"
         enable_runner_binaries_syncer: "Option to disable the lambda to sync GitHub runner distribution, useful when using a pre-build AMI."
         enable_ssm_on_runners: "Enable to allow access the runner instances for debugging purposes via SSM. Note that this adds additional permissions to the runner instances."
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index 63f5f3333d..abd969dc7e 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -730,7 +730,7 @@ variable "enable_on_demand_failover_for_errors" {
 }
 
 variable "custom_scale_errors" {
-  description = "List of custom aws error codes that should trigger retry during scale up."
+  description = "List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"
   type        = list(string)
   default     = []
 }

From 5ca61387b6fa6003d682768f63bdede8893a54be Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 4 Dec 2025 14:56:34 +0100
Subject: [PATCH 03/46] fix: fix typo

---
 main.tf | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/main.tf b/main.tf
index 6f5dd62421..f74892a2dd 100644
--- a/main.tf
+++ b/main.tf
@@ -190,7 +190,7 @@ module "runners" {
   enable_job_queued_check              = var.enable_job_queued_check
   enable_jit_config                    = var.enable_jit_config
   enable_on_demand_failover_for_errors = var.enable_runner_on_demand_failover_for_errors
-  ccustom_scale_errors                 = var.custom_scale_errors
+  custom_scale_errors                  = var.custom_scale_errors
   disable_runner_autoupdate            = var.disable_runner_autoupdate
   enable_managed_runner_security_group = var.enable_managed_runner_security_group
   enable_runner_detailed_monitoring    = var.enable_runner_detailed_monitoring

From 73c5714c86bf07972d1f4277500e09d27f285f1e Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 4 Dec 2025 15:03:34 +0100
Subject: [PATCH 04/46] style: fix ts formating

---
 lambdas/functions/control-plane/src/aws/runners.test.ts | 6 ++++--
 lambdas/functions/control-plane/src/pool/pool.ts        | 2 +-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/lambdas/functions/control-plane/src/aws/runners.test.ts b/lambdas/functions/control-plane/src/aws/runners.test.ts
index 7dd69765a6..4512615541 100644
--- a/lambdas/functions/control-plane/src/aws/runners.test.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.test.ts
@@ -719,8 +719,10 @@ describe('create runner with errors', () => {
 
   it('test ScaleError with custom scale error.', async () => {
     createFleetMockWithErrors(['CustomAWSError']);
-    
-    await expect(createRunner(createRunnerConfig({ ...defaultRunnerConfig, customScaleErrors: ['CustomAWSError'] }))).rejects.toBeInstanceOf(ScaleError);
+
+    await expect(
+      createRunner(createRunnerConfig({ ...defaultRunnerConfig, customScaleErrors: ['CustomAWSError'] })),
+    ).rejects.toBeInstanceOf(ScaleError);
     expect(mockEC2Client).toHaveReceivedCommandWith(
       CreateFleetCommand,
       expectedCreateFleetRequest(defaultExpectedFleetRequestValues),
diff --git a/lambdas/functions/control-plane/src/pool/pool.ts b/lambdas/functions/control-plane/src/pool/pool.ts
index b370e2e4b7..4fd0b26368 100644
--- a/lambdas/functions/control-plane/src/pool/pool.ts
+++ b/lambdas/functions/control-plane/src/pool/pool.ts
@@ -102,7 +102,7 @@ export async function adjust(event: PoolEvent): Promise<void> {
         amiIdSsmParameterName,
         tracingEnabled,
         onDemandFailoverOnError,
-        customScaleErrors
+        customScaleErrors,
       },
       topUp,
       githubInstallationClient,

From 47743e4ccf3e2159263bc2aa9038415e0c6ccb8f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 15 Dec 2025 11:11:39 +0000
Subject: [PATCH 05/46] docs: auto update terraform docs

---
 README.md                 | 1 +
 modules/runners/README.md | 1 +
 2 files changed, 2 insertions(+)

diff --git a/README.md b/README.md
index d7b77ba3a5..ce27ba58d4 100644
--- a/README.md
+++ b/README.md
@@ -117,6 +117,7 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_block_device_mappings"></a> [block\_device\_mappings](#input\_block\_device\_mappings) | The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`. | <pre>list(object({<br/>    delete_on_termination = optional(bool, true)<br/>    device_name           = optional(string, "/dev/xvda")<br/>    encrypted             = optional(bool, true)<br/>    iops                  = optional(number)<br/>    kms_key_id            = optional(string)<br/>    snapshot_id           = optional(string)<br/>    throughput            = optional(number)<br/>    volume_size           = number<br/>    volume_type           = optional(string, "gp3")<br/>  }))</pre> | <pre>[<br/>  {<br/>    "volume_size": 30<br/>  }<br/>]</pre> | no |
 | <a name="input_cloudwatch_config"></a> [cloudwatch\_config](#input\_cloudwatch\_config) | (optional) Replaces the module's default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details. | `string` | `null` | no |
 | <a name="input_create_service_linked_role_spot"></a> [create\_service\_linked\_role\_spot](#input\_create\_service\_linked\_role\_spot) | (optional) create the service linked role for spot instances that is required by the scale-up lambda. | `bool` | `false` | no |
+| <a name="input_custom_scale_errors"></a> [custom\_scale\_errors](#input\_custom\_scale\_errors) | List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts | `list(string)` | `[]` | no |
 | <a name="input_delay_webhook_event"></a> [delay\_webhook\_event](#input\_delay\_webhook\_event) | The number of seconds the event accepted by the webhook is invisible on the queue before the scale up lambda will receive the event. | `number` | `30` | no |
 | <a name="input_disable_runner_autoupdate"></a> [disable\_runner\_autoupdate](#input\_disable\_runner\_autoupdate) | Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/) | `bool` | `false` | no |
 | <a name="input_enable_ami_housekeeper"></a> [enable\_ami\_housekeeper](#input\_enable\_ami\_housekeeper) | Option to disable the lambda to clean up old AMIs. | `bool` | `false` | no |
diff --git a/modules/runners/README.md b/modules/runners/README.md
index 1f3495be07..81bd2daf63 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -145,6 +145,7 @@ yarn run dist
 | <a name="input_cpu_options"></a> [cpu\_options](#input\_cpu\_options) | The CPU options for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#cpu-options for details. Note that not all instance types support CPU options, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#instance-cpu-options | <pre>object({<br/>    core_count       = number<br/>    threads_per_core = number<br/>  })</pre> | `null` | no |
 | <a name="input_create_service_linked_role_spot"></a> [create\_service\_linked\_role\_spot](#input\_create\_service\_linked\_role\_spot) | (optional) create the service linked role for spot instances that is required by the scale-up lambda. | `bool` | `false` | no |
 | <a name="input_credit_specification"></a> [credit\_specification](#input\_credit\_specification) | The credit option for CPU usage of a T instance. Can be unset, "standard" or "unlimited". | `string` | `null` | no |
+| <a name="input_custom_scale_errors"></a> [custom\_scale\_errors](#input\_custom\_scale\_errors) | List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts | `list(string)` | `[]` | no |
 | <a name="input_disable_runner_autoupdate"></a> [disable\_runner\_autoupdate](#input\_disable\_runner\_autoupdate) | Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/) | `bool` | `false` | no |
 | <a name="input_ebs_optimized"></a> [ebs\_optimized](#input\_ebs\_optimized) | The EC2 EBS optimized configuration. | `bool` | `false` | no |
 | <a name="input_egress_rules"></a> [egress\_rules](#input\_egress\_rules) | List of egress rules for the GitHub runner instances. | <pre>list(object({<br/>    cidr_blocks      = list(string)<br/>    ipv6_cidr_blocks = list(string)<br/>    prefix_list_ids  = list(string)<br/>    from_port        = number<br/>    protocol         = string<br/>    security_groups  = list(string)<br/>    self             = bool<br/>    to_port          = number<br/>    description      = string<br/>  }))</pre> | <pre>[<br/>  {<br/>    "cidr_blocks": [<br/>      "0.0.0.0/0"<br/>    ],<br/>    "description": null,<br/>    "from_port": 0,<br/>    "ipv6_cidr_blocks": [<br/>      "::/0"<br/>    ],<br/>    "prefix_list_ids": null,<br/>    "protocol": "-1",<br/>    "security_groups": null,<br/>    "self": null,<br/>    "to_port": 0<br/>  }<br/>]</pre> | no |

From 29a0498d3088412bacad298466d7b5a42dcb2b30 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Mon, 15 Dec 2025 12:20:57 +0100
Subject: [PATCH 06/46] style: fix formatting issue

---
 lambdas/functions/control-plane/src/aws/runners.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/lambdas/functions/control-plane/src/aws/runners.ts b/lambdas/functions/control-plane/src/aws/runners.ts
index 3f9b921359..ef9c8dc9ad 100644
--- a/lambdas/functions/control-plane/src/aws/runners.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.ts
@@ -219,10 +219,10 @@ async function processFleetResult(
   ];
 
   const scaleErrors =
-      runnerParameters.customScaleErrors && runnerParameters.customScaleErrors.length > 0
-        ? runnerParameters.customScaleErrors
-        : defaultScaleErrors;
-  
+    runnerParameters.customScaleErrors && runnerParameters.customScaleErrors.length > 0
+      ? runnerParameters.customScaleErrors
+      : defaultScaleErrors;
+
   const failedCount = countScaleErrors(errors, scaleErrors);
   if (failedCount > 0) {
     logger.warn('Create fleet failed, ScaleError will be thrown to trigger retry for ephemeral runners.');

From 3c71fffe789b0b0741b9ff414c01fa3975ba1f66 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Mon, 15 Dec 2025 12:25:54 +0100
Subject: [PATCH 07/46] test: fix test after rebase

---
 .../functions/control-plane/src/scale-runners/scale-up.test.ts  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
index fa2bca6cc4..6123417f86 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
@@ -1354,7 +1354,7 @@ describe('scaleUp with public GH', () => {
     it('creates a runner with correct config and labels and custom scale errors enabled.', async () => {
       process.env.RUNNER_LABELS = 'label1,label2';
       process.env.CUSTOM_SCALE_ERRORS = JSON.stringify(['RequestLimitExceeded']);
-      await scaleUpModule.scaleUp('aws:sqs', TEST_DATA);
+      await scaleUpModule.scaleUp(TEST_DATA);
       expect(createRunner).toBeCalledWith({
         ...expectedRunnerParams,
         customScaleErrors: ['RequestLimitExceeded'],

From 4cfde09b5fdc93177729d51c30cd6622def73ae8 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Tue, 16 Dec 2025 10:29:21 +0100
Subject: [PATCH 08/46] fix: missing property in NodeJS

---
 lambdas/functions/control-plane/src/modules.d.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lambdas/functions/control-plane/src/modules.d.ts b/lambdas/functions/control-plane/src/modules.d.ts
index ff447c0e51..f1a3164637 100644
--- a/lambdas/functions/control-plane/src/modules.d.ts
+++ b/lambdas/functions/control-plane/src/modules.d.ts
@@ -3,7 +3,7 @@ declare namespace NodeJS {
     AWS_REGION: string;
     ENABLE_METRIC_GITHUB_APP_RATE_LIMIT: string;
     ENABLE_ON_DEMAND_FAILOVER_FOR_ERRORS: string;
-    SCALE_ERRORS: string;
+    CUSTOM_SCALE_ERRORS: string;
     ENVIRONMENT: string;
     GHES_URL: string;
     JOB_RETRY_CONFIG: string;

From b82a47acce20dc0ddcfc414845f7802de0af19c1 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 18 Dec 2025 23:11:16 +0100
Subject: [PATCH 09/46] refactor: remove custom friom variable and add default
 values

---
 README.md                                     |  2 +-
 .../control-plane/src/aws/runners.d.ts        |  2 +-
 .../control-plane/src/aws/runners.test.ts     | 19 ++----------
 .../control-plane/src/aws/runners.ts          | 18 +----------
 .../functions/control-plane/src/modules.d.ts  |  2 +-
 .../functions/control-plane/src/pool/pool.ts  |  2 +-
 .../src/scale-runners/scale-up.test.ts        | 11 +++----
 .../src/scale-runners/scale-up.ts             |  4 +--
 main.tf                                       |  2 +-
 modules/multi-runner/runners.tf               |  2 +-
 modules/multi-runner/variables.tf             | 30 ++++++++++++-------
 modules/runners/README.md                     |  2 +-
 modules/runners/pool.tf                       |  2 +-
 modules/runners/pool/variables.tf             |  2 +-
 modules/runners/scale-up.tf                   |  2 +-
 modules/runners/variables.tf                  | 16 ++++++++--
 16 files changed, 55 insertions(+), 63 deletions(-)

diff --git a/README.md b/README.md
index ce27ba58d4..3466862548 100644
--- a/README.md
+++ b/README.md
@@ -117,7 +117,7 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_block_device_mappings"></a> [block\_device\_mappings](#input\_block\_device\_mappings) | The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`. | <pre>list(object({<br/>    delete_on_termination = optional(bool, true)<br/>    device_name           = optional(string, "/dev/xvda")<br/>    encrypted             = optional(bool, true)<br/>    iops                  = optional(number)<br/>    kms_key_id            = optional(string)<br/>    snapshot_id           = optional(string)<br/>    throughput            = optional(number)<br/>    volume_size           = number<br/>    volume_type           = optional(string, "gp3")<br/>  }))</pre> | <pre>[<br/>  {<br/>    "volume_size": 30<br/>  }<br/>]</pre> | no |
 | <a name="input_cloudwatch_config"></a> [cloudwatch\_config](#input\_cloudwatch\_config) | (optional) Replaces the module's default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details. | `string` | `null` | no |
 | <a name="input_create_service_linked_role_spot"></a> [create\_service\_linked\_role\_spot](#input\_create\_service\_linked\_role\_spot) | (optional) create the service linked role for spot instances that is required by the scale-up lambda. | `bool` | `false` | no |
-| <a name="input_custom_scale_errors"></a> [custom\_scale\_errors](#input\_custom\_scale\_errors) | List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts | `list(string)` | `[]` | no |
+| <a name="input_scale_errors"></a> [custom\_scale\_errors](#input\_custom\_scale\_errors) | List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts | `list(string)` | `[]` | no |
 | <a name="input_delay_webhook_event"></a> [delay\_webhook\_event](#input\_delay\_webhook\_event) | The number of seconds the event accepted by the webhook is invisible on the queue before the scale up lambda will receive the event. | `number` | `30` | no |
 | <a name="input_disable_runner_autoupdate"></a> [disable\_runner\_autoupdate](#input\_disable\_runner\_autoupdate) | Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/) | `bool` | `false` | no |
 | <a name="input_enable_ami_housekeeper"></a> [enable\_ami\_housekeeper](#input\_enable\_ami\_housekeeper) | Option to disable the lambda to clean up old AMIs. | `bool` | `false` | no |
diff --git a/lambdas/functions/control-plane/src/aws/runners.d.ts b/lambdas/functions/control-plane/src/aws/runners.d.ts
index e5b4e67d80..f57652d491 100644
--- a/lambdas/functions/control-plane/src/aws/runners.d.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.d.ts
@@ -69,5 +69,5 @@ export interface RunnerInputParameters {
   amiIdSsmParameterName?: string;
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
-  customScaleErrors?: string[];
+  scaleErrors: string[];
 }
diff --git a/lambdas/functions/control-plane/src/aws/runners.test.ts b/lambdas/functions/control-plane/src/aws/runners.test.ts
index 4512615541..1e3d10eb34 100644
--- a/lambdas/functions/control-plane/src/aws/runners.test.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.test.ts
@@ -717,19 +717,6 @@ describe('create runner with errors', () => {
     expect(mockSSMClient).not.toHaveReceivedCommand(PutParameterCommand);
   });
 
-  it('test ScaleError with custom scale error.', async () => {
-    createFleetMockWithErrors(['CustomAWSError']);
-
-    await expect(
-      createRunner(createRunnerConfig({ ...defaultRunnerConfig, customScaleErrors: ['CustomAWSError'] })),
-    ).rejects.toBeInstanceOf(ScaleError);
-    expect(mockEC2Client).toHaveReceivedCommandWith(
-      CreateFleetCommand,
-      expectedCreateFleetRequest(defaultExpectedFleetRequestValues),
-    );
-    expect(mockSSMClient).not.toHaveReceivedCommand(PutParameterCommand);
-  });
-
   it('test ScaleError with multiple error.', async () => {
     createFleetMockWithErrors(['UnfulfillableCapacity', 'MaxSpotInstanceCountExceeded', 'NotMappedError']);
 
@@ -975,7 +962,7 @@ interface RunnerConfig {
   amiIdSsmParameterName?: string;
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
-  customScaleErrors?: string[];
+  scaleErrors: string[];
   source: LambdaRunnerSource;
 }
 
@@ -996,8 +983,8 @@ function createRunnerConfig(runnerConfig: RunnerConfig): RunnerInputParameters {
     amiIdSsmParameterName: runnerConfig.amiIdSsmParameterName,
     tracingEnabled: runnerConfig.tracingEnabled,
     onDemandFailoverOnError: runnerConfig.onDemandFailoverOnError,
-    customScaleErrors: runnerConfig.customScaleErrors,
-    source: runnerConfig.source,
+    scaleErrors: runnerConfig.scaleErrors,
+    source: runnerConfig.source,    
   };
 }
 
diff --git a/lambdas/functions/control-plane/src/aws/runners.ts b/lambdas/functions/control-plane/src/aws/runners.ts
index ef9c8dc9ad..61edf99af6 100644
--- a/lambdas/functions/control-plane/src/aws/runners.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.ts
@@ -205,23 +205,7 @@ async function processFleetResult(
     return instances;
   }
 
-  // Educated guess of errors that would make sense to retry based on the list
-  // https://docs.aws.amazon.com/AWSEC2/latest/APIReference/errors-overview.html
-  const defaultScaleErrors = [
-    'UnfulfillableCapacity',
-    'MaxSpotInstanceCountExceeded',
-    'TargetCapacityLimitExceededException',
-    'RequestLimitExceeded',
-    'ResourceLimitExceeded',
-    'MaxSpotInstanceCountExceeded',
-    'MaxSpotFleetRequestCountExceeded',
-    'InsufficientInstanceCapacity',
-  ];
-
-  const scaleErrors =
-    runnerParameters.customScaleErrors && runnerParameters.customScaleErrors.length > 0
-      ? runnerParameters.customScaleErrors
-      : defaultScaleErrors;
+  const scaleErrors = runnerParameters.scaleErrors;
 
   const failedCount = countScaleErrors(errors, scaleErrors);
   if (failedCount > 0) {
diff --git a/lambdas/functions/control-plane/src/modules.d.ts b/lambdas/functions/control-plane/src/modules.d.ts
index f1a3164637..ff447c0e51 100644
--- a/lambdas/functions/control-plane/src/modules.d.ts
+++ b/lambdas/functions/control-plane/src/modules.d.ts
@@ -3,7 +3,7 @@ declare namespace NodeJS {
     AWS_REGION: string;
     ENABLE_METRIC_GITHUB_APP_RATE_LIMIT: string;
     ENABLE_ON_DEMAND_FAILOVER_FOR_ERRORS: string;
-    CUSTOM_SCALE_ERRORS: string;
+    SCALE_ERRORS: string;
     ENVIRONMENT: string;
     GHES_URL: string;
     JOB_RETRY_CONFIG: string;
diff --git a/lambdas/functions/control-plane/src/pool/pool.ts b/lambdas/functions/control-plane/src/pool/pool.ts
index 4fd0b26368..cece8d9951 100644
--- a/lambdas/functions/control-plane/src/pool/pool.ts
+++ b/lambdas/functions/control-plane/src/pool/pool.ts
@@ -102,7 +102,7 @@ export async function adjust(event: PoolEvent): Promise<void> {
         amiIdSsmParameterName,
         tracingEnabled,
         onDemandFailoverOnError,
-        customScaleErrors,
+        scaleErrors,
       },
       topUp,
       githubInstallationClient,
diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
index 6123417f86..c9003c2e85 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
@@ -112,8 +112,8 @@ const EXPECTED_RUNNER_PARAMS: RunnerInputParameters = {
   subnets: ['subnet-123'],
   tracingEnabled: false,
   onDemandFailoverOnError: [],
-  customScaleErrors: [],
-  source: 'scale-up-lambda',  
+  scaleErrors: ['UnfulfillableCapacity', 'MaxSpotInstanceCountExceeded', 'TargetCapacityLimitExceededException'],
+  source: 'scale-up-lambda',    
 };
 let expectedRunnerParams: RunnerInputParameters;
 
@@ -131,7 +131,8 @@ function setDefaults() {
   process.env.INSTANCE_TYPES = 'm5.large';
   process.env.INSTANCE_TARGET_CAPACITY_TYPE = 'spot';
   process.env.ENABLE_ON_DEMAND_FAILOVER = undefined;
-  process.env.CUSTOM_SCALE_ERRORS = undefined;
+  process.env.SCALE_ERRORS =
+    '["UnfulfillableCapacity","MaxSpotInstanceCountExceeded","TargetCapacityLimitExceededException"]';
 }
 
 beforeEach(() => {
@@ -1353,11 +1354,11 @@ describe('scaleUp with public GH', () => {
 
     it('creates a runner with correct config and labels and custom scale errors enabled.', async () => {
       process.env.RUNNER_LABELS = 'label1,label2';
-      process.env.CUSTOM_SCALE_ERRORS = JSON.stringify(['RequestLimitExceeded']);
+      process.env.SCALE_ERRORS = JSON.stringify(['RequestLimitExceeded']);
       await scaleUpModule.scaleUp(TEST_DATA);
       expect(createRunner).toBeCalledWith({
         ...expectedRunnerParams,
-        customScaleErrors: ['RequestLimitExceeded'],
+        scaleErrors: ['RequestLimitExceeded'],
       });
     });
 
diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
index 6756d9792d..b51731f180 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
@@ -98,7 +98,7 @@ interface CreateEC2RunnerConfig {
   amiIdSsmParameterName?: string;
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
-  customScaleErrors?: string[];
+  scaleErrors: string[];
 }
 
 function generateRunnerServiceConfig(githubRunnerConfig: CreateGitHubRunnerConfig, token: string) {
@@ -582,7 +582,7 @@ export async function scaleUp(payloads: ActionRequestMessageSQS[]): Promise<stri
         amiIdSsmParameterName,
         tracingEnabled,
         onDemandFailoverOnError,
-        customScaleErrors,
+        scaleErrors,
       },
       newRunners,
       githubInstallationClient,
diff --git a/main.tf b/main.tf
index f74892a2dd..63b5725d06 100644
--- a/main.tf
+++ b/main.tf
@@ -190,7 +190,7 @@ module "runners" {
   enable_job_queued_check              = var.enable_job_queued_check
   enable_jit_config                    = var.enable_jit_config
   enable_on_demand_failover_for_errors = var.enable_runner_on_demand_failover_for_errors
-  custom_scale_errors                  = var.custom_scale_errors
+  scale_errors                         = var.scale_errors
   disable_runner_autoupdate            = var.disable_runner_autoupdate
   enable_managed_runner_security_group = var.enable_managed_runner_security_group
   enable_runner_detailed_monitoring    = var.enable_runner_detailed_monitoring
diff --git a/modules/multi-runner/runners.tf b/modules/multi-runner/runners.tf
index b60801cba8..32251eb1bc 100644
--- a/modules/multi-runner/runners.tf
+++ b/modules/multi-runner/runners.tf
@@ -32,7 +32,7 @@ module "runners" {
   github_app_parameters                = local.github_app_parameters
   ebs_optimized                        = each.value.runner_config.ebs_optimized
   enable_on_demand_failover_for_errors = each.value.runner_config.enable_on_demand_failover_for_errors
-  custom_scale_errors                  = each.value.runner_config.custom_scale_errors
+  scale_errors                         = each.value.runner_config.scale_errors
   enable_organization_runners          = each.value.runner_config.enable_organization_runners
   enable_ephemeral_runners             = each.value.runner_config.enable_ephemeral_runners
   enable_dynamic_labels                = var.enable_dynamic_labels
diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index 5335a0a267..191f60fd28 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -71,15 +71,25 @@ variable "multi_runner_config" {
         id_ssm_parameter_arn = optional(string, null)
         kms_key_arn          = optional(string, null)
       }), null)
-      create_service_linked_role_spot         = optional(bool, false)
-      credit_specification                    = optional(string, null)
-      delay_webhook_event                     = optional(number, 30)
-      disable_runner_autoupdate               = optional(bool, false)
-      ebs_optimized                           = optional(bool, false)
-      enable_ephemeral_runners                = optional(bool, false)
-      enable_job_queued_check                 = optional(bool, null)
-      enable_on_demand_failover_for_errors    = optional(list(string), [])
-      custom_scale_errors                     = optional(list(string), [])
+      create_service_linked_role_spot      = optional(bool, false)
+      credit_specification                 = optional(string, null)
+      delay_webhook_event                  = optional(number, 30)
+      disable_runner_autoupdate            = optional(bool, false)
+      ebs_optimized                        = optional(bool, false)
+      enable_ephemeral_runners             = optional(bool, false)
+      enable_job_queued_check              = optional(bool, null)
+      enable_on_demand_failover_for_errors = optional(list(string), [])
+      scale_errors = optional(list(string), [
+        "UnfulfillableCapacity",
+        "MaxSpotInstanceCountExceeded",
+        "TargetCapacityLimitExceededException",
+        "RequestLimitExceeded",
+        "ResourceLimitExceeded",
+        "MaxSpotInstanceCountExceeded",
+        "MaxSpotFleetRequestCountExceeded",
+        "InsufficientInstanceCapacity",
+        "InsufficientCapacityOnHost",
+      ])
       enable_organization_runners             = optional(bool, false)
       enable_runner_binaries_syncer           = optional(bool, true)
       enable_ssm_on_runners                   = optional(bool, false)
@@ -202,7 +212,7 @@ variable "multi_runner_config" {
         enable_dynamic_labels: "Experimental! Can be removed / changed without trigger a major release. Enable dynamic labels with 'ghr-' prefix. When enabled, jobs can use 'ghr-ec2-<config>:<value>' labels to dynamically configure EC2 instances (e.g., 'ghr-ec2-instance-type:t3.large') and 'ghr-run-<label>' to add unique labels dynamically to runners."
         enable_job_queued_check: Enables JIT configuration for creating runners instead of registration token based registraton. JIT configuration will only be applied for ephemeral runners. By default JIT configuration is enabled for ephemeral runners an can be disabled via this override. When running on GHES without support for JIT configuration this variable should be set to true for ephemeral runners."
         enable_on_demand_failover_for_errors: "Enable on-demand failover. For example to fall back to on demand when no spot capacity is available the variable can be set to `InsufficientInstanceCapacity`. When not defined the default behavior is to retry later."
-        custom_scale_errors: "List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"
+        scale_errors: "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"
         enable_organization_runners: "Register runners to organization, instead of repo level"
         enable_runner_binaries_syncer: "Option to disable the lambda to sync GitHub runner distribution, useful when using a pre-build AMI."
         enable_ssm_on_runners: "Enable to allow access the runner instances for debugging purposes via SSM. Note that this adds additional permissions to the runner instances."
diff --git a/modules/runners/README.md b/modules/runners/README.md
index 81bd2daf63..21623ced33 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -145,7 +145,7 @@ yarn run dist
 | <a name="input_cpu_options"></a> [cpu\_options](#input\_cpu\_options) | The CPU options for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#cpu-options for details. Note that not all instance types support CPU options, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#instance-cpu-options | <pre>object({<br/>    core_count       = number<br/>    threads_per_core = number<br/>  })</pre> | `null` | no |
 | <a name="input_create_service_linked_role_spot"></a> [create\_service\_linked\_role\_spot](#input\_create\_service\_linked\_role\_spot) | (optional) create the service linked role for spot instances that is required by the scale-up lambda. | `bool` | `false` | no |
 | <a name="input_credit_specification"></a> [credit\_specification](#input\_credit\_specification) | The credit option for CPU usage of a T instance. Can be unset, "standard" or "unlimited". | `string` | `null` | no |
-| <a name="input_custom_scale_errors"></a> [custom\_scale\_errors](#input\_custom\_scale\_errors) | List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts | `list(string)` | `[]` | no |
+| <a name="input_scale_errors"></a> [custom\_scale\_errors](#input\_custom\_scale\_errors) | List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts | `list(string)` | `[]` | no |
 | <a name="input_disable_runner_autoupdate"></a> [disable\_runner\_autoupdate](#input\_disable\_runner\_autoupdate) | Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/) | `bool` | `false` | no |
 | <a name="input_ebs_optimized"></a> [ebs\_optimized](#input\_ebs\_optimized) | The EC2 EBS optimized configuration. | `bool` | `false` | no |
 | <a name="input_egress_rules"></a> [egress\_rules](#input\_egress\_rules) | List of egress rules for the GitHub runner instances. | <pre>list(object({<br/>    cidr_blocks      = list(string)<br/>    ipv6_cidr_blocks = list(string)<br/>    prefix_list_ids  = list(string)<br/>    from_port        = number<br/>    protocol         = string<br/>    security_groups  = list(string)<br/>    self             = bool<br/>    to_port          = number<br/>    description      = string<br/>  }))</pre> | <pre>[<br/>  {<br/>    "cidr_blocks": [<br/>      "0.0.0.0/0"<br/>    ],<br/>    "description": null,<br/>    "from_port": 0,<br/>    "ipv6_cidr_blocks": [<br/>      "::/0"<br/>    ],<br/>    "prefix_list_ids": null,<br/>    "protocol": "-1",<br/>    "security_groups": null,<br/>    "self": null,<br/>    "to_port": 0<br/>  }<br/>]</pre> | no |
diff --git a/modules/runners/pool.tf b/modules/runners/pool.tf
index 28fa6b2ea6..53c5d1c2cd 100644
--- a/modules/runners/pool.tf
+++ b/modules/runners/pool.tf
@@ -44,7 +44,7 @@ module "pool" {
       ephemeral                            = var.enable_ephemeral_runners
       enable_jit_config                    = var.enable_jit_config
       enable_on_demand_failover_for_errors = var.enable_on_demand_failover_for_errors
-      custom_scale_errors                  = var.custom_scale_errors
+      scale_errors                         = var.scale_errors
       boot_time_in_minutes                 = var.runner_boot_time_in_minutes
       labels                               = var.runner_labels
       launch_template                      = aws_launch_template.runner
diff --git a/modules/runners/pool/variables.tf b/modules/runners/pool/variables.tf
index c397c2803f..4bfdd68010 100644
--- a/modules/runners/pool/variables.tf
+++ b/modules/runners/pool/variables.tf
@@ -34,7 +34,7 @@ variable "config" {
       ephemeral                            = bool
       enable_jit_config                    = bool
       enable_on_demand_failover_for_errors = list(string)
-      custom_scale_errors                  = list(string)
+      scale_errors                         = list(string)
       boot_time_in_minutes                 = number
       labels                               = list(string)
       launch_template = object({
diff --git a/modules/runners/scale-up.tf b/modules/runners/scale-up.tf
index 0999fca9f2..d360520965 100644
--- a/modules/runners/scale-up.tf
+++ b/modules/runners/scale-up.tf
@@ -61,7 +61,7 @@ resource "aws_lambda_function" "scale_up" {
       SSM_PARAMETER_STORE_TAGS                 = local.parameter_store_tags
       SUBNET_IDS                               = join(",", var.subnet_ids)
       ENABLE_ON_DEMAND_FAILOVER_FOR_ERRORS     = jsonencode(var.enable_on_demand_failover_for_errors)
-      CUSTOM_SCALE_ERRORS                      = jsonencode(var.custom_scale_errors)
+      SCALE_ERRORS                             = jsonencode(var.scale_errors)
       JOB_RETRY_CONFIG                         = jsonencode(local.job_retry_config)
     }
   }
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index abd969dc7e..fbedc77f19 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -729,10 +729,20 @@ variable "enable_on_demand_failover_for_errors" {
   default     = []
 }
 
-variable "custom_scale_errors" {
-  description = "List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"
+variable "scale_errors" {
+  description = "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"
   type        = list(string)
-  default     = []
+  default = [
+    "UnfulfillableCapacity",
+    "MaxSpotInstanceCountExceeded",
+    "TargetCapacityLimitExceededException",
+    "RequestLimitExceeded",
+    "ResourceLimitExceeded",
+    "MaxSpotInstanceCountExceeded",
+    "MaxSpotFleetRequestCountExceeded",
+    "InsufficientInstanceCapacity",
+    "InsufficientCapacityOnHost",
+  ]
 }
 
 variable "lambda_tags" {

From b03adcc36de06d7b32a002128795c5194a35fed8 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 3 Dec 2025 21:39:42 +0100
Subject: [PATCH 10/46] feat: add osx options

---
 examples/prebuilt/variables.tf              | 2 +-
 modules/multi-runner/variables.tf           | 4 ++--
 modules/runner-binaries-syncer/main.tf      | 2 +-
 modules/runner-binaries-syncer/variables.tf | 6 +++---
 modules/runners/main.tf                     | 4 ++++
 modules/runners/scale-down-state-diagram.md | 4 ++--
 modules/runners/scale-down.tf               | 3 +++
 modules/runners/variables.tf                | 8 ++++----
 variables.tf                                | 8 ++++----
 9 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/examples/prebuilt/variables.tf b/examples/prebuilt/variables.tf
index 643072a163..11670a5d2e 100644
--- a/examples/prebuilt/variables.tf
+++ b/examples/prebuilt/variables.tf
@@ -22,7 +22,7 @@ variable "aws_region" {
 }
 
 variable "runner_os" {
-  description = "The EC2 Operating System type to use for action runner instances (linux,windows)."
+  description = "The EC2 Operating System type to use for action runner instances (linux, osx, windows)."
 
   type    = string
   default = "linux"
diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index 191f60fd28..c2aea07196 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -199,7 +199,7 @@ variable "multi_runner_config" {
   description = <<EOT
     multi_runner_config = {
       runner_config: {
-        runner_os: "The EC2 Operating System type to use for action runner instances (linux,windows)."
+        runner_os: "The EC2 Operating System type to use for action runner instances (linux, osx, windows)."
         runner_architecture: "The platform architecture of the runner instance_type."
         runner_metadata_options: "(Optional) Metadata options for the ec2 runner instances."
         ami: "(Optional) AMI configuration for the action runner instances. This object allows you to specify all AMI-related settings in one place."
@@ -220,7 +220,7 @@ variable "multi_runner_config" {
         instance_allocation_strategy: "The allocation strategy for spot instances. AWS recommends to use `capacity-optimized` however the AWS default is `lowest-price`."
         instance_max_spot_price: "Max price price for spot instances per hour. This variable will be passed to the create fleet as max spot price for the fleet."
         instance_target_capacity_type: "Default lifecycle used for runner instances, can be either `spot` or `on-demand`."
-        instance_types: "List of instance types for the action runner. Defaults are based on runner_os (al2023 for linux and Windows Server Core for win)."
+        description: "List of instance types for the action runner. Defaults are based on runner_os (al2023 for linux, macOS Sequoia for osx, Windows Server Core for win)."
         job_queue_retention_in_seconds: "The number of seconds the job is held in the queue before it is purged"
         minimum_running_time_in_minutes: "The time an ec2 action runner should be running at minimum before terminated if not busy."
         pool_runner_owner: "The pool will deploy runners to the GitHub org ID, set this value to the org to which you want the runners deployed. Repo level is not supported."
diff --git a/modules/runner-binaries-syncer/main.tf b/modules/runner-binaries-syncer/main.tf
index c1cbf382af..2b1e212262 100644
--- a/modules/runner-binaries-syncer/main.tf
+++ b/modules/runner-binaries-syncer/main.tf
@@ -1,5 +1,5 @@
 locals {
-  action_runner_distribution_object_key = "actions-runner-${var.runner_os}.${var.runner_os == "linux" ? "tar.gz" : "zip"}"
+  action_runner_distribution_object_key = "actions-runner-${var.runner_os}.${var.runner_os == "windows" ? "zip" : "tar.gz"}"
 }
 
 resource "aws_s3_bucket" "action_dist" {
diff --git a/modules/runner-binaries-syncer/variables.tf b/modules/runner-binaries-syncer/variables.tf
index e274f043a2..b48e6da5fd 100644
--- a/modules/runner-binaries-syncer/variables.tf
+++ b/modules/runner-binaries-syncer/variables.tf
@@ -99,13 +99,13 @@ variable "role_path" {
 }
 
 variable "runner_os" {
-  description = "The EC2 Operating System type to use for action runner instances (linux,windows)."
+  description = "The EC2 Operating System type to use for action runner instances (linux, osx, windows)."
   type        = string
   default     = "linux"
 
   validation {
-    condition     = contains(["linux", "windows"], var.runner_os)
-    error_message = "Valid values for runner_os are (linux, windows)."
+    condition     = contains(["linux", "osx", "windows"], var.runner_os)
+    error_message = "Valid values for runner_os are (linux, osx, windows)."
   }
 }
 
diff --git a/modules/runners/main.tf b/modules/runners/main.tf
index e62b0bcd8f..408f05336c 100644
--- a/modules/runners/main.tf
+++ b/modules/runners/main.tf
@@ -20,21 +20,25 @@ locals {
   default_ami = {
     "windows" = { name = ["Windows_Server-2022-English-Full-ECS_Optimized-*"] }
     "linux"   = var.runner_architecture == "arm64" ? { name = ["al2023-ami-2023.*-kernel-6.*-arm64"] } : { name = ["al2023-ami-2023.*-kernel-6.*-x86_64"] }
+    "osx"     = var.runner_architecture == "arm64" ? { name = ["amzn-ec2-macos-15.*-arm64"] } : { name = ["amzn-ec2-macos-15.*"] }
   }
 
   default_userdata_template = {
     "windows" = "${path.module}/templates/user-data.ps1"
     "linux"   = "${path.module}/templates/user-data.sh"
+    "osx"     = "${path.module}/templates/user-data.sh"
   }
 
   userdata_install_runner = {
     "windows" = "${path.module}/templates/install-runner.ps1"
     "linux"   = "${path.module}/templates/install-runner.sh"
+    "osx"     = "${path.module}/templates/install-runner.sh"
   }
 
   userdata_start_runner = {
     "windows" = "${path.module}/templates/start-runner.ps1"
     "linux"   = "${path.module}/templates/start-runner.sh"
+    "osx"     = "${path.module}/templates/start-runner.sh"
   }
 
   # Handle AMI configuration
diff --git a/modules/runners/scale-down-state-diagram.md b/modules/runners/scale-down-state-diagram.md
index b4f260eb2a..64e32bc141 100644
--- a/modules/runners/scale-down-state-diagram.md
+++ b/modules/runners/scale-down-state-diagram.md
@@ -117,7 +117,7 @@ stateDiagram-v2
 
     note right of CheckMinimumTime
         Minimum running time in minutes
-        (Linux: 5min, Windows: 15min)
+        (Linux: 5min, Windows: 15min, OSX: 20min)
     end note
 
     note right of CheckBootTime
@@ -145,6 +145,6 @@ stateDiagram-v2
 ## Configuration Parameters
 
 - **Cron Schedule**: `cron(*/5 * * * ? *)` (every 5 minutes)
-- **Minimum Runtime**: Linux 5min, Windows 15min
+- **Minimum Runtime**: Linux 5min, Windows 15min, OSX 20min
 - **Boot Timeout**: Configurable via `runner_boot_time_in_minutes`
 - **Idle Config**: Per-environment configuration for desired idle runners
diff --git a/modules/runners/scale-down.tf b/modules/runners/scale-down.tf
index b304e8066e..bd5f75554b 100644
--- a/modules/runners/scale-down.tf
+++ b/modules/runners/scale-down.tf
@@ -1,8 +1,11 @@
 locals {
   # Windows Runners can take their sweet time to do anything
+  # For an AWS vended AMI with a x86 Mac instance or a Apple silicon Mac instance, 
+  # the launch time can range from approximately 6 minutes to 20 minutes. 
   min_runtime_defaults = {
     "windows" = 15
     "linux"   = 5
+    "osx"     = 20
   }
 }
 resource "aws_lambda_function" "scale_down" {
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index fbedc77f19..a2d24223d0 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -119,18 +119,18 @@ variable "instance_max_spot_price" {
 }
 
 variable "runner_os" {
-  description = "The EC2 Operating System type to use for action runner instances (linux,windows)."
+  description = "The EC2 Operating System type to use for action runner instances (linux, osx, windows)."
   type        = string
   default     = "linux"
 
   validation {
-    condition     = contains(["linux", "windows"], var.runner_os)
-    error_message = "Valid values for runner_os are (linux, windows)."
+    condition     = contains(["linux", "osx", "windows"], var.runner_os)
+    error_message = "Valid values for runner_os are (linux, osx, windows)."
   }
 }
 
 variable "instance_types" {
-  description = "List of instance types for the action runner. Defaults are based on runner_os (al2023 for linux and Windows Server Core for win)."
+  description = "List of instance types for the action runner. Defaults are based on runner_os (al2023 for linux, macOS Sequoia for osx, Windows Server Core for win)."
   type        = list(string)
   default     = null
 }
diff --git a/variables.tf b/variables.tf
index 474ae12ebd..75a825c348 100644
--- a/variables.tf
+++ b/variables.tf
@@ -570,7 +570,7 @@ variable "instance_max_spot_price" {
 }
 
 variable "instance_types" {
-  description = "List of instance types for the action runner. Defaults are based on runner_os (al2023 for linux and Windows Server Core for win)."
+  description = "List of instance types for the action runner. Defaults are based on runner_os (al2023 for linux, macOS Sequoia for osx, Windows Server Core for win)."
   type        = list(string)
   default     = ["m5.large", "c5.large"]
 }
@@ -692,13 +692,13 @@ variable "enable_managed_runner_security_group" {
 }
 
 variable "runner_os" {
-  description = "The EC2 Operating System type to use for action runner instances (linux,windows)."
+  description = "The EC2 Operating System type to use for action runner instances (linux, osx, windows)."
   type        = string
   default     = "linux"
 
   validation {
-    condition     = contains(["linux", "windows"], var.runner_os)
-    error_message = "Valid values for runner_os are (linux, windows)."
+    condition     = contains(["linux", "osx", "windows"], var.runner_os)
+    error_message = "Valid values for runner_os are (linux, osx, windows)."
   }
 }
 

From cd6b82a6aa659339305b3988e73638938918286f Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 3 Dec 2025 21:44:42 +0100
Subject: [PATCH 11/46] feat: create runner scripts for macos

---
 modules/runners/main.tf                       |   6 +-
 .../runners/templates/install-runner-osx.sh   |  60 ++++++
 modules/runners/templates/start-runner-osx.sh | 196 ++++++++++++++++++
 modules/runners/templates/user-data-osx.sh    |  43 ++++
 4 files changed, 302 insertions(+), 3 deletions(-)
 create mode 100644 modules/runners/templates/install-runner-osx.sh
 create mode 100644 modules/runners/templates/start-runner-osx.sh
 create mode 100644 modules/runners/templates/user-data-osx.sh

diff --git a/modules/runners/main.tf b/modules/runners/main.tf
index 408f05336c..0590f1b5ff 100644
--- a/modules/runners/main.tf
+++ b/modules/runners/main.tf
@@ -26,19 +26,19 @@ locals {
   default_userdata_template = {
     "windows" = "${path.module}/templates/user-data.ps1"
     "linux"   = "${path.module}/templates/user-data.sh"
-    "osx"     = "${path.module}/templates/user-data.sh"
+    "osx"     = "${path.module}/templates/user-data-osx.sh"
   }
 
   userdata_install_runner = {
     "windows" = "${path.module}/templates/install-runner.ps1"
     "linux"   = "${path.module}/templates/install-runner.sh"
-    "osx"     = "${path.module}/templates/install-runner.sh"
+    "osx"     = "${path.module}/templates/install-runner-osx.sh"
   }
 
   userdata_start_runner = {
     "windows" = "${path.module}/templates/start-runner.ps1"
     "linux"   = "${path.module}/templates/start-runner.sh"
-    "osx"     = "${path.module}/templates/start-runner.sh"
+    "osx"     = "${path.module}/templates/start-runner-osx.sh"
   }
 
   # Handle AMI configuration
diff --git a/modules/runners/templates/install-runner-osx.sh b/modules/runners/templates/install-runner-osx.sh
new file mode 100644
index 0000000000..893a62b098
--- /dev/null
+++ b/modules/runners/templates/install-runner-osx.sh
@@ -0,0 +1,60 @@
+# shellcheck shell=bash
+
+## install the runner (macOS)
+
+s3_location=${S3_LOCATION_RUNNER_DISTRIBUTION}
+architecture=${RUNNER_ARCHITECTURE}
+
+if [ -z "$RUNNER_TARBALL_URL" ] && [ -z "$s3_location" ]; then
+  echo "Neither RUNNER_TARBALL_URL or s3_location are set"
+  exit 1
+fi
+
+file_name="actions-runner.tar.gz"
+
+echo "Setting up GH Actions runner tool cache"
+mkdir -p /opt/hostedtoolcache
+
+echo "Creating actions-runner directory for the GH Action installation"
+sudo mkdir -p /opt/actions-runner
+cd /opt/actions-runner || exit 1
+
+if [[ -n "$RUNNER_TARBALL_URL" ]]; then
+  echo "Downloading the GH Action runner from $RUNNER_TARBALL_URL to $file_name"
+  curl -s -o "$file_name" -L "$RUNNER_TARBALL_URL"
+else
+  echo "Retrieving REGION from AWS API"
+  token="$(curl -s -f -X PUT "http://169.254.169.254/latest/api/token" \
+    -H "X-aws-ec2-metadata-token-ttl-seconds: 180")"
+
+  region="$(curl -s -f -H "X-aws-ec2-metadata-token: $token" \
+    http://169.254.169.254/latest/dynamic/instance-identity/document | jq -r .region)"
+  echo "Retrieved REGION from AWS API ($region)"
+
+  echo "Downloading the GH Action runner from s3 bucket $s3_location"
+  aws s3 cp "$s3_location" "$file_name" --region "$region" --no-progress
+fi
+
+echo "Un-tar action runner"
+tar xzf "./$file_name"
+echo "Delete tar file"
+rm -rf "$file_name"
+
+os_name=$(sw_vers -productName 2>/dev/null || echo "macOS")
+os_version=$(sw_vers -productVersion 2>/dev/null || echo "unknown")
+arch_name=$(uname -m)
+
+echo "OS: $os_name $os_version ($arch_name)"
+
+if ! command -v brew >/dev/null 2>&1; then
+  echo "Homebrew not found; skipping dependency installation via brew"
+else
+  echo "Homebrew detected; install any macOS-specific dependencies here if needed"
+  # Example: brew install jq awscli
+fi
+
+user_name="${RUNNER_USER:-ec2-user}"
+
+echo "Set file ownership of action runner"
+sudo chown -R "$user_name":"$user_name" /opt/actions-runner
+sudo chown -R "$user_name":"$user_name" /opt/hostedtoolcache
diff --git a/modules/runners/templates/start-runner-osx.sh b/modules/runners/templates/start-runner-osx.sh
new file mode 100644
index 0000000000..20541a2312
--- /dev/null
+++ b/modules/runners/templates/start-runner-osx.sh
@@ -0,0 +1,196 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# macOS variant of start-runner.sh
+
+tag_instance_with_runner_id() {
+  echo "Checking for .runner file to extract agent ID"
+
+  if [[ ! -f "/opt/actions-runner/.runner" ]]; then
+    echo "Warning: .runner file not found"
+    return 0
+  fi
+
+  echo "Found .runner file, extracting agent ID"
+  local agent_id
+  agent_id=$(jq -r '.agentId' /opt/actions-runner/.runner 2>/dev/null || echo "")
+
+  if [[ -z "$agent_id" || "$agent_id" == "null" ]]; then
+    echo "Warning: Could not extract agent ID from .runner file"
+    return 0
+  fi
+
+  echo "Tagging instance with GitHub runner agent ID: $agent_id"
+  if aws ec2 create-tags \
+    --region "$region" \
+    --resources "$instance_id" \
+    --tags Key=ghr:github_runner_id,Value="$agent_id"; then
+    echo "Successfully tagged instance with agent ID: $agent_id"
+    return 0
+  else
+    echo "Warning: Failed to tag instance with agent ID"
+    return 0
+  fi
+}
+
+cleanup() {
+  local exit_code="$1"
+
+  if [ "$exit_code" -ne 0 ]; then
+    echo "ERROR: runner-start-failed with exit code $exit_code"
+  fi
+
+  if [ "$agent_mode" = "ephemeral" ] || [ "$exit_code" -ne 0 ]; then
+    echo "Terminating instance"
+    aws ec2 terminate-instances \
+      --instance-ids "$instance_id" \
+      --region "$region" || true
+  fi
+}
+
+trap 'cleanup $?' EXIT
+
+echo "Retrieving TOKEN from AWS API"
+token=$(curl -f -X PUT "http://169.254.169.254/latest/api/token" \
+  -H "X-aws-ec2-metadata-token-ttl-seconds: 180" || true)
+if [ -z "$token" ]; then
+  retrycount=0
+  until [ -n "$token" ]; do
+    echo "Failed to retrieve token. Retrying in 5 seconds."
+    sleep 5
+    token=$(curl -f -X PUT "http://169.254.169.254/latest/api/token" \
+      -H "X-aws-ec2-metadata-token-ttl-seconds: 180" || true)
+    retrycount=$((retrycount + 1))
+    if [ $retrycount -gt 40 ]; then
+      break
+    fi
+  done
+fi
+
+region=$(curl -f -H "X-aws-ec2-metadata-token: $token" \
+  http://169.254.169.254/latest/dynamic/instance-identity/document | jq -r .region)
+echo "Retrieved REGION from AWS API ($region)"
+
+instance_id=$(curl -f -H "X-aws-ec2-metadata-token: $token" \
+  http://169.254.169.254/latest/meta-data/instance-id)
+echo "Retrieved INSTANCE_ID from AWS API ($instance_id)"
+
+availability_zone=$(curl -f -H "X-aws-ec2-metadata-token: $token" \
+  http://169.254.169.254/latest/meta-data/placement/availability-zone)
+
+environment=$(curl -f -H "X-aws-ec2-metadata-token: $token" \
+  http://169.254.169.254/latest/meta-data/tags/instance/ghr:environment || echo "")
+ssm_config_path=$(curl -f -H "X-aws-ec2-metadata-token: $token" \
+  http://169.254.169.254/latest/meta-data/tags/instance/ghr:ssm_config_path || echo "")
+runner_name_prefix=$(curl -f -H "X-aws-ec2-metadata-token: $token" \
+  http://169.254.169.254/latest/meta-data/tags/instance/ghr:runner_name_prefix || echo "")
+
+echo "Retrieved ghr:environment tag - ($environment)"
+echo "Retrieved ghr:ssm_config_path tag - ($ssm_config_path)"
+echo "Retrieved ghr:runner_name_prefix tag - ($runner_name_prefix)"
+
+parameters=$(aws ssm get-parameters-by-path \
+  --path "$ssm_config_path" \
+  --region "$region" \
+  --query "Parameters[*].{Name:Name,Value:Value}")
+echo "Retrieved parameters from AWS SSM ($parameters)"
+
+run_as=$(echo "$parameters" | jq -r '.[] | select(.Name == "'$ssm_config_path'/run_as") | .Value')
+echo "Retrieved /$ssm_config_path/run_as parameter - ($run_as)"
+
+agent_mode=$(echo "$parameters" | jq -r '.[] | select(.Name == "'$ssm_config_path'/agent_mode") | .Value')
+echo "Retrieved /$ssm_config_path/agent_mode parameter - ($agent_mode)"
+
+disable_default_labels=$(echo "$parameters" | jq -r '.[] | select(.Name == "'$ssm_config_path'/disable_default_labels") | .Value')
+echo "Retrieved /$ssm_config_path/disable_default_labels parameter - ($disable_default_labels)"
+
+enable_jit_config=$(echo "$parameters" | jq -r '.[] | select(.Name == "'$ssm_config_path'/enable_jit_config") | .Value')
+echo "Retrieved /$ssm_config_path/enable_jit_config parameter - ($enable_jit_config)"
+
+token_path=$(echo "$parameters" | jq -r '.[] | select(.Name == "'$ssm_config_path'/token_path") | .Value')
+echo "Retrieved /$ssm_config_path/token_path parameter - ($token_path)"
+
+echo "Get GH Runner config from AWS SSM"
+config=$(aws ssm get-parameter \
+  --name "$token_path"/"$instance_id" \
+  --with-decryption \
+  --region "$region" | jq -r ".Parameter | .Value")
+
+while [[ -z "$config" ]]; do
+  echo "Waiting for GH Runner config to become available in AWS SSM"
+  sleep 1
+  config=$(aws ssm get-parameter \
+    --name "$token_path"/"$instance_id" \
+    --with-decryption \
+    --region "$region" | jq -r ".Parameter | .Value")
+done
+
+echo "Delete GH Runner token from AWS SSM"
+aws ssm delete-parameter --name "$token_path"/"$instance_id" --region "$region"
+
+if [ -z "$run_as" ]; then
+  echo "No user specified, using default ec2-user account"
+  run_as="ec2-user"
+fi
+
+if [[ "$run_as" == "root" ]]; then
+  echo "run_as is set to root - export RUNNER_ALLOW_RUNASROOT=1"
+  export RUNNER_ALLOW_RUNASROOT=1
+fi
+
+sudo chown -R "$run_as" /opt/actions-runner
+
+info_arch=$(uname -m)
+info_os=$(sw_vers -productName 2>/dev/null || echo "macOS")
+info_ver=$(sw_vers -productVersion 2>/dev/null || echo "unknown")
+
+tee /opt/actions-runner/.setup_info <<EOL
+[
+  {
+    "group": "Operating System",
+    "detail": "Distribution: $info_os $info_ver\nArchitecture: $info_arch"
+  },
+  {
+    "group": "EC2",
+    "detail": "Instance id: $instance_id\nAvailability zone: $availability_zone"
+  }
+]
+EOL
+
+echo "Starting runner as user $run_as"
+
+cd /opt/actions-runner || exit 1
+
+if [[ "$enable_jit_config" == "false" || $agent_mode != "ephemeral" ]]; then
+  echo "Configure GH Runner as user $run_as"
+  if [[ "$disable_default_labels" == "true" ]]; then
+    extra_flags="--no-default-labels"
+  else
+    extra_flags=""
+  fi
+
+  sudo --preserve-env=RUNNER_ALLOW_RUNASROOT -u "$run_as" -- ./config.sh \
+    $extra_flags \
+    --unattended \
+    --name "$runner_name_prefix$instance_id" \
+    --work "_work" $config
+
+  tag_instance_with_runner_id
+fi
+
+if [[ $agent_mode = "ephemeral" ]]; then
+  echo "Starting the runner in ephemeral mode"
+
+  if [[ "$enable_jit_config" == "true" ]]; then
+    echo "Starting with JIT config"
+    sudo --preserve-env=RUNNER_ALLOW_RUNASROOT -u "$run_as" -- ./run.sh --jitconfig $config
+  else
+    echo "Starting without JIT config"
+    sudo --preserve-env=RUNNER_ALLOW_RUNASROOT -u "$run_as" -- ./run.sh
+  fi
+  echo "Runner has finished"
+else
+  echo "Starting the runner in persistent mode (foreground)"
+  sudo --preserve-env=RUNNER_ALLOW_RUNASROOT -u "$run_as" -- ./run.sh
+fi
diff --git a/modules/runners/templates/user-data-osx.sh b/modules/runners/templates/user-data-osx.sh
new file mode 100644
index 0000000000..1b8c9455a1
--- /dev/null
+++ b/modules/runners/templates/user-data-osx.sh
@@ -0,0 +1,43 @@
+#!/bin/bash -e
+
+exec > >(tee /var/log/user-data.log | logger -t user-data -s 2>/dev/console) 2>&1
+
+# macOS user-data for GitHub Actions runners
+
+set +x
+
+%{ if enable_debug_logging }
+set -x
+%{ endif }
+
+${pre_install}
+
+# On macOS we don't use dnf; assume base image has required tools
+# Optionally use brew here if needed
+if command -v brew >/dev/null 2>&1; then
+  echo "Homebrew detected; you can install extra dependencies via brew if needed"
+fi
+
+user_name=ec2-user
+
+${install_runner}
+
+${post_install}
+
+# Register runner job hooks
+# Ref: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job
+%{ if hook_job_started != "" }
+cat > /opt/actions-runner/hook_job_started.sh <<'EOF'
+${hook_job_started}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/actions-runner/hook_job_started.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
+%{ if hook_job_completed != "" }
+cat > /opt/actions-runner/hook_job_completed.sh <<'EOF'
+${hook_job_completed}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/opt/actions-runner/hook_job_completed.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
+${start_runner}

From be6f11a2783b8d53f7cbcb6ecca3c4bdd1083cbb Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 15 Dec 2025 11:14:32 +0000
Subject: [PATCH 12/46] docs: auto update terraform docs

---
 README.md                                | 2 +-
 examples/prebuilt/README.md              | 2 +-
 modules/runner-binaries-syncer/README.md | 2 +-
 modules/runners/README.md                | 4 ++--
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 3466862548..185691f36f 100644
--- a/README.md
+++ b/README.md
@@ -145,7 +145,7 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_instance_profile_path"></a> [instance\_profile\_path](#input\_instance\_profile\_path) | The path that will be added to the instance\_profile, if not set the environment name will be used. | `string` | `null` | no |
 | <a name="input_instance_target_capacity_type"></a> [instance\_target\_capacity\_type](#input\_instance\_target\_capacity\_type) | Default lifecycle used for runner instances, can be either `spot` or `on-demand`. | `string` | `"spot"` | no |
 | <a name="input_instance_termination_watcher"></a> [instance\_termination\_watcher](#input\_instance\_termination\_watcher) | Configuration for the instance termination watcher. This feature is Beta, changes will not trigger a major release as long in beta.<br/><br/>`enable`: Enable or disable the spot termination watcher.<br/>'features': Enable or disable features of the termination watcher.<br/>`memory_size`: Memory size limit in MB of the lambda.<br/>`s3_key`: S3 key for syncer lambda function. Required if using S3 bucket to specify lambdas.<br/>`s3_object_version`: S3 object version for syncer lambda function. Useful if S3 versioning is enabled on source bucket.<br/>`timeout`: Time out of the lambda in seconds.<br/>`zip`: File location of the lambda zip file. | <pre>object({<br/>    enable = optional(bool, false)<br/>    features = optional(object({<br/>      enable_spot_termination_handler              = optional(bool, true)<br/>      enable_spot_termination_notification_watcher = optional(bool, true)<br/>    }), {})<br/>    memory_size       = optional(number, null)<br/>    s3_key            = optional(string, null)<br/>    s3_object_version = optional(string, null)<br/>    timeout           = optional(number, null)<br/>    zip               = optional(string, null)<br/>  })</pre> | `{}` | no |
-| <a name="input_instance_types"></a> [instance\_types](#input\_instance\_types) | List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux and Windows Server Core for win). | `list(string)` | <pre>[<br/>  "m5.large",<br/>  "c5.large"<br/>]</pre> | no |
+| <a name="input_instance_types"></a> [instance\_types](#input\_instance\_types) | List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux, macOS Sequoia for osx, Windows Server Core for win). | `list(string)` | <pre>[<br/>  "m5.large",<br/>  "c5.large"<br/>]</pre> | no |
 | <a name="input_job_queue_retention_in_seconds"></a> [job\_queue\_retention\_in\_seconds](#input\_job\_queue\_retention\_in\_seconds) | The number of seconds the job is held in the queue before it is purged. | `number` | `86400` | no |
 | <a name="input_job_retry"></a> [job\_retry](#input\_job\_retry) | Experimental! Can be removed / changed without trigger a major release.Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app.<br/><br/>`enable`: Enable or disable the job retry feature.<br/>`delay_in_seconds`: The delay in seconds before the job retry check lambda will check the job status.<br/>`delay_backoff`: The backoff factor for the delay.<br/>`lambda_memory_size`: Memory size limit in MB for the job retry check lambda.<br/>`lambda_timeout`: Time out of the job retry check lambda in seconds.<br/>`max_attempts`: The maximum number of attempts to retry the job. | <pre>object({<br/>    enable             = optional(bool, false)<br/>    delay_in_seconds   = optional(number, 300)<br/>    delay_backoff      = optional(number, 2)<br/>    lambda_memory_size = optional(number, 256)<br/>    lambda_timeout     = optional(number, 30)<br/>    max_attempts       = optional(number, 1)<br/>  })</pre> | `{}` | no |
 | <a name="input_key_name"></a> [key\_name](#input\_key\_name) | Key pair name | `string` | `null` | no |
diff --git a/examples/prebuilt/README.md b/examples/prebuilt/README.md
index b24f47a01d..c2d66139d4 100644
--- a/examples/prebuilt/README.md
+++ b/examples/prebuilt/README.md
@@ -112,7 +112,7 @@ terraform output webhook_secret
 | <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS region. | `string` | `"eu-west-1"` | no |
 | <a name="input_environment"></a> [environment](#input\_environment) | Environment name, used as prefix. | `string` | `null` | no |
 | <a name="input_github_app"></a> [github\_app](#input\_github\_app) | GitHub for API usages. | <pre>object({<br/>    id         = string<br/>    key_base64 = string<br/>  })</pre> | n/a | yes |
-| <a name="input_runner_os"></a> [runner\_os](#input\_runner\_os) | The EC2 Operating System type to use for action runner instances (linux,windows). | `string` | `"linux"` | no |
+| <a name="input_runner_os"></a> [runner\_os](#input\_runner\_os) | The EC2 Operating System type to use for action runner instances (linux, osx, windows). | `string` | `"linux"` | no |
 
 ## Outputs
 
diff --git a/modules/runner-binaries-syncer/README.md b/modules/runner-binaries-syncer/README.md
index 9923e72c08..41b2bdd1e5 100644
--- a/modules/runner-binaries-syncer/README.md
+++ b/modules/runner-binaries-syncer/README.md
@@ -105,7 +105,7 @@ No modules.
 | <a name="input_role_path"></a> [role\_path](#input\_role\_path) | The path that will be added to the role, if not set the environment name will be used. | `string` | `null` | no |
 | <a name="input_role_permissions_boundary"></a> [role\_permissions\_boundary](#input\_role\_permissions\_boundary) | Permissions boundary that will be added to the created role for the lambda. | `string` | `null` | no |
 | <a name="input_runner_architecture"></a> [runner\_architecture](#input\_runner\_architecture) | The platform architecture of the runner instance\_type. | `string` | `"x64"` | no |
-| <a name="input_runner_os"></a> [runner\_os](#input\_runner\_os) | The EC2 Operating System type to use for action runner instances (linux,windows). | `string` | `"linux"` | no |
+| <a name="input_runner_os"></a> [runner\_os](#input\_runner\_os) | The EC2 Operating System type to use for action runner instances (linux, osx, windows). | `string` | `"linux"` | no |
 | <a name="input_s3_logging_bucket"></a> [s3\_logging\_bucket](#input\_s3\_logging\_bucket) | Bucket for action runner distribution bucket access logging. | `string` | `null` | no |
 | <a name="input_s3_logging_bucket_prefix"></a> [s3\_logging\_bucket\_prefix](#input\_s3\_logging\_bucket\_prefix) | Bucket prefix for action runner distribution bucket access logging. | `string` | `null` | no |
 | <a name="input_s3_tags"></a> [s3\_tags](#input\_s3\_tags) | Map of tags that will be added to the S3 bucket. Note these are additional tags to the default tags. | `map(string)` | `{}` | no |
diff --git a/modules/runners/README.md b/modules/runners/README.md
index 21623ced33..39676da78a 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -170,7 +170,7 @@ yarn run dist
 | <a name="input_instance_max_spot_price"></a> [instance\_max\_spot\_price](#input\_instance\_max\_spot\_price) | Max price price for spot instances per hour. This variable will be passed to the create fleet as max spot price for the fleet. | `string` | `null` | no |
 | <a name="input_instance_profile_path"></a> [instance\_profile\_path](#input\_instance\_profile\_path) | The path that will be added to the instance\_profile, if not set the prefix will be used. | `string` | `null` | no |
 | <a name="input_instance_target_capacity_type"></a> [instance\_target\_capacity\_type](#input\_instance\_target\_capacity\_type) | Default lifecycle used runner instances, can be either `spot` or `on-demand`. | `string` | `"spot"` | no |
-| <a name="input_instance_types"></a> [instance\_types](#input\_instance\_types) | List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux and Windows Server Core for win). | `list(string)` | `null` | no |
+| <a name="input_instance_types"></a> [instance\_types](#input\_instance\_types) | List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux, macOS Sequoia for osx, Windows Server Core for win). | `list(string)` | `null` | no |
 | <a name="input_job_retry"></a> [job\_retry](#input\_job\_retry) | Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app.<br/><br/>`enable`: Enable or disable the job retry feature.<br/>`delay_in_seconds`: The delay in seconds before the job retry check lambda will check the job status.<br/>`delay_backoff`: The backoff factor for the delay.<br/>`lambda_memory_size`: Memory size limit in MB for the job retry check lambda.<br/>'lambda\_reserved\_concurrent\_executions': Amount of reserved concurrent executions for the job retry check lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations.<br/>`lambda_timeout`: Time out of the job retry check lambda in seconds.<br/>`max_attempts`: The maximum number of attempts to retry the job. | <pre>object({<br/>    enable                                = optional(bool, false)<br/>    delay_in_seconds                      = optional(number, 300)<br/>    delay_backoff                         = optional(number, 2)<br/>    lambda_memory_size                    = optional(number, 256)<br/>    lambda_reserved_concurrent_executions = optional(number, 1)<br/><br/>    lambda_timeout = optional(number, 30)<br/><br/>    max_attempts = optional(number, 1)<br/>  })</pre> | `{}` | no |
 | <a name="input_key_name"></a> [key\_name](#input\_key\_name) | Key pair name | `string` | `null` | no |
 | <a name="input_kms_key_arn"></a> [kms\_key\_arn](#input\_kms\_key\_arn) | Optional CMK Key ARN to be used for Parameter Store. | `string` | `null` | no |
@@ -218,7 +218,7 @@ yarn run dist
 | <a name="input_runner_labels"></a> [runner\_labels](#input\_runner\_labels) | All the labels for the runners (GitHub) including the default one's(e.g: self-hosted, linux, x64, label1, label2). Separate each label by a comma | `list(string)` | n/a | yes |
 | <a name="input_runner_log_files"></a> [runner\_log\_files](#input\_runner\_log\_files) | (optional) List of logfiles to send to CloudWatch, will only be used if `enable_cloudwatch_agent` is set to true. Object description: `log_group_name`: Name of the log group, `prefix_log_group`: If true, the log group name will be prefixed with `/github-self-hosted-runners/<var.prefix>`, `file_path`: path to the log file, `log_stream_name`: name of the log stream, `log_class`: The log class of the log group. Valid values are `STANDARD` or `INFREQUENT_ACCESS`. Defaults to `STANDARD`. | <pre>list(object({<br/>    log_group_name   = string<br/>    prefix_log_group = bool<br/>    file_path        = string<br/>    log_stream_name  = string<br/>    log_class        = optional(string, "STANDARD")<br/>  }))</pre> | `null` | no |
 | <a name="input_runner_name_prefix"></a> [runner\_name\_prefix](#input\_runner\_name\_prefix) | The prefix used for the GitHub runner name. The prefix will be used in the default start script to prefix the instance name when register the runner in GitHub. The value is available via an EC2 tag 'ghr:runner\_name\_prefix'. | `string` | `""` | no |
-| <a name="input_runner_os"></a> [runner\_os](#input\_runner\_os) | The EC2 Operating System type to use for action runner instances (linux,windows). | `string` | `"linux"` | no |
+| <a name="input_runner_os"></a> [runner\_os](#input\_runner\_os) | The EC2 Operating System type to use for action runner instances (linux, osx, windows). | `string` | `"linux"` | no |
 | <a name="input_runner_run_as"></a> [runner\_run\_as](#input\_runner\_run\_as) | Run the GitHub actions agent as user. | `string` | `"ec2-user"` | no |
 | <a name="input_runners_lambda_s3_key"></a> [runners\_lambda\_s3\_key](#input\_runners\_lambda\_s3\_key) | S3 key for runners lambda function. Required if using S3 bucket to specify lambdas. | `string` | `null` | no |
 | <a name="input_runners_lambda_s3_object_version"></a> [runners\_lambda\_s3\_object\_version](#input\_runners\_lambda\_s3\_object\_version) | S3 object version for runners lambda function. Useful if S3 versioning is enabled on source bucket. | `string` | `null` | no |

From 5e906512eca793396f9109955a4e11226c9423f0 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 17 Dec 2025 13:37:14 +0100
Subject: [PATCH 13/46] fix: remove not needed variable

---
 modules/runners/templates/install-runner-osx.sh | 2 --
 1 file changed, 2 deletions(-)

diff --git a/modules/runners/templates/install-runner-osx.sh b/modules/runners/templates/install-runner-osx.sh
index 893a62b098..9f3c41ccb5 100644
--- a/modules/runners/templates/install-runner-osx.sh
+++ b/modules/runners/templates/install-runner-osx.sh
@@ -53,8 +53,6 @@ else
   # Example: brew install jq awscli
 fi
 
-user_name="${RUNNER_USER:-ec2-user}"
-
 echo "Set file ownership of action runner"
 sudo chown -R "$user_name":"$user_name" /opt/actions-runner
 sudo chown -R "$user_name":"$user_name" /opt/hostedtoolcache

From cc9a15b35cc535b9de4e2a64a08bb4b403a98ca8 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 18 Dec 2025 12:38:49 +0100
Subject: [PATCH 14/46] fix: fix ownership group

---
 modules/runners/templates/install-runner-osx.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/modules/runners/templates/install-runner-osx.sh b/modules/runners/templates/install-runner-osx.sh
index 9f3c41ccb5..7d212f6a01 100644
--- a/modules/runners/templates/install-runner-osx.sh
+++ b/modules/runners/templates/install-runner-osx.sh
@@ -54,5 +54,5 @@ else
 fi
 
 echo "Set file ownership of action runner"
-sudo chown -R "$user_name":"$user_name" /opt/actions-runner
-sudo chown -R "$user_name":"$user_name" /opt/hostedtoolcache
+sudo chown -R "$user_name":staff /opt/actions-runner
+sudo chown -R "$user_name":staff /opt/hostedtoolcache

From 68e3f2490159f02cf44d476d2b72d405aac65c3a Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 18 Dec 2025 15:36:34 +0100
Subject: [PATCH 15/46] fix: fix wrong type for host_resource_group_arn

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 185691f36f..2e05dc2a51 100644
--- a/README.md
+++ b/README.md
@@ -203,7 +203,7 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_runner_log_files"></a> [runner\_log\_files](#input\_runner\_log\_files) | (optional) List of logfiles to send to CloudWatch, will only be used if `enable_cloudwatch_agent` is set to true. Object description: `log_group_name`: Name of the log group, `prefix_log_group`: If true, the log group name will be prefixed with `/github-self-hosted-runners/<var.prefix>`, `file_path`: path to the log file, `log_stream_name`: name of the log stream, `log_class`: The log class of the log group. Valid values are `STANDARD` or `INFREQUENT_ACCESS`. Defaults to `STANDARD`. | <pre>list(object({<br/>    log_group_name   = string<br/>    prefix_log_group = bool<br/>    file_path        = string<br/>    log_stream_name  = string<br/>    log_class        = optional(string, "STANDARD")<br/>  }))</pre> | `null` | no |
 | <a name="input_runner_metadata_options"></a> [runner\_metadata\_options](#input\_runner\_metadata\_options) | Metadata options for the ec2 runner instances. By default, the module uses metadata tags for bootstrapping the runner, only disable `instance_metadata_tags` when using custom scripts for starting the runner. | `map(any)` | <pre>{<br/>  "http_endpoint": "enabled",<br/>  "http_put_response_hop_limit": 1,<br/>  "http_tokens": "required",<br/>  "instance_metadata_tags": "enabled"<br/>}</pre> | no |
 | <a name="input_runner_name_prefix"></a> [runner\_name\_prefix](#input\_runner\_name\_prefix) | The prefix used for the GitHub runner name. The prefix will be used in the default start script to prefix the instance name when register the runner in GitHub. The value is available via an EC2 tag 'ghr:runner\_name\_prefix'. | `string` | `""` | no |
-| <a name="input_runner_os"></a> [runner\_os](#input\_runner\_os) | The EC2 Operating System type to use for action runner instances (linux,windows). | `string` | `"linux"` | no |
+| <a name="input_runner_os"></a> [runner\_os](#input\_runner\_os) | The EC2 Operating System type to use for action runner instances (linux, osx, windows). | `string` | `"linux"` | no |
 | <a name="input_runner_placement"></a> [runner\_placement](#input\_runner\_placement) | The placement options for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#placement for details. | <pre>object({<br/>    affinity                = optional(string)<br/>    availability_zone       = optional(string)<br/>    group_id                = optional(string)<br/>    group_name              = optional(string)<br/>    host_id                 = optional(string)<br/>    host_resource_group_arn = optional(string)<br/>    spread_domain           = optional(string)<br/>    tenancy                 = optional(string)<br/>    partition_number        = optional(number)<br/>  })</pre> | `null` | no |
 | <a name="input_runner_run_as"></a> [runner\_run\_as](#input\_runner\_run\_as) | Run the GitHub actions agent as user. | `string` | `"ec2-user"` | no |
 | <a name="input_runners_ebs_optimized"></a> [runners\_ebs\_optimized](#input\_runners\_ebs\_optimized) | Enable EBS optimization for the runner instances. | `bool` | `false` | no |

From 69add62f5e57f835b085cb66f0a4c4fdd83711b3 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 18 Dec 2025 21:51:42 +0100
Subject: [PATCH 16/46] feat: add license_specification

---
 main.tf                                    | 1 +
 modules/multi-runner/runners.tf            | 1 +
 modules/multi-runner/variables.tf          | 3 +++
 modules/runners/main.tf                    | 7 +++++++
 modules/runners/templates/user-data-osx.sh | 4 ----
 modules/runners/variables.tf               | 8 ++++++++
 variables.tf                               | 8 ++++++++
 7 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/main.tf b/main.tf
index 63b5725d06..8a58057b90 100644
--- a/main.tf
+++ b/main.tf
@@ -210,6 +210,7 @@ module "runners" {
   credit_specification                 = var.runner_credit_specification
   cpu_options                          = var.runner_cpu_options
   placement                            = var.runner_placement
+  license_specification                = var.runner_license_specification
 
   enable_runner_binaries_syncer                                  = var.enable_runner_binaries_syncer
   lambda_s3_bucket                                               = var.lambda_s3_bucket
diff --git a/modules/multi-runner/runners.tf b/modules/multi-runner/runners.tf
index 32251eb1bc..00b1a65028 100644
--- a/modules/multi-runner/runners.tf
+++ b/modules/multi-runner/runners.tf
@@ -57,6 +57,7 @@ module "runners" {
   credit_specification                 = each.value.runner_config.credit_specification
   cpu_options                          = each.value.runner_config.cpu_options
   placement                            = each.value.runner_config.placement
+  license_specification                = each.value.runner_config.license_specification
 
   enable_runner_binaries_syncer                                  = each.value.runner_config.enable_runner_binaries_syncer
   lambda_s3_bucket                                               = var.lambda_s3_bucket
diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index c2aea07196..9676f1c0ef 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -149,6 +149,9 @@ variable "multi_runner_config" {
         tenancy                 = optional(string)
         partition_number        = optional(number)
       }), null)
+      license_specification = optional(object({
+        license_configuration_arn = string
+      }), null)
       runner_log_files = optional(list(object({
         log_group_name   = string
         prefix_log_group = bool
diff --git a/modules/runners/main.tf b/modules/runners/main.tf
index 0590f1b5ff..d818aff4d5 100644
--- a/modules/runners/main.tf
+++ b/modules/runners/main.tf
@@ -192,6 +192,13 @@ resource "aws_launch_template" "runner" {
     }
   }
 
+  dynamic "license_specification" {
+    for_each = var.license_specification != null ? [var.license_specification] : []
+    content {
+      license_configuration_arn = license_specification.value.license_configuration_arn
+    }
+  }
+
   monitoring {
     enabled = var.enable_runner_detailed_monitoring
   }
diff --git a/modules/runners/templates/user-data-osx.sh b/modules/runners/templates/user-data-osx.sh
index 1b8c9455a1..e4c4673598 100644
--- a/modules/runners/templates/user-data-osx.sh
+++ b/modules/runners/templates/user-data-osx.sh
@@ -1,9 +1,5 @@
 #!/bin/bash -e
 
-exec > >(tee /var/log/user-data.log | logger -t user-data -s 2>/dev/console) 2>&1
-
-# macOS user-data for GitHub Actions runners
-
 set +x
 
 %{ if enable_debug_logging }
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index a2d24223d0..cbb959ddbc 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -687,6 +687,14 @@ variable "placement" {
   default = null
 }
 
+variable "license_specification" {
+  description = "The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details."
+  type = object({
+    license_configuration_arn = string
+  })
+  default = null
+}
+
 variable "enable_jit_config" {
   description = "Overwrite the default behavior for JIT configuration. By default JIT configuration is enabled for ephemeral runners and disabled for non-ephemeral runners. In case of GHES check first if the JIT config API is available. In case you are upgrading from 3.x to 4.x you can set `enable_jit_config` to `false` to avoid a breaking change when having your own AMI."
   type        = bool
diff --git a/variables.tf b/variables.tf
index 75a825c348..eaca4a28ac 100644
--- a/variables.tf
+++ b/variables.tf
@@ -918,6 +918,14 @@ variable "runner_placement" {
   default = null
 }
 
+variable "runner_license_specification" {
+  description = "The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details."
+  type = object({
+    license_configuration_arn = string
+  })
+  default = null
+}
+
 variable "enable_jit_config" {
   description = "Overwrite the default behavior for JIT configuration. By default JIT configuration is enabled for ephemeral runners and disabled for non-ephemeral runners. In case of GHES check first if the JIT config API is available. In case you are upgrading from 3.x to 4.x you can set `enable_jit_config` to `false` to avoid a breaking change when having your own AMI."
   type        = bool

From d4dbbc2bcd938b651d702f6e36ee353d076ad931 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 18 Dec 2025 22:17:21 +0100
Subject: [PATCH 17/46] fix: use list of license_specification

---
 main.tf                           | 2 +-
 modules/multi-runner/runners.tf   | 2 +-
 modules/multi-runner/variables.tf | 4 ++--
 modules/runners/main.tf           | 2 +-
 modules/runners/variables.tf      | 8 ++++----
 variables.tf                      | 8 ++++----
 6 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/main.tf b/main.tf
index 8a58057b90..65f0801851 100644
--- a/main.tf
+++ b/main.tf
@@ -210,7 +210,7 @@ module "runners" {
   credit_specification                 = var.runner_credit_specification
   cpu_options                          = var.runner_cpu_options
   placement                            = var.runner_placement
-  license_specification                = var.runner_license_specification
+  license_specifications               = var.runner_license_specifications
 
   enable_runner_binaries_syncer                                  = var.enable_runner_binaries_syncer
   lambda_s3_bucket                                               = var.lambda_s3_bucket
diff --git a/modules/multi-runner/runners.tf b/modules/multi-runner/runners.tf
index 00b1a65028..d957100ef0 100644
--- a/modules/multi-runner/runners.tf
+++ b/modules/multi-runner/runners.tf
@@ -57,7 +57,7 @@ module "runners" {
   credit_specification                 = each.value.runner_config.credit_specification
   cpu_options                          = each.value.runner_config.cpu_options
   placement                            = each.value.runner_config.placement
-  license_specification                = each.value.runner_config.license_specification
+  license_specifications               = each.value.runner_config.license_specifications
 
   enable_runner_binaries_syncer                                  = each.value.runner_config.enable_runner_binaries_syncer
   lambda_s3_bucket                                               = var.lambda_s3_bucket
diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index 9676f1c0ef..52a2e295da 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -149,9 +149,9 @@ variable "multi_runner_config" {
         tenancy                 = optional(string)
         partition_number        = optional(number)
       }), null)
-      license_specification = optional(object({
+      license_specifications = optional(list(object({
         license_configuration_arn = string
-      }), null)
+      })), null)
       runner_log_files = optional(list(object({
         log_group_name   = string
         prefix_log_group = bool
diff --git a/modules/runners/main.tf b/modules/runners/main.tf
index d818aff4d5..d5c4fb097f 100644
--- a/modules/runners/main.tf
+++ b/modules/runners/main.tf
@@ -193,7 +193,7 @@ resource "aws_launch_template" "runner" {
   }
 
   dynamic "license_specification" {
-    for_each = var.license_specification != null ? [var.license_specification] : []
+    for_each = var.license_specifications
     content {
       license_configuration_arn = license_specification.value.license_configuration_arn
     }
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index cbb959ddbc..c475ff9cef 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -687,12 +687,12 @@ variable "placement" {
   default = null
 }
 
-variable "license_specification" {
+variable "license_specifications" {
   description = "The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details."
-  type = object({
+  type = list(object({
     license_configuration_arn = string
-  })
-  default = null
+  }))
+  default = []
 }
 
 variable "enable_jit_config" {
diff --git a/variables.tf b/variables.tf
index eaca4a28ac..40a40dbcdc 100644
--- a/variables.tf
+++ b/variables.tf
@@ -918,12 +918,12 @@ variable "runner_placement" {
   default = null
 }
 
-variable "runner_license_specification" {
+variable "runner_license_specifications" {
   description = "The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details."
-  type = object({
+  type = list(object({
     license_configuration_arn = string
-  })
-  default = null
+  }))
+  default = []
 }
 
 variable "enable_jit_config" {

From b235d68504b39b001329ece382f5a9919a8b2d40 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Thu, 18 Dec 2025 23:45:07 +0100
Subject: [PATCH 18/46] fix: fix typo

---
 modules/multi-runner/variables.tf | 2 +-
 modules/runners/main.tf           | 9 ++++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index 52a2e295da..3bc81b7eca 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -151,7 +151,7 @@ variable "multi_runner_config" {
       }), null)
       license_specifications = optional(list(object({
         license_configuration_arn = string
-      })), null)
+      })), [])
       runner_log_files = optional(list(object({
         log_group_name   = string
         prefix_log_group = bool
diff --git a/modules/runners/main.tf b/modules/runners/main.tf
index d5c4fb097f..5e5fdf4e4e 100644
--- a/modules/runners/main.tf
+++ b/modules/runners/main.tf
@@ -82,6 +82,13 @@ locals {
     enable_cloudwatch_agent         = var.enable_cloudwatch_agent
     ssm_key_cloudwatch_agent_config = var.enable_cloudwatch_agent ? aws_ssm_parameter.cloudwatch_agent_config_runner[0].name : ""
   }) : var.userdata_content) : ""
+
+  encoded_user_data = (
+    var.runner_os == "linux" ? base64gzip(local.user_data) :
+    var.runner_os == "windows" ? base64encode(local.user_data) :
+    var.runner_os == "osx" ? base64encode(local.user_data) :
+    null
+  )
 }
 
 data "aws_ami" "runner" {
@@ -280,7 +287,7 @@ resource "aws_launch_template" "runner" {
     )
   }
 
-  user_data = var.runner_os == "windows" ? base64encode(local.user_data) : base64gzip(local.user_data)
+  user_data = local.encoded_user_data
 
   tags = local.tags
 

From ddbc5c64831a3d7776c3b77c44f84a1cee6ca04b Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Mon, 22 Dec 2025 23:41:46 +0100
Subject: [PATCH 19/46] docs: add example to create dedicate hosts and host
 group

---
 examples/dedicated-mac-hosts/README.md    |  44 +++++++++
 examples/dedicated-mac-hosts/main.tf      | 105 ++++++++++++++++++++++
 examples/dedicated-mac-hosts/outputs.tf   |  12 +++
 examples/dedicated-mac-hosts/providers.tf |   9 ++
 examples/dedicated-mac-hosts/variables.tf |  23 +++++
 examples/dedicated-mac-hosts/versions.tf  |  10 +++
 6 files changed, 203 insertions(+)
 create mode 100644 examples/dedicated-mac-hosts/README.md
 create mode 100644 examples/dedicated-mac-hosts/main.tf
 create mode 100644 examples/dedicated-mac-hosts/outputs.tf
 create mode 100644 examples/dedicated-mac-hosts/providers.tf
 create mode 100644 examples/dedicated-mac-hosts/variables.tf
 create mode 100644 examples/dedicated-mac-hosts/versions.tf

diff --git a/examples/dedicated-mac-hosts/README.md b/examples/dedicated-mac-hosts/README.md
new file mode 100644
index 0000000000..41bb42ef65
--- /dev/null
+++ b/examples/dedicated-mac-hosts/README.md
@@ -0,0 +1,44 @@
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | ~> 1.11 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 6.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.27.0 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_ec2_host.mac_dedicated_host](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ec2_host) | resource |
+| [aws_licensemanager_license_configuration.mac_dedicated_host_license_configuration](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/licensemanager_license_configuration) | resource |
+| [aws_resourcegroups_group.mac_host_group](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/resourcegroups_group) | resource |
+| [aws_resourcegroups_resource.mac_host_membership](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/resourcegroups_resource) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_aws_profile"></a> [aws\_profile](#input\_aws\_profile) | AWS profile (i.e., generated via 'sl aws session generate') to use. | `string` | n/a | yes |
+| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | Default AWS region. | `string` | n/a | yes |
+| <a name="input_default_tags"></a> [default\_tags](#input\_default\_tags) | A map of tags to apply to resources. | `map(string)` | n/a | yes |
+| <a name="input_host_groups"></a> [host\_groups](#input\_host\_groups) | Map of host groups, each with a name, host instance type, and a list of hosts (name + AZ). | <pre>map(object({<br/>    name               = string<br/>    host_instance_type = string<br/>    hosts = list(object({<br/>      name              = string<br/>      availability_zone = string<br/>    }))<br/>  }))</pre> | n/a | yes |
+| <a name="input_tags"></a> [tags](#input\_tags) | A map of tags to apply to resources. | `map(string)` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_license_specification_arn"></a> [license\_specification\_arn](#output\_license\_specification\_arn) | ARN of the License Manager configuration used for Mac dedicated hosts. |
+| <a name="output_resource_group_arns"></a> [resource\_group\_arns](#output\_resource\_group\_arns) | Map of resource group names to their ARNs. |
+<!-- END_TF_DOCS -->
diff --git a/examples/dedicated-mac-hosts/main.tf b/examples/dedicated-mac-hosts/main.tf
new file mode 100644
index 0000000000..8d12844bf9
--- /dev/null
+++ b/examples/dedicated-mac-hosts/main.tf
@@ -0,0 +1,105 @@
+locals {
+
+  environment = var.environment != null ? var.environment : "default"
+  aws_region  = var.aws_region
+
+  # Flatten host_groups into a map of individual host definitions keyed by
+  # "groupKey-hostName" so we can create one aws_ec2_host per host.
+  mac_dedicated_hosts = merge([
+    for group_key, group in var.host_groups : {
+      for host in group.hosts :
+      "${group_key}-${host.name}" => {
+        instance_type     = group.host_instance_type
+        availability_zone = host.availability_zone
+        group_name        = group.name
+        host_name         = host.name
+      }
+    }
+  ]...)
+}
+
+resource "aws_ec2_host" "mac_dedicated_host" {
+  for_each = local.mac_dedicated_hosts
+
+  instance_type     = each.value.instance_type
+  availability_zone = each.value.availability_zone
+  auto_placement    = "on"
+
+  tags = {
+    "Name"      = each.value.host_name
+    "HostGroup" = each.value.group_name
+  }
+}
+
+resource "aws_resourcegroups_group" "mac_host_group" {
+  for_each = { for _, group in var.host_groups : group.name => group }
+
+  name = each.value.name
+
+  configuration {
+    type = "AWS::EC2::HostManagement"
+
+    parameters {
+      name   = "any-host-based-license-configuration"
+      values = ["true"]
+    }
+
+    parameters {
+      name = "auto-allocate-host"
+      values = [
+        "false",
+      ]
+    }
+    parameters {
+      name = "auto-host-recovery"
+      values = [
+        "false",
+      ]
+    }
+    parameters {
+      name = "auto-release-host"
+      values = [
+        "false",
+      ]
+    }
+  }
+
+  configuration {
+    type = "AWS::ResourceGroups::Generic"
+    parameters {
+      name = "allowed-resource-types"
+      values = [
+        "AWS::EC2::Host",
+      ]
+    }
+
+    parameters {
+      name = "deletion-protection"
+      values = [
+        "UNLESS_EMPTY",
+      ]
+    }
+  }
+
+  tags = {
+    "Name" = each.value.name
+  }
+}
+
+resource "aws_resourcegroups_resource" "mac_host_membership" {
+  for_each = local.mac_dedicated_hosts
+
+  group_arn    = aws_resourcegroups_group.mac_host_group[each.value.group_name].arn
+  resource_arn = aws_ec2_host.mac_dedicated_host[each.key].arn
+}
+
+
+resource "aws_licensemanager_license_configuration" "mac_dedicated_host_license_configuration" {
+  name                  = "mac-dedicated-host-license-configuration"
+  description           = "Mac dedicated host license configuration"
+  license_counting_type = "Socket"
+
+  tags = {
+    "Name" = each.value.name
+  }
+}
diff --git a/examples/dedicated-mac-hosts/outputs.tf b/examples/dedicated-mac-hosts/outputs.tf
new file mode 100644
index 0000000000..4aa7dda086
--- /dev/null
+++ b/examples/dedicated-mac-hosts/outputs.tf
@@ -0,0 +1,12 @@
+output "resource_group_arns" {
+  description = "Map of resource group names to their ARNs."
+  value = {
+    for k, rg in aws_resourcegroups_group.mac_host_group :
+    rg.name => rg.arn
+  }
+}
+
+output "license_specification_arn" {
+  description = "ARN of the License Manager configuration used for Mac dedicated hosts."
+  value       = aws_licensemanager_license_configuration.mac_dedicated_host_license_configuration.arn
+}
diff --git a/examples/dedicated-mac-hosts/providers.tf b/examples/dedicated-mac-hosts/providers.tf
new file mode 100644
index 0000000000..eca2fe96a7
--- /dev/null
+++ b/examples/dedicated-mac-hosts/providers.tf
@@ -0,0 +1,9 @@
+provider "aws" {
+  region = local.aws_region
+
+  default_tags {
+    tags = {
+      Example = local.environment
+    }
+  }
+}
diff --git a/examples/dedicated-mac-hosts/variables.tf b/examples/dedicated-mac-hosts/variables.tf
new file mode 100644
index 0000000000..3efed4af38
--- /dev/null
+++ b/examples/dedicated-mac-hosts/variables.tf
@@ -0,0 +1,23 @@
+variable "aws_region" {
+  description = "AWS region."
+  type        = string
+}
+
+variable "environment" {
+  description = "Environment name, used as prefix."
+
+  type    = string
+  default = null
+}
+
+variable "host_groups" {
+  description = "Map of host groups, each with a name, host instance type, and a list of hosts (name + AZ)."
+  type = map(object({
+    name               = string
+    host_instance_type = string
+    hosts = list(object({
+      name              = string
+      availability_zone = string
+    }))
+  }))
+}
diff --git a/examples/dedicated-mac-hosts/versions.tf b/examples/dedicated-mac-hosts/versions.tf
new file mode 100644
index 0000000000..af69406fbd
--- /dev/null
+++ b/examples/dedicated-mac-hosts/versions.tf
@@ -0,0 +1,10 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 6.21"
+    }
+  }
+
+  required_version = ">= 1.3.0"
+}

From 9a0b3154786561734ed42493ea65819392eaec17 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Tue, 23 Dec 2025 17:33:14 +0100
Subject: [PATCH 20/46] fix: fix install runner for windows

---
 modules/runners/templates/install-runner.ps1 | 23 +++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/modules/runners/templates/install-runner.ps1 b/modules/runners/templates/install-runner.ps1
index 4219773ad8..2cdd812a92 100644
--- a/modules/runners/templates/install-runner.ps1
+++ b/modules/runners/templates/install-runner.ps1
@@ -1,10 +1,27 @@
 ## install the runner
 
 Write-Host "Creating actions-runner directory for the GH Action installation"
-New-Item -ItemType Directory -Path C:\actions-runner ; Set-Location C:\actions-runner
+New-Item -ItemType Directory -Path C:\actions-runner -Force | Out-Null
+Set-Location C:\actions-runner
 
-Write-Host "Downloading the GH Action runner from s3 bucket $s3_location"
-aws s3 cp ${S3_LOCATION_RUNNER_DISTRIBUTION} actions-runner.zip
+$runnerTarballUrl = $Env:RUNNER_TARBALL_URL
+$s3RunnerDistribution = $Env:S3_LOCATION_RUNNER_DISTRIBUTION
+
+if ([string]::IsNullOrWhiteSpace($runnerTarballUrl) -and [string]::IsNullOrWhiteSpace($s3RunnerDistribution)) {
+  Write-Host "Neither RUNNER_TARBALL_URL nor S3_LOCATION_RUNNER_DISTRIBUTION are set" -ForegroundColor Red
+  exit 1
+}
+
+$fileName = "actions-runner.zip"
+
+if (-not [string]::IsNullOrWhiteSpace($runnerTarballUrl)) {
+  Write-Host "Downloading the GH Action runner from $runnerTarballUrl to $fileName"
+  Invoke-WebRequest -Uri $runnerTarballUrl -OutFile $fileName -UseBasicParsing
+}
+else {
+  Write-Host "Downloading the GH Action runner from s3 bucket $s3RunnerDistribution"
+  aws s3 cp $s3RunnerDistribution $fileName | Out-Null
+}
 
 Write-Host "Un-zip action runner"
 Expand-Archive -Path actions-runner.zip -DestinationPath .

From 61550f8df2c42c3bc19e9c12636866e6772ce8bd Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Tue, 23 Dec 2025 20:20:39 +0100
Subject: [PATCH 21/46] fix: remove cd in start

---
 modules/runners/templates/start-runner-osx.sh | 2 --
 1 file changed, 2 deletions(-)

diff --git a/modules/runners/templates/start-runner-osx.sh b/modules/runners/templates/start-runner-osx.sh
index 20541a2312..c3ea08af20 100644
--- a/modules/runners/templates/start-runner-osx.sh
+++ b/modules/runners/templates/start-runner-osx.sh
@@ -160,8 +160,6 @@ EOL
 
 echo "Starting runner as user $run_as"
 
-cd /opt/actions-runner || exit 1
-
 if [[ "$enable_jit_config" == "false" || $agent_mode != "ephemeral" ]]; then
   echo "Configure GH Runner as user $run_as"
   if [[ "$disable_default_labels" == "true" ]]; then

From 6c349dc3e13c86464c25b935cc20896ef3b8d650 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 7 Jan 2026 11:50:23 +0100
Subject: [PATCH 22/46] fix: undo windows change

---
 modules/runners/templates/install-runner.ps1 | 24 +++-----------------
 1 file changed, 3 insertions(+), 21 deletions(-)

diff --git a/modules/runners/templates/install-runner.ps1 b/modules/runners/templates/install-runner.ps1
index 2cdd812a92..a13f91a65b 100644
--- a/modules/runners/templates/install-runner.ps1
+++ b/modules/runners/templates/install-runner.ps1
@@ -1,31 +1,13 @@
 ## install the runner
 
 Write-Host "Creating actions-runner directory for the GH Action installation"
-New-Item -ItemType Directory -Path C:\actions-runner -Force | Out-Null
-Set-Location C:\actions-runner
+New-Item -ItemType Directory -Path C:\actions-runner ; Set-Location C:\actions-runner
 
-$runnerTarballUrl = $Env:RUNNER_TARBALL_URL
-$s3RunnerDistribution = $Env:S3_LOCATION_RUNNER_DISTRIBUTION
-
-if ([string]::IsNullOrWhiteSpace($runnerTarballUrl) -and [string]::IsNullOrWhiteSpace($s3RunnerDistribution)) {
-  Write-Host "Neither RUNNER_TARBALL_URL nor S3_LOCATION_RUNNER_DISTRIBUTION are set" -ForegroundColor Red
-  exit 1
-}
-
-$fileName = "actions-runner.zip"
-
-if (-not [string]::IsNullOrWhiteSpace($runnerTarballUrl)) {
-  Write-Host "Downloading the GH Action runner from $runnerTarballUrl to $fileName"
-  Invoke-WebRequest -Uri $runnerTarballUrl -OutFile $fileName -UseBasicParsing
-}
-else {
-  Write-Host "Downloading the GH Action runner from s3 bucket $s3RunnerDistribution"
-  aws s3 cp $s3RunnerDistribution $fileName | Out-Null
-}
+Write-Host "Downloading the GH Action runner from s3 bucket $s3_location"
+aws s3 cp ${S3_LOCATION_RUNNER_DISTRIBUTION} actions-runner.zip
 
 Write-Host "Un-zip action runner"
 Expand-Archive -Path actions-runner.zip -DestinationPath .
 
 Write-Host "Delete zip file"
 Remove-Item actions-runner.zip
-

From 994429a0479c5e218366cefa893f7f517bd92309 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 7 Jan 2026 12:00:53 +0100
Subject: [PATCH 23/46] docs: fix typo

---
 modules/multi-runner/variables.tf | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index 3bc81b7eca..e38383c697 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -223,7 +223,7 @@ variable "multi_runner_config" {
         instance_allocation_strategy: "The allocation strategy for spot instances. AWS recommends to use `capacity-optimized` however the AWS default is `lowest-price`."
         instance_max_spot_price: "Max price price for spot instances per hour. This variable will be passed to the create fleet as max spot price for the fleet."
         instance_target_capacity_type: "Default lifecycle used for runner instances, can be either `spot` or `on-demand`."
-        description: "List of instance types for the action runner. Defaults are based on runner_os (al2023 for linux, macOS Sequoia for osx, Windows Server Core for win)."
+        instance_types: "List of instance types for the action runner. Defaults are based on runner_os (al2023 for linux, macOS Sequoia for osx, Windows Server Core for win)."
         job_queue_retention_in_seconds: "The number of seconds the job is held in the queue before it is purged"
         minimum_running_time_in_minutes: "The time an ec2 action runner should be running at minimum before terminated if not busy."
         pool_runner_owner: "The pool will deploy runners to the GitHub org ID, set this value to the org to which you want the runners deployed. Repo level is not supported."

From 3f5c1ab133c4d606c077b140f7f124c56fa59a56 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 13 Jan 2026 18:11:39 +0000
Subject: [PATCH 24/46] docs: auto update terraform docs

---
 README.md                              |  1 -
 examples/dedicated-mac-hosts/README.md | 12 +++++-------
 modules/runners/README.md              |  1 -
 3 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 2e05dc2a51..d845428698 100644
--- a/README.md
+++ b/README.md
@@ -117,7 +117,6 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_block_device_mappings"></a> [block\_device\_mappings](#input\_block\_device\_mappings) | The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`. | <pre>list(object({<br/>    delete_on_termination = optional(bool, true)<br/>    device_name           = optional(string, "/dev/xvda")<br/>    encrypted             = optional(bool, true)<br/>    iops                  = optional(number)<br/>    kms_key_id            = optional(string)<br/>    snapshot_id           = optional(string)<br/>    throughput            = optional(number)<br/>    volume_size           = number<br/>    volume_type           = optional(string, "gp3")<br/>  }))</pre> | <pre>[<br/>  {<br/>    "volume_size": 30<br/>  }<br/>]</pre> | no |
 | <a name="input_cloudwatch_config"></a> [cloudwatch\_config](#input\_cloudwatch\_config) | (optional) Replaces the module's default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details. | `string` | `null` | no |
 | <a name="input_create_service_linked_role_spot"></a> [create\_service\_linked\_role\_spot](#input\_create\_service\_linked\_role\_spot) | (optional) create the service linked role for spot instances that is required by the scale-up lambda. | `bool` | `false` | no |
-| <a name="input_scale_errors"></a> [custom\_scale\_errors](#input\_custom\_scale\_errors) | List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts | `list(string)` | `[]` | no |
 | <a name="input_delay_webhook_event"></a> [delay\_webhook\_event](#input\_delay\_webhook\_event) | The number of seconds the event accepted by the webhook is invisible on the queue before the scale up lambda will receive the event. | `number` | `30` | no |
 | <a name="input_disable_runner_autoupdate"></a> [disable\_runner\_autoupdate](#input\_disable\_runner\_autoupdate) | Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/) | `bool` | `false` | no |
 | <a name="input_enable_ami_housekeeper"></a> [enable\_ami\_housekeeper](#input\_enable\_ami\_housekeeper) | Option to disable the lambda to clean up old AMIs. | `bool` | `false` | no |
diff --git a/examples/dedicated-mac-hosts/README.md b/examples/dedicated-mac-hosts/README.md
index 41bb42ef65..ad00c2533e 100644
--- a/examples/dedicated-mac-hosts/README.md
+++ b/examples/dedicated-mac-hosts/README.md
@@ -3,14 +3,14 @@
 
 | Name | Version |
 |------|---------|
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | ~> 1.11 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 6.0 |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.27.0 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 6.21 |
 
 ## Modules
 
@@ -29,11 +29,9 @@ No modules.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_aws_profile"></a> [aws\_profile](#input\_aws\_profile) | AWS profile (i.e., generated via 'sl aws session generate') to use. | `string` | n/a | yes |
-| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | Default AWS region. | `string` | n/a | yes |
-| <a name="input_default_tags"></a> [default\_tags](#input\_default\_tags) | A map of tags to apply to resources. | `map(string)` | n/a | yes |
+| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS region. | `string` | n/a | yes |
+| <a name="input_environment"></a> [environment](#input\_environment) | Environment name, used as prefix. | `string` | `null` | no |
 | <a name="input_host_groups"></a> [host\_groups](#input\_host\_groups) | Map of host groups, each with a name, host instance type, and a list of hosts (name + AZ). | <pre>map(object({<br/>    name               = string<br/>    host_instance_type = string<br/>    hosts = list(object({<br/>      name              = string<br/>      availability_zone = string<br/>    }))<br/>  }))</pre> | n/a | yes |
-| <a name="input_tags"></a> [tags](#input\_tags) | A map of tags to apply to resources. | `map(string)` | n/a | yes |
 
 ## Outputs
 
diff --git a/modules/runners/README.md b/modules/runners/README.md
index 39676da78a..02a0731c1d 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -145,7 +145,6 @@ yarn run dist
 | <a name="input_cpu_options"></a> [cpu\_options](#input\_cpu\_options) | The CPU options for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#cpu-options for details. Note that not all instance types support CPU options, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#instance-cpu-options | <pre>object({<br/>    core_count       = number<br/>    threads_per_core = number<br/>  })</pre> | `null` | no |
 | <a name="input_create_service_linked_role_spot"></a> [create\_service\_linked\_role\_spot](#input\_create\_service\_linked\_role\_spot) | (optional) create the service linked role for spot instances that is required by the scale-up lambda. | `bool` | `false` | no |
 | <a name="input_credit_specification"></a> [credit\_specification](#input\_credit\_specification) | The credit option for CPU usage of a T instance. Can be unset, "standard" or "unlimited". | `string` | `null` | no |
-| <a name="input_scale_errors"></a> [custom\_scale\_errors](#input\_custom\_scale\_errors) | List of aws error codesthat should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts | `list(string)` | `[]` | no |
 | <a name="input_disable_runner_autoupdate"></a> [disable\_runner\_autoupdate](#input\_disable\_runner\_autoupdate) | Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/) | `bool` | `false` | no |
 | <a name="input_ebs_optimized"></a> [ebs\_optimized](#input\_ebs\_optimized) | The EC2 EBS optimized configuration. | `bool` | `false` | no |
 | <a name="input_egress_rules"></a> [egress\_rules](#input\_egress\_rules) | List of egress rules for the GitHub runner instances. | <pre>list(object({<br/>    cidr_blocks      = list(string)<br/>    ipv6_cidr_blocks = list(string)<br/>    prefix_list_ids  = list(string)<br/>    from_port        = number<br/>    protocol         = string<br/>    security_groups  = list(string)<br/>    self             = bool<br/>    to_port          = number<br/>    description      = string<br/>  }))</pre> | <pre>[<br/>  {<br/>    "cidr_blocks": [<br/>      "0.0.0.0/0"<br/>    ],<br/>    "description": null,<br/>    "from_port": 0,<br/>    "ipv6_cidr_blocks": [<br/>      "::/0"<br/>    ],<br/>    "prefix_list_ids": null,<br/>    "protocol": "-1",<br/>    "security_groups": null,<br/>    "self": null,<br/>    "to_port": 0<br/>  }<br/>]</pre> | no |

From 262d0ee31573dbdf5e3089282c9e9107c727984a Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 14 Jan 2026 13:11:37 +0100
Subject: [PATCH 25/46] fix: fix github copilot findings

---
 examples/dedicated-mac-hosts/main.tf | 2 +-
 modules/runners/scale-down.tf        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/dedicated-mac-hosts/main.tf b/examples/dedicated-mac-hosts/main.tf
index 8d12844bf9..f0b1537859 100644
--- a/examples/dedicated-mac-hosts/main.tf
+++ b/examples/dedicated-mac-hosts/main.tf
@@ -100,6 +100,6 @@ resource "aws_licensemanager_license_configuration" "mac_dedicated_host_license_
   license_counting_type = "Socket"
 
   tags = {
-    "Name" = each.value.name
+    "Name" = "mac-dedicated-host-license-configuration"
   }
 }
diff --git a/modules/runners/scale-down.tf b/modules/runners/scale-down.tf
index bd5f75554b..449d1970ed 100644
--- a/modules/runners/scale-down.tf
+++ b/modules/runners/scale-down.tf
@@ -1,6 +1,6 @@
 locals {
   # Windows Runners can take their sweet time to do anything
-  # For an AWS vended AMI with a x86 Mac instance or a Apple silicon Mac instance, 
+  # For an AWS vended AMI with an x86 Mac instance or an Apple silicon Mac instance,
   # the launch time can range from approximately 6 minutes to 20 minutes. 
   min_runtime_defaults = {
     "windows" = 15

From 406b76a95928fb0d0b1e0aa6533c2f3a3612dad5 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Tue, 20 Jan 2026 19:21:14 +0100
Subject: [PATCH 26/46] docs: add mac template example

---
 .../runner-configs/mac-arm64-26.yaml          | 40 +++++++++++++++++++
 examples/multi-runner/variables.tf            |  2 +-
 .../runner-binaries-syncer.tf                 |  1 +
 3 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml

diff --git a/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml b/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml
new file mode 100644
index 0000000000..2c4d700b31
--- /dev/null
+++ b/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml
@@ -0,0 +1,40 @@
+matcherConfig:
+  exactMatch: true
+  labelMatchers:
+    - [self-hosted, osx, arm64]
+fifo: true
+redrive_build_queue:
+  enabled: false
+  maxReceiveCount: null
+runner_config:
+  placement:
+    host_resource_group_arn: "<host_resource_group_arn>"
+    tenancy: host
+  license_specifications:
+    - license_configuration_arn: "<license_configuration_arn>"
+  runner_os: osx
+  runner_architecture: arm64
+  runner_user: ec2-user
+  runner_name_prefix: macos_26_
+  enable_ssm_on_runners: true
+  credit_specification: unlimited
+  instance_types:
+    - mac2.metal
+  ami:
+    id_ssm_parameter_arn: ${ami_id_ssm_parameter_arn}
+  ami:
+    owners:
+      - amazon
+    filter:
+      name:
+        - amzn-ec2-macos-26*
+      state:
+        - available    
+  runners_maximum_count: 1
+  delay_webhook_event: 0
+  scale_down_schedule_expression: cron(* * * * ? *)
+  runner_hook_job_started: |
+    echo "Running pre job hook as $(whoami)"
+  runner_hook_job_completed: |
+    echo "Running post job hook as $(whoami)"
+
diff --git a/examples/multi-runner/variables.tf b/examples/multi-runner/variables.tf
index 009c3643db..bc490ae273 100644
--- a/examples/multi-runner/variables.tf
+++ b/examples/multi-runner/variables.tf
@@ -19,4 +19,4 @@ variable "aws_region" {
 
   type    = string
   default = "eu-west-1"
-}
+}
\ No newline at end of file
diff --git a/modules/runner-binaries-syncer/runner-binaries-syncer.tf b/modules/runner-binaries-syncer/runner-binaries-syncer.tf
index 00b6e700f5..b893c70393 100644
--- a/modules/runner-binaries-syncer/runner-binaries-syncer.tf
+++ b/modules/runner-binaries-syncer/runner-binaries-syncer.tf
@@ -4,6 +4,7 @@ locals {
   gh_binary_os_label = {
     windows = "win",
     linux   = "linux"
+    osx     = "osx"
   }
 }
 

From ebbe471ae4bb1138d3aae680c9a87a1aa424b619 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 28 Jan 2026 16:49:56 +0100
Subject: [PATCH 27/46] fix: fix path to hostedtoolcache in mac

---
 modules/runners/templates/install-runner-osx.sh | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/modules/runners/templates/install-runner-osx.sh b/modules/runners/templates/install-runner-osx.sh
index 7d212f6a01..73abce4500 100644
--- a/modules/runners/templates/install-runner-osx.sh
+++ b/modules/runners/templates/install-runner-osx.sh
@@ -13,7 +13,7 @@ fi
 file_name="actions-runner.tar.gz"
 
 echo "Setting up GH Actions runner tool cache"
-mkdir -p /opt/hostedtoolcache
+mkdir -p /Users/runner/hostedtoolcache
 
 echo "Creating actions-runner directory for the GH Action installation"
 sudo mkdir -p /opt/actions-runner
@@ -55,4 +55,5 @@ fi
 
 echo "Set file ownership of action runner"
 sudo chown -R "$user_name":staff /opt/actions-runner
-sudo chown -R "$user_name":staff /opt/hostedtoolcache
+sudo chmod 755 "/Users/runner"
+sudo chown -R "$user_name":staff /Users/runner/hostedtoolcache

From a70f0ca3f3e9e5b04b0815ae415432d6cb205f1e Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Fri, 6 Mar 2026 16:02:51 +0100
Subject: [PATCH 28/46] feat: add input use_dedicated_host

---
 .../control-plane/src/aws/runners.d.ts        |   1 +
 .../control-plane/src/aws/runners.test.ts     | 211 ++++++++++++++++++
 .../control-plane/src/aws/runners.ts          |  72 ++++++
 .../src/scale-runners/scale-up.test.ts        |  37 +++
 .../src/scale-runners/scale-up.ts             |   3 +
 main.tf                                       |   1 +
 modules/multi-runner/runners.tf               |   1 +
 modules/multi-runner/variables.tf             |   1 +
 modules/runners/pool.tf                       |   1 +
 modules/runners/pool/main.tf                  |   1 +
 modules/runners/pool/variables.tf             |   1 +
 modules/runners/scale-up.tf                   |   1 +
 modules/runners/variables.tf                  |   6 +
 variables.tf                                  |   6 +
 14 files changed, 343 insertions(+)

diff --git a/lambdas/functions/control-plane/src/aws/runners.d.ts b/lambdas/functions/control-plane/src/aws/runners.d.ts
index f57652d491..01cd4c1459 100644
--- a/lambdas/functions/control-plane/src/aws/runners.d.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.d.ts
@@ -70,4 +70,5 @@ export interface RunnerInputParameters {
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
   scaleErrors: string[];
+  useDedicatedHost?: boolean;
 }
diff --git a/lambdas/functions/control-plane/src/aws/runners.test.ts b/lambdas/functions/control-plane/src/aws/runners.test.ts
index 1e3d10eb34..3fdbe5fc2f 100644
--- a/lambdas/functions/control-plane/src/aws/runners.test.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.test.ts
@@ -10,6 +10,7 @@ import {
   DescribeInstancesCommand,
   type DescribeInstancesResult,
   EC2Client,
+  RunInstancesCommand,
   SpotAllocationStrategy,
   TerminateInstancesCommand,
 } from '@aws-sdk/client-ec2';
@@ -964,6 +965,7 @@ interface RunnerConfig {
   onDemandFailoverOnError?: string[];
   scaleErrors: string[];
   source: LambdaRunnerSource;
+  useDedicatedHost?: boolean;
 }
 
 function createRunnerConfig(runnerConfig: RunnerConfig): RunnerInputParameters {
@@ -985,6 +987,7 @@ function createRunnerConfig(runnerConfig: RunnerConfig): RunnerInputParameters {
     onDemandFailoverOnError: runnerConfig.onDemandFailoverOnError,
     scaleErrors: runnerConfig.scaleErrors,
     source: runnerConfig.source,    
+    useDedicatedHost: runnerConfig.useDedicatedHost,
   };
 }
 
@@ -1073,3 +1076,211 @@ function expectedCreateFleetRequest(expectedValues: ExpectedFleetRequestValues):
 
   return request;
 }
+
+describe('create runner with useDedicatedHost', () => {
+  const dedicatedHostRunnerConfig: RunnerConfig = {
+    allocationStrategy: SpotAllocationStrategy.CAPACITY_OPTIMIZED,
+    capacityType: 'on-demand',
+    type: 'Org',
+    scaleErrors: [],
+    useDedicatedHost: true,
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockEC2Client.reset();
+    mockSSMClient.reset();
+
+    mockEC2Client.on(RunInstancesCommand).resolves({
+      Instances: [{ InstanceId: 'i-dedicated-1' }],
+    });
+    mockSSMClient.on(GetParameterCommand).resolves({});
+  });
+
+  it('uses RunInstances instead of CreateFleet when useDedicatedHost is true', async () => {
+    const result = await createRunner(createRunnerConfig(dedicatedHostRunnerConfig));
+
+    expect(result).toEqual(['i-dedicated-1']);
+    expect(mockEC2Client).toHaveReceivedCommand(RunInstancesCommand);
+    expect(mockEC2Client).not.toHaveReceivedCommand(CreateFleetCommand);
+  });
+
+  it('uses CreateFleet when useDedicatedHost is false', async () => {
+    mockEC2Client.on(CreateFleetCommand).resolves({ Instances: [{ InstanceIds: ['i-fleet-1'] }] });
+
+    const result = await createRunner(createRunnerConfig({
+      ...dedicatedHostRunnerConfig,
+      useDedicatedHost: false,
+    }));
+
+    expect(result).toEqual(['i-fleet-1']);
+    expect(mockEC2Client).toHaveReceivedCommand(CreateFleetCommand);
+    expect(mockEC2Client).not.toHaveReceivedCommand(RunInstancesCommand);
+  });
+
+  it('uses CreateFleet when useDedicatedHost is undefined', async () => {
+    mockEC2Client.on(CreateFleetCommand).resolves({ Instances: [{ InstanceIds: ['i-fleet-1'] }] });
+
+    const result = await createRunner(createRunnerConfig({
+      ...dedicatedHostRunnerConfig,
+      useDedicatedHost: undefined,
+    }));
+
+    expect(result).toEqual(['i-fleet-1']);
+    expect(mockEC2Client).toHaveReceivedCommand(CreateFleetCommand);
+    expect(mockEC2Client).not.toHaveReceivedCommand(RunInstancesCommand);
+  });
+
+  it('passes correct parameters to RunInstances', async () => {
+    await createRunner(createRunnerConfig(dedicatedHostRunnerConfig));
+
+    expect(mockEC2Client).toHaveReceivedCommandWith(RunInstancesCommand, {
+      LaunchTemplate: {
+        LaunchTemplateName: LAUNCH_TEMPLATE,
+        Version: '$Default',
+      },
+      InstanceType: 'm5.large',
+      MinCount: 1,
+      MaxCount: 1,
+      SubnetId: 'subnet-123',
+      TagSpecifications: [
+        {
+          ResourceType: 'instance',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'scale-up-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+        {
+          ResourceType: 'volume',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'scale-up-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('creates multiple instances via RunInstances', async () => {
+    mockEC2Client.on(RunInstancesCommand).resolves({
+      Instances: [{ InstanceId: 'i-dedicated-1' }, { InstanceId: 'i-dedicated-2' }],
+    });
+
+    const result = await createRunner({
+      ...createRunnerConfig(dedicatedHostRunnerConfig),
+      numberOfRunners: 2,
+    });
+
+    expect(result).toEqual(['i-dedicated-1', 'i-dedicated-2']);
+    expect(mockEC2Client).toHaveReceivedCommandWith(RunInstancesCommand, {
+      LaunchTemplate: {
+        LaunchTemplateName: LAUNCH_TEMPLATE,
+        Version: '$Default',
+      },
+      InstanceType: 'm5.large',
+      MinCount: 2,
+      MaxCount: 2,
+      SubnetId: 'subnet-123',
+      TagSpecifications: [
+        {
+          ResourceType: 'instance',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'pool-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+        {
+          ResourceType: 'volume',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'pool-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('throws error when spot is used with dedicated host', async () => {
+    await expect(
+      createRunner(createRunnerConfig({
+        ...dedicatedHostRunnerConfig,
+        capacityType: 'spot',
+      })),
+    ).rejects.toThrow('Spot instances are not supported with RunInstances');
+    expect(mockEC2Client).not.toHaveReceivedCommand(RunInstancesCommand);
+  });
+
+  it('throws error when RunInstances returns no instances', async () => {
+    mockEC2Client.on(RunInstancesCommand).resolves({ Instances: [] });
+
+    await expect(
+      createRunner(createRunnerConfig(dedicatedHostRunnerConfig)),
+    ).rejects.toThrow('RunInstances returned no instances for dedicated host.');
+  });
+
+  it('throws error when RunInstances fails', async () => {
+    mockEC2Client.on(RunInstancesCommand).rejects(new Error('EC2 error'));
+
+    await expect(
+      createRunner(createRunnerConfig(dedicatedHostRunnerConfig)),
+    ).rejects.toThrow('EC2 error');
+  });
+
+  it('uses ami id override from ssm parameter', async () => {
+    const paramValue: GetParameterResult = {
+      Parameter: {
+        Value: 'ami-dedicated',
+      },
+    };
+    mockSSMClient.on(GetParameterCommand).resolves(paramValue);
+
+    await createRunner(createRunnerConfig({
+      ...dedicatedHostRunnerConfig,
+      amiIdSsmParameterName: 'my-ami-id-param',
+    }));
+
+    expect(mockEC2Client).toHaveReceivedCommandWith(RunInstancesCommand, {
+      LaunchTemplate: {
+        LaunchTemplateName: LAUNCH_TEMPLATE,
+        Version: '$Default',
+      },
+      InstanceType: 'm5.large',
+      MinCount: 1,
+      MaxCount: 1,
+      SubnetId: 'subnet-123',
+      ImageId: 'ami-dedicated',
+      TagSpecifications: [
+        {
+          ResourceType: 'instance',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'scale-up-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+        {
+          ResourceType: 'volume',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'scale-up-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+      ],
+    });
+    expect(mockSSMClient).toHaveReceivedCommandWith(GetParameterCommand, {
+      Name: 'my-ami-id-param',
+    });
+  });
+});
diff --git a/lambdas/functions/control-plane/src/aws/runners.ts b/lambdas/functions/control-plane/src/aws/runners.ts
index 61edf99af6..4e105dd021 100644
--- a/lambdas/functions/control-plane/src/aws/runners.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.ts
@@ -5,6 +5,7 @@ import {
   DeleteTagsCommand,
   DescribeInstancesCommand,
   DescribeInstancesResult,
+  RunInstancesCommand,
   EC2Client,
   FleetLaunchTemplateOverridesRequest,
   Tag,
@@ -160,6 +161,15 @@ export async function createRunner(runnerParameters: Runners.RunnerInputParamete
   const ec2Client = getTracedAWSV3Client(new EC2Client({ region: process.env.AWS_REGION }));
   const amiIdOverride = await getAmiIdOverride(runnerParameters);
 
+  // EC2 Fleet (CreateFleet) does not support launching instances onto dedicated hosts
+  // for instance types like mac*.metal. Use RunInstances directly instead.
+  if (runnerParameters.useDedicatedHost) {
+    logger.info('Using RunInstances for dedicated host placement (CreateFleet does not support dedicated hosts).');
+    const instances = await createInstancesWithRunInstances(runnerParameters, amiIdOverride, ec2Client);
+    logger.info(`Created instance(s) via RunInstances: ${instances.join(',')}`);
+    return instances;
+  }
+
   const fleet: CreateFleetResult = await createInstances(runnerParameters, amiIdOverride, ec2Client);
 
   const instances: string[] = await processFleetResult(fleet, runnerParameters);
@@ -297,6 +307,7 @@ async function createInstances(
       ],
       Type: 'instant',
     });
+    logger.debug('CreateFleet request payload.', { payload: createFleetCommand.input });
     fleet = await ec2Client.send(createFleetCommand);
   } catch (e) {
     logger.warn('Create fleet request failed.', { error: e as Error });
@@ -305,6 +316,67 @@ async function createInstances(
   return fleet;
 }
 
+async function createInstancesWithRunInstances(
+  runnerParameters: Runners.RunnerInputParameters,
+  amiIdOverride: string | undefined,
+  ec2Client: EC2Client,
+): Promise<string[]> {
+  const tags = [
+    { Key: 'ghr:Application', Value: 'github-action-runner' },
+    { Key: 'ghr:created_by', Value: runnerParameters.numberOfRunners === 1 ? 'scale-up-lambda' : 'pool-lambda' },
+    { Key: 'ghr:Type', Value: runnerParameters.runnerType },
+    { Key: 'ghr:Owner', Value: runnerParameters.runnerOwner },
+  ];
+
+  if (runnerParameters.tracingEnabled) {
+    const traceId = tracer.getRootXrayTraceId();
+    tags.push({ Key: 'ghr:trace_id', Value: traceId! });
+  }
+
+  try {
+    if (runnerParameters.ec2instanceCriteria.targetCapacityType === 'spot') {
+      throw new Error('Spot instances are not supported with RunInstances. Please set targetCapacityType to on-demand for dedicated hosts.');
+    }
+
+    const instanceType = runnerParameters.ec2instanceCriteria.instanceTypes[0] as _InstanceType;
+    const runInstancesCommand = new RunInstancesCommand({
+      LaunchTemplate: {
+        LaunchTemplateName: runnerParameters.launchTemplateName,
+        Version: '$Default',
+      },
+      InstanceType: instanceType,
+      MinCount: runnerParameters.numberOfRunners,
+      MaxCount: runnerParameters.numberOfRunners,
+      SubnetId: runnerParameters.subnets[0],
+      ...(amiIdOverride ? { ImageId: amiIdOverride } : {}),
+      TagSpecifications: [
+        {
+          ResourceType: 'instance',
+          Tags: tags,
+        },
+        {
+          ResourceType: 'volume',
+          Tags: tags,
+        },
+      ],
+    });
+
+    logger.debug('RunInstances request payload.', { payload: runInstancesCommand.input });
+    const result = await ec2Client.send(runInstancesCommand);
+    const instanceIds = result.Instances?.map((i) => i.InstanceId!).filter(Boolean) || [];
+
+    if (instanceIds.length === 0) {
+      throw new Error('RunInstances returned no instances for dedicated host.');
+    }
+
+    return instanceIds;
+  } catch (e) {
+    logger.warn('RunInstances request failed for dedicated host.', { error: e as Error });
+    throw e;
+  }
+}
+
+
 // If launchTime is undefined, this will return false
 export function bootTimeExceeded(ec2Runner: { launchTime?: Date }): boolean {
   const runnerBootTimeInMinutes = process.env.RUNNER_BOOT_TIME_IN_MINUTES;
diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
index c9003c2e85..d7d49e0fab 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
@@ -114,6 +114,7 @@ const EXPECTED_RUNNER_PARAMS: RunnerInputParameters = {
   onDemandFailoverOnError: [],
   scaleErrors: ['UnfulfillableCapacity', 'MaxSpotInstanceCountExceeded', 'TargetCapacityLimitExceededException'],
   source: 'scale-up-lambda',    
+  useDedicatedHost: false,
 };
 let expectedRunnerParams: RunnerInputParameters;
 
@@ -3084,6 +3085,42 @@ describe('parseEc2OverrideConfig', () => {
   });
 });
 
+describe('useDedicatedHost', () => {
+  beforeEach(() => {
+    process.env.ENABLE_ORGANIZATION_RUNNERS = 'true';
+    process.env.ENABLE_EPHEMERAL_RUNNERS = 'true';
+    process.env.RUNNER_NAME_PREFIX = 'unit-test-';
+    process.env.RUNNER_GROUP_NAME = 'Default';
+    process.env.SSM_CONFIG_PATH = '/github-action-runners/default/runners/config';
+    process.env.SSM_TOKEN_PATH = '/github-action-runners/default/runners/config';
+    process.env.RUNNER_LABELS = 'label1,label2';
+  });
+
+  it('defaults to false when USE_DEDICATED_HOST env var is not set', async () => {
+    delete process.env.USE_DEDICATED_HOST;
+    await scaleUpModule.scaleUp(TEST_DATA);
+    expect(createRunner).toHaveBeenCalledWith(
+      expect.objectContaining({ useDedicatedHost: false }),
+    );
+  });
+
+  it('is true when USE_DEDICATED_HOST is "true"', async () => {
+    process.env.USE_DEDICATED_HOST = 'true';
+    await scaleUpModule.scaleUp(TEST_DATA);
+    expect(createRunner).toHaveBeenCalledWith(
+      expect.objectContaining({ useDedicatedHost: true }),
+    );
+  });
+
+  it('is false when USE_DEDICATED_HOST is "false"', async () => {
+    process.env.USE_DEDICATED_HOST = 'false';
+    await scaleUpModule.scaleUp(TEST_DATA);
+    expect(createRunner).toHaveBeenCalledWith(
+      expect.objectContaining({ useDedicatedHost: false }),
+    );
+  });
+});
+
 function defaultOctokitMockImpl() {
   mockOctokit.actions.getJobForWorkflowRun.mockImplementation(() => ({
     data: {
diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
index b51731f180..4f6f9bd42d 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.ts
@@ -99,6 +99,7 @@ interface CreateEC2RunnerConfig {
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
   scaleErrors: string[];
+  useDedicatedHost?: boolean;
 }
 
 function generateRunnerServiceConfig(githubRunnerConfig: CreateGitHubRunnerConfig, token: string) {
@@ -354,6 +355,7 @@ export async function scaleUp(payloads: ActionRequestMessageSQS[]): Promise<stri
       ? validateSsmParameterStoreTags(process.env.SSM_PARAMETER_STORE_TAGS)
       : [];
   const scaleErrors = JSON.parse(process.env.SCALE_ERRORS) as [string];
+  const useDedicatedHost = yn(process.env.USE_DEDICATED_HOST, { default: false });
 
   const { ghesApiUrl, ghesBaseUrl } = getGitHubEnterpriseApiUrl();
 
@@ -583,6 +585,7 @@ export async function scaleUp(payloads: ActionRequestMessageSQS[]): Promise<stri
         tracingEnabled,
         onDemandFailoverOnError,
         scaleErrors,
+        useDedicatedHost,
       },
       newRunners,
       githubInstallationClient,
diff --git a/main.tf b/main.tf
index 65f0801851..44757e29a4 100644
--- a/main.tf
+++ b/main.tf
@@ -211,6 +211,7 @@ module "runners" {
   cpu_options                          = var.runner_cpu_options
   placement                            = var.runner_placement
   license_specifications               = var.runner_license_specifications
+  use_dedicated_host                   = var.use_dedicated_host
 
   enable_runner_binaries_syncer                                  = var.enable_runner_binaries_syncer
   lambda_s3_bucket                                               = var.lambda_s3_bucket
diff --git a/modules/multi-runner/runners.tf b/modules/multi-runner/runners.tf
index d957100ef0..1695726f91 100644
--- a/modules/multi-runner/runners.tf
+++ b/modules/multi-runner/runners.tf
@@ -58,6 +58,7 @@ module "runners" {
   cpu_options                          = each.value.runner_config.cpu_options
   placement                            = each.value.runner_config.placement
   license_specifications               = each.value.runner_config.license_specifications
+  use_dedicated_host                   = each.value.runner_config.use_dedicated_host
 
   enable_runner_binaries_syncer                                  = each.value.runner_config.enable_runner_binaries_syncer
   lambda_s3_bucket                                               = var.lambda_s3_bucket
diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index e38383c697..75fad7f65d 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -152,6 +152,7 @@ variable "multi_runner_config" {
       license_specifications = optional(list(object({
         license_configuration_arn = string
       })), [])
+      use_dedicated_host = optional(bool, false)
       runner_log_files = optional(list(object({
         log_group_name   = string
         prefix_log_group = bool
diff --git a/modules/runners/pool.tf b/modules/runners/pool.tf
index 53c5d1c2cd..3434829018 100644
--- a/modules/runners/pool.tf
+++ b/modules/runners/pool.tf
@@ -52,6 +52,7 @@ module "pool" {
       name_prefix                          = var.runner_name_prefix
       pool_owner                           = var.pool_runner_owner
       role                                 = aws_iam_role.runner
+      use_dedicated_host                   = var.use_dedicated_host
     }
     subnet_ids                           = var.subnet_ids
     ssm_token_path                       = "${var.ssm_paths.root}/${var.ssm_paths.tokens}"
diff --git a/modules/runners/pool/main.tf b/modules/runners/pool/main.tf
index 5363f3c3fb..8f70713f9e 100644
--- a/modules/runners/pool/main.tf
+++ b/modules/runners/pool/main.tf
@@ -49,6 +49,7 @@ resource "aws_lambda_function" "pool" {
       ENABLE_ON_DEMAND_FAILOVER_FOR_ERRORS     = jsonencode(var.config.runner.enable_on_demand_failover_for_errors)
       SSM_PARAMETER_STORE_TAGS                 = var.config.lambda.parameter_store_tags
       SCALE_ERRORS                             = jsonencode(var.config.runner.scale_errors)
+      USE_DEDICATED_HOST                       = var.config.runner.use_dedicated_host
     }
   }
 
diff --git a/modules/runners/pool/variables.tf b/modules/runners/pool/variables.tf
index 4bfdd68010..a613c5563b 100644
--- a/modules/runners/pool/variables.tf
+++ b/modules/runners/pool/variables.tf
@@ -46,6 +46,7 @@ variable "config" {
       role = object({
         arn = string
       })
+      use_dedicated_host = bool
     })
     instance_types                = list(string)
     instance_target_capacity_type = string
diff --git a/modules/runners/scale-up.tf b/modules/runners/scale-up.tf
index d360520965..42787b1657 100644
--- a/modules/runners/scale-up.tf
+++ b/modules/runners/scale-up.tf
@@ -63,6 +63,7 @@ resource "aws_lambda_function" "scale_up" {
       ENABLE_ON_DEMAND_FAILOVER_FOR_ERRORS     = jsonencode(var.enable_on_demand_failover_for_errors)
       SCALE_ERRORS                             = jsonencode(var.scale_errors)
       JOB_RETRY_CONFIG                         = jsonencode(local.job_retry_config)
+      USE_DEDICATED_HOST                       = var.use_dedicated_host
     }
   }
 
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index c475ff9cef..f7973f3113 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -836,3 +836,9 @@ variable "parameter_store_tags" {
   type        = map(string)
   default     = {}
 }
+
+variable "use_dedicated_host" {
+  description = "Use a dedicated host for the runner instances."
+  type        = bool
+  default     = false
+}
diff --git a/variables.tf b/variables.tf
index 40a40dbcdc..37a3df78a0 100644
--- a/variables.tf
+++ b/variables.tf
@@ -1082,3 +1082,9 @@ variable "parameter_store_tags" {
   type        = map(string)
   default     = {}
 }
+
+variable "use_dedicated_host" {
+  description = "Use a dedicated host for the runner instances."
+  type        = bool
+  default     = false
+}

From c1d7e4db013dece4d3cb40fa7d3283109b33106c Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 6 Mar 2026 21:43:46 +0000
Subject: [PATCH 29/46] docs: auto update terraform docs

---
 README.md                      | 1 +
 modules/multi-runner/README.md | 1 +
 modules/runners/README.md      | 1 +
 3 files changed, 3 insertions(+)

diff --git a/README.md b/README.md
index d845428698..64671fb1db 100644
--- a/README.md
+++ b/README.md
@@ -225,6 +225,7 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_syncer_lambda_s3_object_version"></a> [syncer\_lambda\_s3\_object\_version](#input\_syncer\_lambda\_s3\_object\_version) | S3 object version for syncer lambda function. Useful if S3 versioning is enabled on source bucket. | `string` | `null` | no |
 | <a name="input_tags"></a> [tags](#input\_tags) | Map of tags that will be added to created resources. By default resources will be tagged with name and environment. | `map(string)` | `{}` | no |
 | <a name="input_tracing_config"></a> [tracing\_config](#input\_tracing\_config) | Configuration for lambda tracing. | <pre>object({<br/>    mode                  = optional(string, null)<br/>    capture_http_requests = optional(bool, false)<br/>    capture_error         = optional(bool, false)<br/>  })</pre> | `{}` | no |
+| <a name="input_use_dedicated_host"></a> [use\_dedicated\_host](#input\_use\_dedicated\_host) | Use a dedicated host for the runner instances. | `bool` | `false` | no |
 | <a name="input_user_agent"></a> [user\_agent](#input\_user\_agent) | User agent used for API calls by lambda functions. | `string` | `"github-aws-runners"` | no |
 | <a name="input_userdata_content"></a> [userdata\_content](#input\_userdata\_content) | Alternative user-data content, replacing the templated one. By providing your own user\_data you have to take care of installing all required software, including the action runner and registering the runner.  Be-aware configuration parameters in SSM as well as tags are treated as internals. Changes will not trigger a breaking release. | `string` | `null` | no |
 | <a name="input_userdata_post_install"></a> [userdata\_post\_install](#input\_userdata\_post\_install) | Script to be ran after the GitHub Actions runner is installed on the EC2 instances | `string` | `""` | no |
diff --git a/modules/multi-runner/README.md b/modules/multi-runner/README.md
index 0488db417f..15d584ca51 100644
--- a/modules/multi-runner/README.md
+++ b/modules/multi-runner/README.md
@@ -152,6 +152,7 @@ module "multi-runner" {
 | <a name="input_logging_retention_in_days"></a> [logging\_retention\_in\_days](#input\_logging\_retention\_in\_days) | Specifies the number of days you want to retain log events for the lambda log group. Possible values are: 0, 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, and 3653. | `number` | `180` | no |
 | <a name="input_matcher_config_parameter_store_tier"></a> [matcher\_config\_parameter\_store\_tier](#input\_matcher\_config\_parameter\_store\_tier) | The tier of the parameter store for the matcher configuration. Valid values are `Standard`, and `Advanced`. | `string` | `"Standard"` | no |
 | <a name="input_metrics"></a> [metrics](#input\_metrics) | Configuration for metrics created by the module, by default metrics are disabled to avoid additional costs. When metrics are enable all metrics are created unless explicit configured otherwise. | <pre>object({<br/>    enable    = optional(bool, false)<br/>    namespace = optional(string, "GitHub Runners")<br/>    metric = optional(object({<br/>      enable_github_app_rate_limit    = optional(bool, true)<br/>      enable_job_retry                = optional(bool, true)<br/>      enable_spot_termination_warning = optional(bool, true)<br/>    }), {})<br/>  })</pre> | `{}` | no |
+| <a name="input_multi_runner_config"></a> [multi\_runner\_config](#input\_multi\_runner\_config) | multi\_runner\_config = {<br/>      runner\_config: {<br/>        runner\_os: "The EC2 Operating System type to use for action runner instances (linux,windows)."<br/>        runner\_architecture: "The platform architecture of the runner instance\_type."<br/>        runner\_metadata\_options: "(Optional) Metadata options for the ec2 runner instances."<br/>        ami: "(Optional) AMI configuration for the action runner instances. This object allows you to specify all AMI-related settings in one place."<br/>        create\_service\_linked\_role\_spot: (Optional) create the serviced linked role for spot instances that is required by the scale-up lambda.<br/>        credit\_specification: "(Optional) The credit specification of the runner instance\_type. Can be unset, `standard` or `unlimited`.<br/>        delay\_webhook\_event: "The number of seconds the event accepted by the webhook is invisible on the queue before the scale up lambda will receive the event."<br/>        disable\_runner\_autoupdate: "Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/)"<br/>        ebs\_optimized: "The EC2 EBS optimized configuration."<br/>        enable\_ephemeral\_runners: "Enable ephemeral runners, runners will only be used once."<br/>        enable\_job\_queued\_check: "Enables JIT configuration for creating runners instead of registration token based registraton. JIT configuration will only be applied for ephemeral runners. By default JIT configuration is enabled for ephemeral runners an can be disabled via this override. When running on GHES without support for JIT configuration this variable should be set to true for ephemeral runners."<br/>        enable\_on\_demand\_failover\_for\_errors: "Enable on-demand failover. For example to fall back to on demand when no spot capacity is available the variable can be set to `InsufficientInstanceCapacity`. When not defined the default behavior is to retry later."<br/>        scale\_errors: "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"<br/>        enable\_organization\_runners: "Register runners to organization, instead of repo level"<br/>        enable\_runner\_binaries\_syncer: "Option to disable the lambda to sync GitHub runner distribution, useful when using a pre-build AMI."<br/>        enable\_ssm\_on\_runners: "Enable to allow access the runner instances for debugging purposes via SSM. Note that this adds additional permissions to the runner instances."<br/>        enable\_userdata: "Should the userdata script be enabled for the runner. Set this to false if you are using your own prebuilt AMI."<br/>        instance\_allocation\_strategy: "The allocation strategy for spot instances. AWS recommends to use `capacity-optimized` however the AWS default is `lowest-price`."<br/>        instance\_max\_spot\_price: "Max price price for spot instances per hour. This variable will be passed to the create fleet as max spot price for the fleet."<br/>        instance\_target\_capacity\_type: "Default lifecycle used for runner instances, can be either `spot` or `on-demand`."<br/>        instance\_types: "List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux and Windows Server Core for win)."<br/>        job\_queue\_retention\_in\_seconds: "The number of seconds the job is held in the queue before it is purged"<br/>        minimum\_running\_time\_in\_minutes: "The time an ec2 action runner should be running at minimum before terminated if not busy."<br/>        pool\_runner\_owner: "The pool will deploy runners to the GitHub org ID, set this value to the org to which you want the runners deployed. Repo level is not supported."<br/>        runner\_additional\_security\_group\_ids: "List of additional security groups IDs to apply to the runner. If added outside the multi\_runner\_config block, the additional security group(s) will be applied to all runner configs. If added inside the multi\_runner\_config, the additional security group(s) will be applied to the individual runner."<br/>        runner\_as\_root: "Run the action runner under the root user. Variable `runner_run_as` will be ignored."<br/>        runner\_boot\_time\_in\_minutes: "The minimum time for an EC2 runner to boot and register as a runner."<br/>        runner\_disable\_default\_labels: "Disable default labels for the runners (os, architecture and `self-hosted`). If enabled, the runner will only have the extra labels provided in `runner_extra_labels`. In case you on own start script is used, this configuration parameter needs to be parsed via SSM."<br/>        runner\_extra\_labels: "Extra (custom) labels for the runners (GitHub). Separate each label by a comma. Labels checks on the webhook can be enforced by setting `multi_runner_config.matcherConfig.exactMatch`. GitHub read-only labels should not be provided."<br/>        runner\_group\_name: "Name of the runner group."<br/>        runner\_name\_prefix: "Prefix for the GitHub runner name."<br/>        runner\_run\_as: "Run the GitHub actions agent as user."<br/>        runners\_maximum\_count: "The maximum number of runners that will be created. Setting the variable to `-1` desiables the maximum check."<br/>        scale\_down\_schedule\_expression: "Scheduler expression to check every x for scale down."<br/>        scale\_up\_reserved\_concurrent\_executions: "Amount of reserved concurrent executions for the scale-up lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations."<br/>        userdata\_template: "Alternative user-data template, replacing the default template. By providing your own user\_data you have to take care of installing all required software, including the action runner. Variables userdata\_pre/post\_install are ignored."<br/>        enable\_jit\_config "Overwrite the default behavior for JIT configuration. By default JIT configuration is enabled for ephemeral runners and disabled for non-ephemeral runners. In case of GHES check first if the JIT config API is available. In case you are upgrading from 3.x to 4.x you can set `enable_jit_config` to `false` to avoid a breaking change when having your own AMI."<br/>        enable\_runner\_detailed\_monitoring: "Should detailed monitoring be enabled for the runner. Set this to true if you want to use detailed monitoring. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html for details."<br/>        enable\_cloudwatch\_agent: "Enabling the cloudwatch agent on the ec2 runner instances, the runner contains default config. Configuration can be overridden via `cloudwatch_config`."<br/>        cloudwatch\_config: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        userdata\_pre\_install: "Script to be ran before the GitHub Actions runner is installed on the EC2 instances"<br/>        userdata\_post\_install: "Script to be ran after the GitHub Actions runner is installed on the EC2 instances"<br/>        runner\_hook\_job\_started: "Script to be ran in the runner environment at the beginning of every job"<br/>        runner\_hook\_job\_completed: "Script to be ran in the runner environment at the end of every job"<br/>        runner\_ec2\_tags: "Map of tags that will be added to the launch template instance tag specifications."<br/>        runner\_iam\_role\_managed\_policy\_arns: "Attach AWS or customer-managed IAM policies (by ARN) to the runner IAM role"<br/>        vpc\_id: "The VPC for security groups of the action runners. If not set uses the value of `var.vpc_id`."<br/>        subnet\_ids: "List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. If not set, uses the value of `var.subnet_ids`."<br/>        idle\_config: "List of time period that can be defined as cron expression to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."<br/>        runner\_log\_files: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        block\_device\_mappings: "The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`."<br/>        job\_retry: "Experimental! Can be removed / changed without trigger a major release. Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app."<br/>        pool\_config: "The configuration for updating the pool. The `pool_size` to adjust to by the events triggered by the `schedule_expression`. For example you can configure a cron expression for week days to adjust the pool to 10 and another expression for the weekend to adjust the pool to 1. Use `schedule_expression_timezone` to override the schedule time zone (defaults to UTC)."<br/>      }<br/>      matcherConfig: {<br/>        labelMatchers: "The list of list of labels supported by the runner configuration. `[[self-hosted, linux, x64, example]]`"<br/>        exactMatch: "If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ workflow label matches it will trigger the webhook."<br/>        priority: "If set it defines the priority of the matcher, the matcher with the lowest priority will be evaluated first. Default is 999, allowed values 0-999."<br/>      }<br/>      redrive\_build\_queue: "Set options to attach (optional) a dead letter queue to the build queue, the queue between the webhook and the scale up lambda. You have the following options. 1. Disable by setting `enabled` to false. 2. Enable by setting `enabled` to `true`, `maxReceiveCount` to a number of max retries."<br/>    } | <pre>map(object({<br/>    runner_config = object({<br/>      runner_os           = string<br/>      runner_architecture = string<br/>      runner_metadata_options = optional(map(any), {<br/>        instance_metadata_tags      = "enabled"<br/>        http_endpoint               = "enabled"<br/>        http_tokens                 = "required"<br/>        http_put_response_hop_limit = 1<br/>      })<br/>      ami = optional(object({<br/>        filter               = optional(map(list(string)), { state = ["available"] })<br/>        owners               = optional(list(string), ["amazon"])<br/>        id_ssm_parameter_arn = optional(string, null)<br/>        kms_key_arn          = optional(string, null)<br/>      }), null)<br/>      create_service_linked_role_spot      = optional(bool, false)<br/>      credit_specification                 = optional(string, null)<br/>      delay_webhook_event                  = optional(number, 30)<br/>      disable_runner_autoupdate            = optional(bool, false)<br/>      ebs_optimized                        = optional(bool, false)<br/>      enable_ephemeral_runners             = optional(bool, false)<br/>      enable_job_queued_check              = optional(bool, null)<br/>      enable_on_demand_failover_for_errors = optional(list(string), [])<br/>      scale_errors = optional(list(string), [<br/>        "UnfulfillableCapacity",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "TargetCapacityLimitExceededException",<br/>        "RequestLimitExceeded",<br/>        "ResourceLimitExceeded",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "MaxSpotFleetRequestCountExceeded",<br/>        "InsufficientInstanceCapacity",<br/>        "InsufficientCapacityOnHost",<br/>      ])<br/>      enable_organization_runners             = optional(bool, false)<br/>      enable_runner_binaries_syncer           = optional(bool, true)<br/>      enable_ssm_on_runners                   = optional(bool, false)<br/>      enable_userdata                         = optional(bool, true)<br/>      instance_allocation_strategy            = optional(string, "lowest-price")<br/>      instance_max_spot_price                 = optional(string, null)<br/>      instance_target_capacity_type           = optional(string, "spot")<br/>      instance_types                          = list(string)<br/>      job_queue_retention_in_seconds          = optional(number, 86400)<br/>      minimum_running_time_in_minutes         = optional(number, null)<br/>      pool_runner_owner                       = optional(string, null)<br/>      runner_as_root                          = optional(bool, false)<br/>      runner_boot_time_in_minutes             = optional(number, 5)<br/>      runner_disable_default_labels           = optional(bool, false)<br/>      runner_extra_labels                     = optional(list(string), [])<br/>      runner_group_name                       = optional(string, "Default")<br/>      runner_name_prefix                      = optional(string, "")<br/>      runner_run_as                           = optional(string, "ec2-user")<br/>      runners_maximum_count                   = number<br/>      runner_additional_security_group_ids    = optional(list(string), [])<br/>      scale_down_schedule_expression          = optional(string, "cron(*/5 * * * ? *)")<br/>      scale_up_reserved_concurrent_executions = optional(number, 1)<br/>      userdata_template                       = optional(string, null)<br/>      userdata_content                        = optional(string, null)<br/>      enable_jit_config                       = optional(bool, null)<br/>      enable_runner_detailed_monitoring       = optional(bool, false)<br/>      enable_cloudwatch_agent                 = optional(bool, true)<br/>      cloudwatch_config                       = optional(string, null)<br/>      userdata_pre_install                    = optional(string, "")<br/>      userdata_post_install                   = optional(string, "")<br/>      runner_hook_job_started                 = optional(string, "")<br/>      runner_hook_job_completed               = optional(string, "")<br/>      runner_ec2_tags                         = optional(map(string), {})<br/>      runner_iam_role_managed_policy_arns     = optional(list(string), [])<br/>      vpc_id                                  = optional(string, null)<br/>      subnet_ids                              = optional(list(string), null)<br/>      idle_config = optional(list(object({<br/>        cron             = string<br/>        timeZone         = string<br/>        idleCount        = number<br/>        evictionStrategy = optional(string, "oldest_first")<br/>      })), [])<br/>      cpu_options = optional(object({<br/>        core_count       = number<br/>        threads_per_core = number<br/>      }), null)<br/>      placement = optional(object({<br/>        affinity                = optional(string)<br/>        availability_zone       = optional(string)<br/>        group_id                = optional(string)<br/>        group_name              = optional(string)<br/>        host_id                 = optional(string)<br/>        host_resource_group_arn = optional(string)<br/>        spread_domain           = optional(string)<br/>        tenancy                 = optional(string)<br/>        partition_number        = optional(number)<br/>      }), null)<br/>      runner_log_files = optional(list(object({<br/>        log_group_name   = string<br/>        prefix_log_group = bool<br/>        file_path        = string<br/>        log_stream_name  = string<br/>        log_class        = optional(string, "STANDARD")<br/>      })), null)<br/>      block_device_mappings = optional(list(object({<br/>        delete_on_termination = optional(bool, true)<br/>        device_name           = optional(string, "/dev/xvda")<br/>        encrypted             = optional(bool, true)<br/>        iops                  = optional(number)<br/>        kms_key_id            = optional(string)<br/>        snapshot_id           = optional(string)<br/>        throughput            = optional(number)<br/>        volume_size           = number<br/>        volume_type           = optional(string, "gp3")<br/>        })), [{<br/>        volume_size = 30<br/>      }])<br/>      pool_config = optional(list(object({<br/>        schedule_expression          = string<br/>        schedule_expression_timezone = optional(string)<br/>        size                         = number<br/>      })), [])<br/>      job_retry = optional(object({<br/>        enable             = optional(bool, false)<br/>        delay_in_seconds   = optional(number, 300)<br/>        delay_backoff      = optional(number, 2)<br/>        lambda_memory_size = optional(number, 256)<br/>        lambda_timeout     = optional(number, 30)<br/>        max_attempts       = optional(number, 1)<br/>      }), {})<br/>    })<br/>    matcherConfig = object({<br/>      labelMatchers = list(list(string))<br/>      exactMatch    = optional(bool, false)<br/>      priority      = optional(number, 999)<br/>    })<br/>    redrive_build_queue = optional(object({<br/>      enabled         = bool<br/>      maxReceiveCount = number<br/>      }), {<br/>      enabled         = false<br/>      maxReceiveCount = null<br/>    })<br/>  }))</pre> | n/a | yes |
 | <a name="input_multi_runner_config"></a> [multi\_runner\_config](#input\_multi\_runner\_config) | multi\_runner\_config = {<br/>      runner\_config: {<br/>        runner\_os: "The EC2 Operating System type to use for action runner instances (linux,windows)."<br/>        runner\_architecture: "The platform architecture of the runner instance\_type."<br/>        runner\_metadata\_options: "(Optional) Metadata options for the ec2 runner instances."<br/>        ami: "(Optional) AMI configuration for the action runner instances. This object allows you to specify all AMI-related settings in one place."<br/>        create\_service\_linked\_role\_spot: (Optional) create the serviced linked role for spot instances that is required by the scale-up lambda.<br/>        credit\_specification: "(Optional) The credit specification of the runner instance\_type. Can be unset, `standard` or `unlimited`.<br/>        delay\_webhook\_event: "The number of seconds the event accepted by the webhook is invisible on the queue before the scale up lambda will receive the event."<br/>        disable\_runner\_autoupdate: "Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/)"<br/>        ebs\_optimized: "The EC2 EBS optimized configuration."<br/>        enable\_ephemeral\_runners: "Enable ephemeral runners, runners will only be used once."<br/>        enable\_dynamic\_labels: "Experimental! Can be removed / changed without trigger a major release. Enable dynamic labels with 'ghr-' prefix. When enabled, jobs can use 'ghr-ec2-<config>:<value>' labels to dynamically configure EC2 instances (e.g., 'ghr-ec2-instance-type:t3.large') and 'ghr-run-<label>' to add unique labels dynamically to runners."<br/>        enable\_job\_queued\_check: Enables JIT configuration for creating runners instead of registration token based registraton. JIT configuration will only be applied for ephemeral runners. By default JIT configuration is enabled for ephemeral runners an can be disabled via this override. When running on GHES without support for JIT configuration this variable should be set to true for ephemeral runners."<br/>        enable\_on\_demand\_failover\_for\_errors: "Enable on-demand failover. For example to fall back to on demand when no spot capacity is available the variable can be set to `InsufficientInstanceCapacity`. When not defined the default behavior is to retry later."<br/>        scale\_errors: "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"<br/>        enable\_organization\_runners: "Register runners to organization, instead of repo level"<br/>        enable\_runner\_binaries\_syncer: "Option to disable the lambda to sync GitHub runner distribution, useful when using a pre-build AMI."<br/>        enable\_ssm\_on\_runners: "Enable to allow access the runner instances for debugging purposes via SSM. Note that this adds additional permissions to the runner instances."<br/>        enable\_userdata: "Should the userdata script be enabled for the runner. Set this to false if you are using your own prebuilt AMI."<br/>        instance\_allocation\_strategy: "The allocation strategy for spot instances. AWS recommends to use `capacity-optimized` however the AWS default is `lowest-price`."<br/>        instance\_max\_spot\_price: "Max price price for spot instances per hour. This variable will be passed to the create fleet as max spot price for the fleet."<br/>        instance\_target\_capacity\_type: "Default lifecycle used for runner instances, can be either `spot` or `on-demand`."<br/>        instance\_types: "List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux and Windows Server Core for win)."<br/>        job\_queue\_retention\_in\_seconds: "The number of seconds the job is held in the queue before it is purged"<br/>        minimum\_running\_time\_in\_minutes: "The time an ec2 action runner should be running at minimum before terminated if not busy."<br/>        pool\_runner\_owner: "The pool will deploy runners to the GitHub org ID, set this value to the org to which you want the runners deployed. Repo level is not supported."<br/>        runner\_additional\_security\_group\_ids: "List of additional security groups IDs to apply to the runner. If added outside the multi\_runner\_config block, the additional security group(s) will be applied to all runner configs. If added inside the multi\_runner\_config, the additional security group(s) will be applied to the individual runner."<br/>        runner\_as\_root: "Run the action runner under the root user. Variable `runner_run_as` will be ignored."<br/>        runner\_boot\_time\_in\_minutes: "The minimum time for an EC2 runner to boot and register as a runner."<br/>        runner\_disable\_default\_labels: "Disable default labels for the runners (os, architecture and `self-hosted`). If enabled, the runner will only have the extra labels provided in `runner_extra_labels`. In case you on own start script is used, this configuration parameter needs to be parsed via SSM."<br/>        runner\_extra\_labels: "Extra (custom) labels for the runners (GitHub). Separate each label by a comma. Labels checks on the webhook can be enforced by setting `multi_runner_config.matcherConfig.exactMatch`. GitHub read-only labels should not be provided."<br/>        runner\_group\_name: "Name of the runner group."<br/>        runner\_name\_prefix: "Prefix for the GitHub runner name."<br/>        runner\_run\_as: "Run the GitHub actions agent as user."<br/>        runners\_maximum\_count: "The maximum number of runners that will be created. Setting the variable to `-1` desiables the maximum check."<br/>        scale\_down\_schedule\_expression: "Scheduler expression to check every x for scale down."<br/>        scale\_up\_reserved\_concurrent\_executions: "Amount of reserved concurrent executions for the scale-up lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations."<br/>        userdata\_template: "Alternative user-data template, replacing the default template. By providing your own user\_data you have to take care of installing all required software, including the action runner. Variables userdata\_pre/post\_install are ignored."<br/>        enable\_jit\_config "Overwrite the default behavior for JIT configuration. By default JIT configuration is enabled for ephemeral runners and disabled for non-ephemeral runners. In case of GHES check first if the JIT config API is available. In case you are upgrading from 3.x to 4.x you can set `enable_jit_config` to `false` to avoid a breaking change when having your own AMI."<br/>        enable\_runner\_detailed\_monitoring: "Should detailed monitoring be enabled for the runner. Set this to true if you want to use detailed monitoring. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html for details."<br/>        enable\_cloudwatch\_agent: "Enabling the cloudwatch agent on the ec2 runner instances, the runner contains default config. Configuration can be overridden via `cloudwatch_config`."<br/>        cloudwatch\_config: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        userdata\_pre\_install: "Script to be ran before the GitHub Actions runner is installed on the EC2 instances"<br/>        userdata\_post\_install: "Script to be ran after the GitHub Actions runner is installed on the EC2 instances"<br/>        runner\_hook\_job\_started: "Script to be ran in the runner environment at the beginning of every job"<br/>        runner\_hook\_job\_completed: "Script to be ran in the runner environment at the end of every job"<br/>        runner\_ec2\_tags: "Map of tags that will be added to the launch template instance tag specifications."<br/>        runner\_iam\_role\_managed\_policy\_arns: "Attach AWS or customer-managed IAM policies (by ARN) to the runner IAM role"<br/>        vpc\_id: "The VPC for security groups of the action runners. If not set uses the value of `var.vpc_id`."<br/>        subnet\_ids: "List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. If not set, uses the value of `var.subnet_ids`."<br/>        idle\_config: "List of time period that can be defined as cron expression to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."<br/>        runner\_log\_files: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        block\_device\_mappings: "The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`."<br/>        job\_retry: "Experimental! Can be removed / changed without trigger a major release. Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app."<br/>        pool\_config: "The configuration for updating the pool. The `pool_size` to adjust to by the events triggered by the `schedule_expression`. For example you can configure a cron expression for week days to adjust the pool to 10 and another expression for the weekend to adjust the pool to 1. Use `schedule_expression_timezone` to override the schedule time zone (defaults to UTC)."<br/>      }<br/>      matcherConfig: {<br/>        labelMatchers: "The list of list of labels supported by the runner configuration. `[[self-hosted, linux, x64, example]]`"<br/>        exactMatch: "If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ workflow label matches it will trigger the webhook."<br/>        priority: "If set it defines the priority of the matcher, the matcher with the lowest priority will be evaluated first. Default is 999, allowed values 0-999."<br/>      }<br/>      redrive\_build\_queue: "Set options to attach (optional) a dead letter queue to the build queue, the queue between the webhook and the scale up lambda. You have the following options. 1. Disable by setting `enabled` to false. 2. Enable by setting `enabled` to `true`, `maxReceiveCount` to a number of max retries."<br/>    } | <pre>map(object({<br/>    runner_config = object({<br/>      runner_os           = string<br/>      runner_architecture = string<br/>      runner_metadata_options = optional(map(any), {<br/>        instance_metadata_tags      = "enabled"<br/>        http_endpoint               = "enabled"<br/>        http_tokens                 = "required"<br/>        http_put_response_hop_limit = 1<br/>      })<br/>      ami = optional(object({<br/>        filter               = optional(map(list(string)), { state = ["available"] })<br/>        owners               = optional(list(string), ["amazon"])<br/>        id_ssm_parameter_arn = optional(string, null)<br/>        kms_key_arn          = optional(string, null)<br/>      }), null)<br/>      create_service_linked_role_spot      = optional(bool, false)<br/>      credit_specification                 = optional(string, null)<br/>      delay_webhook_event                  = optional(number, 30)<br/>      disable_runner_autoupdate            = optional(bool, false)<br/>      ebs_optimized                        = optional(bool, false)<br/>      enable_ephemeral_runners             = optional(bool, false)<br/>      enable_job_queued_check              = optional(bool, null)<br/>      enable_on_demand_failover_for_errors = optional(list(string), [])<br/>      scale_errors = optional(list(string), [<br/>        "UnfulfillableCapacity",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "TargetCapacityLimitExceededException",<br/>        "RequestLimitExceeded",<br/>        "ResourceLimitExceeded",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "MaxSpotFleetRequestCountExceeded",<br/>        "InsufficientInstanceCapacity",<br/>        "InsufficientCapacityOnHost",<br/>      ])<br/>      enable_organization_runners             = optional(bool, false)<br/>      enable_runner_binaries_syncer           = optional(bool, true)<br/>      enable_ssm_on_runners                   = optional(bool, false)<br/>      enable_userdata                         = optional(bool, true)<br/>      instance_allocation_strategy            = optional(string, "lowest-price")<br/>      instance_max_spot_price                 = optional(string, null)<br/>      instance_target_capacity_type           = optional(string, "spot")<br/>      instance_types                          = list(string)<br/>      job_queue_retention_in_seconds          = optional(number, 86400)<br/>      minimum_running_time_in_minutes         = optional(number, null)<br/>      pool_runner_owner                       = optional(string, null)<br/>      runner_as_root                          = optional(bool, false)<br/>      runner_boot_time_in_minutes             = optional(number, 5)<br/>      runner_disable_default_labels           = optional(bool, false)<br/>      runner_extra_labels                     = optional(list(string), [])<br/>      runner_group_name                       = optional(string, "Default")<br/>      runner_name_prefix                      = optional(string, "")<br/>      runner_run_as                           = optional(string, "ec2-user")<br/>      runners_maximum_count                   = number<br/>      runner_additional_security_group_ids    = optional(list(string), [])<br/>      scale_down_schedule_expression          = optional(string, "cron(*/5 * * * ? *)")<br/>      scale_up_reserved_concurrent_executions = optional(number, 1)<br/>      userdata_template                       = optional(string, null)<br/>      userdata_content                        = optional(string, null)<br/>      enable_jit_config                       = optional(bool, null)<br/>      enable_runner_detailed_monitoring       = optional(bool, false)<br/>      enable_cloudwatch_agent                 = optional(bool, true)<br/>      cloudwatch_config                       = optional(string, null)<br/>      userdata_pre_install                    = optional(string, "")<br/>      userdata_post_install                   = optional(string, "")<br/>      runner_hook_job_started                 = optional(string, "")<br/>      runner_hook_job_completed               = optional(string, "")<br/>      runner_ec2_tags                         = optional(map(string), {})<br/>      runner_iam_role_managed_policy_arns     = optional(list(string), [])<br/>      vpc_id                                  = optional(string, null)<br/>      subnet_ids                              = optional(list(string), null)<br/>      idle_config = optional(list(object({<br/>        cron             = string<br/>        timeZone         = string<br/>        idleCount        = number<br/>        evictionStrategy = optional(string, "oldest_first")<br/>      })), [])<br/>      cpu_options = optional(object({<br/>        core_count       = number<br/>        threads_per_core = number<br/>      }), null)<br/>      placement = optional(object({<br/>        affinity                = optional(string)<br/>        availability_zone       = optional(string)<br/>        group_id                = optional(string)<br/>        group_name              = optional(string)<br/>        host_id                 = optional(string)<br/>        host_resource_group_arn = optional(string)<br/>        spread_domain           = optional(string)<br/>        tenancy                 = optional(string)<br/>        partition_number        = optional(number)<br/>      }), null)<br/>      runner_log_files = optional(list(object({<br/>        log_group_name   = string<br/>        prefix_log_group = bool<br/>        file_path        = string<br/>        log_stream_name  = string<br/>        log_class        = optional(string, "STANDARD")<br/>      })), null)<br/>      block_device_mappings = optional(list(object({<br/>        delete_on_termination = optional(bool, true)<br/>        device_name           = optional(string, "/dev/xvda")<br/>        encrypted             = optional(bool, true)<br/>        iops                  = optional(number)<br/>        kms_key_id            = optional(string)<br/>        snapshot_id           = optional(string)<br/>        throughput            = optional(number)<br/>        volume_size           = number<br/>        volume_type           = optional(string, "gp3")<br/>        })), [{<br/>        volume_size = 30<br/>      }])<br/>      pool_config = optional(list(object({<br/>        schedule_expression          = string<br/>        schedule_expression_timezone = optional(string)<br/>        size                         = number<br/>      })), [])<br/>      job_retry = optional(object({<br/>        enable             = optional(bool, false)<br/>        delay_in_seconds   = optional(number, 300)<br/>        delay_backoff      = optional(number, 2)<br/>        lambda_memory_size = optional(number, 256)<br/>        lambda_timeout     = optional(number, 30)<br/>        max_attempts       = optional(number, 1)<br/>      }), {})<br/>    })<br/>    matcherConfig = object({<br/>      labelMatchers = list(list(string))<br/>      exactMatch    = optional(bool, false)<br/>      priority      = optional(number, 999)<br/>    })<br/>    redrive_build_queue = optional(object({<br/>      enabled         = bool<br/>      maxReceiveCount = number<br/>      }), {<br/>      enabled         = false<br/>      maxReceiveCount = null<br/>    })<br/>  }))</pre> | n/a | yes |
 | <a name="input_parameter_store_tags"></a> [parameter\_store\_tags](#input\_parameter\_store\_tags) | Map of tags that will be added to all the SSM Parameter Store parameters created by the Lambda function. | `map(string)` | `{}` | no |
 | <a name="input_pool_lambda_reserved_concurrent_executions"></a> [pool\_lambda\_reserved\_concurrent\_executions](#input\_pool\_lambda\_reserved\_concurrent\_executions) | Amount of reserved concurrent executions for the scale-up lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations. | `number` | `1` | no |
diff --git a/modules/runners/README.md b/modules/runners/README.md
index 02a0731c1d..38c81a155b 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -232,6 +232,7 @@ yarn run dist
 | <a name="input_subnet_ids"></a> [subnet\_ids](#input\_subnet\_ids) | List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. | `list(string)` | n/a | yes |
 | <a name="input_tags"></a> [tags](#input\_tags) | Map of tags that will be added to created resources. By default resources will be tagged with name. | `map(string)` | `{}` | no |
 | <a name="input_tracing_config"></a> [tracing\_config](#input\_tracing\_config) | Configuration for lambda tracing. | <pre>object({<br/>    mode                  = optional(string, null)<br/>    capture_http_requests = optional(bool, false)<br/>    capture_error         = optional(bool, false)<br/>  })</pre> | `{}` | no |
+| <a name="input_use_dedicated_host"></a> [use\_dedicated\_host](#input\_use\_dedicated\_host) | Use a dedicated host for the runner instances. | `bool` | `false` | no |
 | <a name="input_user_agent"></a> [user\_agent](#input\_user\_agent) | User agent used for API calls. | `string` | `null` | no |
 | <a name="input_userdata_content"></a> [userdata\_content](#input\_userdata\_content) | Alternative user-data content, replacing the templated one. By providing your own user\_data you have to take care of installing all required software, including the action runner and registering the runner.  Be-aware configuration parameters in SSM as well as tags are treated as internals. Changes will not trigger a breaking release. | `string` | `null` | no |
 | <a name="input_userdata_post_install"></a> [userdata\_post\_install](#input\_userdata\_post\_install) | User-data script snippet to insert after GitHub action runner install | `string` | `""` | no |

From 2d5e486770294639955efb629e104f5099032fc3 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Sat, 7 Mar 2026 00:08:40 +0100
Subject: [PATCH 30/46] style: fix yarn lint

---
 .../control-plane/src/aws/runners.test.ts     | 50 +++++++++++--------
 .../control-plane/src/aws/runners.ts          |  5 +-
 .../src/scale-runners/scale-up.test.ts        | 12 ++---
 3 files changed, 34 insertions(+), 33 deletions(-)

diff --git a/lambdas/functions/control-plane/src/aws/runners.test.ts b/lambdas/functions/control-plane/src/aws/runners.test.ts
index 3fdbe5fc2f..2c332101d4 100644
--- a/lambdas/functions/control-plane/src/aws/runners.test.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.test.ts
@@ -1108,10 +1108,12 @@ describe('create runner with useDedicatedHost', () => {
   it('uses CreateFleet when useDedicatedHost is false', async () => {
     mockEC2Client.on(CreateFleetCommand).resolves({ Instances: [{ InstanceIds: ['i-fleet-1'] }] });
 
-    const result = await createRunner(createRunnerConfig({
-      ...dedicatedHostRunnerConfig,
-      useDedicatedHost: false,
-    }));
+    const result = await createRunner(
+      createRunnerConfig({
+        ...dedicatedHostRunnerConfig,
+        useDedicatedHost: false,
+      }),
+    );
 
     expect(result).toEqual(['i-fleet-1']);
     expect(mockEC2Client).toHaveReceivedCommand(CreateFleetCommand);
@@ -1121,10 +1123,12 @@ describe('create runner with useDedicatedHost', () => {
   it('uses CreateFleet when useDedicatedHost is undefined', async () => {
     mockEC2Client.on(CreateFleetCommand).resolves({ Instances: [{ InstanceIds: ['i-fleet-1'] }] });
 
-    const result = await createRunner(createRunnerConfig({
-      ...dedicatedHostRunnerConfig,
-      useDedicatedHost: undefined,
-    }));
+    const result = await createRunner(
+      createRunnerConfig({
+        ...dedicatedHostRunnerConfig,
+        useDedicatedHost: undefined,
+      }),
+    );
 
     expect(result).toEqual(['i-fleet-1']);
     expect(mockEC2Client).toHaveReceivedCommand(CreateFleetCommand);
@@ -1211,10 +1215,12 @@ describe('create runner with useDedicatedHost', () => {
 
   it('throws error when spot is used with dedicated host', async () => {
     await expect(
-      createRunner(createRunnerConfig({
-        ...dedicatedHostRunnerConfig,
-        capacityType: 'spot',
-      })),
+      createRunner(
+        createRunnerConfig({
+          ...dedicatedHostRunnerConfig,
+          capacityType: 'spot',
+        }),
+      ),
     ).rejects.toThrow('Spot instances are not supported with RunInstances');
     expect(mockEC2Client).not.toHaveReceivedCommand(RunInstancesCommand);
   });
@@ -1222,17 +1228,15 @@ describe('create runner with useDedicatedHost', () => {
   it('throws error when RunInstances returns no instances', async () => {
     mockEC2Client.on(RunInstancesCommand).resolves({ Instances: [] });
 
-    await expect(
-      createRunner(createRunnerConfig(dedicatedHostRunnerConfig)),
-    ).rejects.toThrow('RunInstances returned no instances for dedicated host.');
+    await expect(createRunner(createRunnerConfig(dedicatedHostRunnerConfig))).rejects.toThrow(
+      'RunInstances returned no instances for dedicated host.',
+    );
   });
 
   it('throws error when RunInstances fails', async () => {
     mockEC2Client.on(RunInstancesCommand).rejects(new Error('EC2 error'));
 
-    await expect(
-      createRunner(createRunnerConfig(dedicatedHostRunnerConfig)),
-    ).rejects.toThrow('EC2 error');
+    await expect(createRunner(createRunnerConfig(dedicatedHostRunnerConfig))).rejects.toThrow('EC2 error');
   });
 
   it('uses ami id override from ssm parameter', async () => {
@@ -1243,10 +1247,12 @@ describe('create runner with useDedicatedHost', () => {
     };
     mockSSMClient.on(GetParameterCommand).resolves(paramValue);
 
-    await createRunner(createRunnerConfig({
-      ...dedicatedHostRunnerConfig,
-      amiIdSsmParameterName: 'my-ami-id-param',
-    }));
+    await createRunner(
+      createRunnerConfig({
+        ...dedicatedHostRunnerConfig,
+        amiIdSsmParameterName: 'my-ami-id-param',
+      }),
+    );
 
     expect(mockEC2Client).toHaveReceivedCommandWith(RunInstancesCommand, {
       LaunchTemplate: {
diff --git a/lambdas/functions/control-plane/src/aws/runners.ts b/lambdas/functions/control-plane/src/aws/runners.ts
index 4e105dd021..0240d86a77 100644
--- a/lambdas/functions/control-plane/src/aws/runners.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.ts
@@ -335,7 +335,9 @@ async function createInstancesWithRunInstances(
 
   try {
     if (runnerParameters.ec2instanceCriteria.targetCapacityType === 'spot') {
-      throw new Error('Spot instances are not supported with RunInstances. Please set targetCapacityType to on-demand for dedicated hosts.');
+      throw new Error(
+        'Spot instances are not supported with RunInstances. Please set targetCapacityType to on-demand for dedicated hosts.',
+      );
     }
 
     const instanceType = runnerParameters.ec2instanceCriteria.instanceTypes[0] as _InstanceType;
@@ -376,7 +378,6 @@ async function createInstancesWithRunInstances(
   }
 }
 
-
 // If launchTime is undefined, this will return false
 export function bootTimeExceeded(ec2Runner: { launchTime?: Date }): boolean {
   const runnerBootTimeInMinutes = process.env.RUNNER_BOOT_TIME_IN_MINUTES;
diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
index d7d49e0fab..83e432add3 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
@@ -3099,25 +3099,19 @@ describe('useDedicatedHost', () => {
   it('defaults to false when USE_DEDICATED_HOST env var is not set', async () => {
     delete process.env.USE_DEDICATED_HOST;
     await scaleUpModule.scaleUp(TEST_DATA);
-    expect(createRunner).toHaveBeenCalledWith(
-      expect.objectContaining({ useDedicatedHost: false }),
-    );
+    expect(createRunner).toHaveBeenCalledWith(expect.objectContaining({ useDedicatedHost: false }));
   });
 
   it('is true when USE_DEDICATED_HOST is "true"', async () => {
     process.env.USE_DEDICATED_HOST = 'true';
     await scaleUpModule.scaleUp(TEST_DATA);
-    expect(createRunner).toHaveBeenCalledWith(
-      expect.objectContaining({ useDedicatedHost: true }),
-    );
+    expect(createRunner).toHaveBeenCalledWith(expect.objectContaining({ useDedicatedHost: true }));
   });
 
   it('is false when USE_DEDICATED_HOST is "false"', async () => {
     process.env.USE_DEDICATED_HOST = 'false';
     await scaleUpModule.scaleUp(TEST_DATA);
-    expect(createRunner).toHaveBeenCalledWith(
-      expect.objectContaining({ useDedicatedHost: false }),
-    );
+    expect(createRunner).toHaveBeenCalledWith(expect.objectContaining({ useDedicatedHost: false }));
   });
 });
 

From 0e23b49138af51be0cee2b897f313a3bcecf5e9b Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Tue, 10 Mar 2026 12:08:20 +0100
Subject: [PATCH 31/46] docs: add documentation and mark asexperimental

---
 docs/configuration.md                |   4 +
 docs/examples/dedicated-mac-hosts.md |   1 +
 docs/examples/index.md               |   1 +
 docs/mac-runners.md                  | 188 +++++++++++++++++++++++++++
 4 files changed, 194 insertions(+)
 create mode 100644 docs/examples/dedicated-mac-hosts.md
 create mode 100644 docs/mac-runners.md

diff --git a/docs/configuration.md b/docs/configuration.md
index 1776e30c76..6c8f33aaf9 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -282,6 +282,10 @@ In case the setup does not work as intended, trace the events through this seque
 
 ## Experimental features
 
+### macOS Runners
+
+This feature is in early stage and should be considered experimental. The module supports macOS-based GitHub Actions self-hosted runners on AWS EC2 Mac instances (`mac1.metal`, `mac2.metal`, `mac2-m2.metal`). macOS runners require dedicated hosts due to Apple's licensing requirements and have longer boot times (6–20 minutes). Set `runner_os = "osx"` and `use_dedicated_host = true` to enable. See the full [macOS Runners documentation](mac-runners.md) for details.
+
 ### Termination watcher
 
 This feature is in early stage and therefore disabled by default. To enable the watcher, set `instance_termination_watcher.enable = true`.
diff --git a/docs/examples/dedicated-mac-hosts.md b/docs/examples/dedicated-mac-hosts.md
new file mode 100644
index 0000000000..fd2caa4291
--- /dev/null
+++ b/docs/examples/dedicated-mac-hosts.md
@@ -0,0 +1 @@
+--8<-- "examples/dedicated-mac-hosts/README.md"
diff --git a/docs/examples/index.md b/docs/examples/index.md
index ac611575fc..f095e68ad9 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -9,4 +9,5 @@ Examples are located in the [examples](https://github.com/github-aws-runners/ter
 - _[Prebuilt Images](prebuilt.md)_: Example usages of deploying runners with a custom prebuilt image.
 - _[Windows](windows.md)_: Example usage of creating a runner using Windows as the OS.
 - _[Termination watcher](termination-watcher.md)_: Example usages of termination watcher.
+- _[Dedicated Mac Hosts](dedicated-mac-hosts.md)_: Example usage of setting up dedicated hosts for macOS runners.
 - _[Externally managed SSM secrets](external-managed-ssm-secrets.md)_: Example usage of externally managed SSM secrets for the GitHub App credentials.
diff --git a/docs/mac-runners.md b/docs/mac-runners.md
new file mode 100644
index 0000000000..fb9fd27021
--- /dev/null
+++ b/docs/mac-runners.md
@@ -0,0 +1,188 @@
+# macOS Runners (Experimental)
+
+!!! warning
+    This feature is in early stage and should be considered experimental. macOS runners on AWS have unique constraints compared to Linux and Windows runners. Please review all sections below before deploying.
+
+## Overview
+
+The module supports provisioning macOS-based GitHub Actions self-hosted runners on AWS using [Amazon EC2 Mac instances](https://aws.amazon.com/ec2/instance-types/mac/). macOS runners use the `osx` value for the `runner_os` variable and require **dedicated hosts** due to Apple's macOS licensing requirements.
+
+Key differences from Linux/Windows runners:
+
+- **Dedicated hosts required.** EC2 Mac instances must run on dedicated hosts. Each dedicated host can run **only one Mac VM at a time** (1:1 ratio). The module uses `RunInstances` directly instead of the `CreateFleet` API when `use_dedicated_host` is enabled.
+- **Longer boot times.** macOS instances can take 6–20 minutes to launch, significantly longer than Linux (~1 min) or Windows (~5 min). The default `minimum_running_time_in_minutes` for `osx` is set to 20 minutes to prevent premature scale-down.
+- **~50 minute host recycle time.** After an EC2 Mac instance is terminated, AWS performs install cleanup and software upgrades on the dedicated host before it becomes available again. This process takes approximately **50 minutes**, during which the host cannot launch a new instance.
+- **ARM64 (Apple Silicon) and x64 (Intel) support.** Both `mac1.metal` (Intel), `mac2.metal` (M1), and `mac2-m2.metal` (M2) instance types are supported. Set `runner_architecture` accordingly (`x64` or `arm64`).
+- **Only ephemeral mode is recommended.** Due to the long host allocation time and dedicated host cost model, we recommend using ephemeral runners.
+
+## Scaling caveats
+
+Running macOS runners at scale introduces challenges that do not exist with Linux or Windows runners:
+
+1. **1:1 host-to-VM ratio.** Unlike Linux where many instances share underlying hardware, each Mac VM requires its own dedicated host. To run N concurrent macOS jobs, you need at least N dedicated hosts.
+2. **Host recycle delay.** After a Mac instance is terminated, the dedicated host enters a ~50 minute cleanup cycle (scrubbing, software updates). During this window the host is unavailable. For bursty workloads, you need additional hosts to absorb demand while others recycle.
+3. **Capacity planning.** As a rule of thumb, if you expect N peak concurrent macOS jobs and each job takes T minutes, account for the extra ~50 minutes of host downtime per cycle when sizing your host pool.
+
+## Prerequisites
+
+Before deploying macOS runners, you must set up dedicated host infrastructure. There are two approaches:
+
+### Option A: Single dedicated host
+
+The simplest setup — allocate a single dedicated host and reference it directly. This works for low-scale or testing scenarios, but you must update the Terraform configuration whenever you replace the host.
+
+1. **Dedicated Host** — Allocate an EC2 dedicated host for your Mac instance type in the target availability zone.
+
+### Option B: Host resource group (recommended for scale)
+
+A host resource group allows you to associate **multiple dedicated hosts within an availability zone** into a logical group. When launching a Mac instance, AWS randomly selects an available host from the group. This means you can add, release, or replace individual dedicated hosts **without changing Terraform state or module inputs** — you only reference the group ARN, not individual host ARNs.
+
+This approach requires three resources:
+
+1. **Dedicated Hosts** — Allocate one or more EC2 dedicated hosts for Mac instance types in your target availability zones.
+2. **Host Resource Group** — Create an AWS Resource Groups group of type `AWS::EC2::HostManagement` and add your dedicated hosts as members.
+3. **License Configuration** — Create an AWS License Manager license configuration for Mac dedicated hosts (counting type: `Socket`). Associate it with the macOS AMI and the host resource group. The license configuration ARN is passed to the module via the `license_specifications` input.
+
+The [dedicated-mac-hosts example](examples/dedicated-mac-hosts.md) provides a ready-to-use Terraform configuration for all three resources.
+
+## Configuration
+
+### Basic setup
+
+```hcl
+module "runners" {
+  source = "github-aws-runners/github-runners/aws"
+
+  # macOS-specific settings
+  runner_os           = "osx"
+  runner_architecture = "arm64"  # or "x64" for Intel Mac instances
+  instance_types      = ["mac2.metal"]
+
+  # Dedicated host settings (required for macOS)
+  use_dedicated_host = true
+  placement = {
+    host_resource_group_arn = "<arn-of-your-host-resource-group>"
+  }
+  license_specifications = ["<arn-of-your-license-configuration>"]
+
+  # Recommended: ephemeral mode with a pool
+  enable_ephemeral_runners = true
+  delay_webhook_event      = 0
+  enable_job_queued_check  = true
+
+  # ...other common settings...
+}
+```
+
+### AMI selection
+
+By default, the module selects an Amazon EC2 macOS Sequoia (macOS 15) AMI:
+
+- **ARM64:** `amzn-ec2-macos-15.*-arm64`
+- **x64:** `amzn-ec2-macos-15.*`
+
+You can override the AMI using filters or an SSM parameter:
+
+```hcl
+# Custom AMI filter
+ami = {
+  filter = {
+    name  = ["amzn-ec2-macos-14.*-arm64"]
+    state = ["available"]
+  }
+  owners = ["amazon"]
+}
+
+# Or via SSM parameter
+ami = {
+  id_ssm_parameter_arn = "arn:aws:ssm:region:account:parameter/path/to/mac/ami"
+}
+```
+
+### Multi-runner setup
+
+When using the multi-runner module, you can add a macOS runner configuration alongside Linux and Windows runners:
+
+```hcl
+multi_runner_config = {
+  "mac-arm64" = {
+    runner_config = {
+      runner_os           = "osx"
+      runner_architecture = "arm64"
+      instance_types      = ["mac2.metal"]
+      use_dedicated_host  = true
+      placement = {
+        host_resource_group_arn = "<arn-of-your-host-resource-group>"
+      }
+      license_specifications = ["<arn-of-your-license-configuration>"]
+      runner_extra_labels    = ["osx", "arm64"]
+    }
+    matcherConfig = {
+      labelMatchers = [["self-hosted", "osx", "arm64"]]
+      exactMatch    = false
+    }
+  }
+}
+```
+
+## Instance launch behavior
+
+Because EC2 Fleet (`CreateFleet`) does not support launching instances onto dedicated hosts for `mac*.metal` instance types, the scale-up lambda automatically falls back to using `RunInstances` when `use_dedicated_host` is `true`. This is handled transparently — no additional configuration is needed.
+
+## User data and scripts
+
+The module uses macOS-specific templates for provisioning:
+
+| Script | Description |
+| --- | --- |
+| `user-data-osx.sh` | Boot script for macOS instances. Uses `ec2-user` and supports Homebrew. |
+| `install-runner-osx.sh` | Downloads and installs the GitHub Actions runner agent to `/opt/actions-runner`. |
+| `start-runner-osx.sh` | Registers the runner with GitHub and handles ephemeral cleanup. |
+
+Custom pre/post install scripts and job hooks (`hook_job_started`, `hook_job_completed`) work the same as on Linux.
+
+## Scale-down considerations
+
+macOS instances have a default minimum running time of **20 minutes** (vs. 5 for Linux, 15 for Windows) to account for the longer boot cycle. Adjust `minimum_running_time_in_minutes` if needed, but setting it too low risks terminating instances before they can execute a job.
+
+Additionally, remember that after an instance is terminated, the dedicated host enters a **~50 minute cleanup cycle** before it can launch a new instance. Aggressive scale-down can leave you with no available hosts during this window.
+
+```hcl
+# Override the minimum running time (not recommended to go below 20 for macOS)
+minimum_running_time_in_minutes = 25
+```
+
+## Cost considerations
+
+!!! note
+    macOS dedicated hosts have a **minimum allocation period of 24 hours**. You are billed for the dedicated host for the full 24-hour period, regardless of instance usage. Plan your host allocation accordingly.
+
+- **Dedicated host costs**: Billed per-host, per-hour with a 24-hour minimum. Each host supports only one Mac VM at a time. See [EC2 Dedicated Hosts Pricing](https://aws.amazon.com/ec2/dedicated-hosts/pricing/).
+- **Instance costs**: Mac instances are billed on-demand only (no spot pricing available for Mac instances).
+- **Over-provisioning for recycle time**: Because hosts are unavailable for ~50 minutes after instance termination, you may need more dedicated hosts than your peak concurrency to avoid queuing. Factor this into your cost model.
+- **Pool sizing**: Keep pool sizes minimal to control costs, but large enough to avoid cold-start delays.
+
+## Known limitations
+
+- **No spot instance support.** EC2 Mac instances do not support the spot lifecycle. Runners always use on-demand pricing.
+- **1:1 host-to-VM ratio.** Each dedicated host can run only one Mac instance at a time.
+- **~50 minute host recycle time.** After instance termination, AWS performs cleanup and software upgrades on the dedicated host. The host is unavailable for approximately 50 minutes during this process.
+- **24-hour minimum host allocation.** Dedicated hosts cannot be released within 24 hours of allocation.
+- **Limited instance types.** Only `mac1.metal` (Intel x86), `mac2.metal` (M1 ARM64), and `mac2-m2.metal` (M2 ARM64) are available. Instance type availability varies by region.
+- **Longer startup.** Boot times of 6–20 minutes mean jobs will queue longer when no warm runners are available.
+- **No SSM Session Manager.** Unlike Linux instances, connecting via AWS Session Manager may not be available depending on your AMI.
+- **GHES not tested.** macOS runner support has not been validated against GitHub Enterprise Server.
+
+## Debugging
+
+- Check `/var/log/user-data.log` on the macOS instance for boot script output.
+- CloudWatch log streams under `<environment>/runners` will contain runner agent logs if CloudWatch logging is enabled.
+- Verify your dedicated host has available capacity in the EC2 console under **Dedicated Hosts**.
+- Ensure the host resource group ARN and license configuration ARN match what is configured in Terraform.
+- If runners fail to register, verify the GitHub App has the correct permissions and the SSM token path is accessible.
+
+## Example
+
+A complete example for setting up the dedicated host infrastructure is available at:
+
+- [Dedicated Mac Hosts example](examples/dedicated-mac-hosts.md)

From 9be8538328873fb7ea99a90ac8a4d75a519dae62 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Tue, 10 Mar 2026 13:27:35 +0100
Subject: [PATCH 32/46] docs: update docs with confirmation that works in GHES
 3.17.3

---
 docs/mac-runners.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/mac-runners.md b/docs/mac-runners.md
index fb9fd27021..509d045751 100644
--- a/docs/mac-runners.md
+++ b/docs/mac-runners.md
@@ -171,7 +171,7 @@ minimum_running_time_in_minutes = 25
 - **Limited instance types.** Only `mac1.metal` (Intel x86), `mac2.metal` (M1 ARM64), and `mac2-m2.metal` (M2 ARM64) are available. Instance type availability varies by region.
 - **Longer startup.** Boot times of 6–20 minutes mean jobs will queue longer when no warm runners are available.
 - **No SSM Session Manager.** Unlike Linux instances, connecting via AWS Session Manager may not be available depending on your AMI.
-- **GHES not tested.** macOS runner support has not been validated against GitHub Enterprise Server.
+- **GHES limited testing.** macOS runner support has only been validated against GitHub Enterprise Server 3.17.3.
 
 ## Debugging
 

From ad46e72282cfb30b9da9da32a4073e6a39bd8f68 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Tue, 10 Mar 2026 19:38:48 +0100
Subject: [PATCH 33/46] docs: update variable description

---
 modules/multi-runner/variables.tf | 1 +
 modules/runners/variables.tf      | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index 75fad7f65d..ad4fcece1f 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -253,6 +253,7 @@ variable "multi_runner_config" {
         vpc_id: "The VPC for security groups of the action runners. If not set uses the value of `var.vpc_id`."
         subnet_ids: "List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. If not set, uses the value of `var.subnet_ids`."
         idle_config: "List of time period that can be defined as cron expression to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."
+        use_dedicated_host: "Experimental! Can be removed / changed without trigger a major release. Whether to use EC2 dedicated hosts for the runners. Needed for macos runners Note that using dedicated hosts can increase cost significantly."
         runner_log_files: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."
         block_device_mappings: "The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`."
         job_retry: "Experimental! Can be removed / changed without trigger a major release. Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app."
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index f7973f3113..925e426145 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -838,7 +838,7 @@ variable "parameter_store_tags" {
 }
 
 variable "use_dedicated_host" {
-  description = "Use a dedicated host for the runner instances."
+  description = "Experimental! Can be removed / changed without trigger a major release. Whether to use EC2 dedicated hosts for the runners. Needed for macos runners Note that using dedicated hosts can increase cost significantly."
   type        = bool
   default     = false
 }

From dd2341bea4dab7011a4d62556e2302103e0f065a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 10 Mar 2026 18:39:59 +0000
Subject: [PATCH 34/46] docs: auto update terraform docs

---
 modules/runners/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/runners/README.md b/modules/runners/README.md
index 38c81a155b..bf0a4e74a0 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -232,7 +232,7 @@ yarn run dist
 | <a name="input_subnet_ids"></a> [subnet\_ids](#input\_subnet\_ids) | List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. | `list(string)` | n/a | yes |
 | <a name="input_tags"></a> [tags](#input\_tags) | Map of tags that will be added to created resources. By default resources will be tagged with name. | `map(string)` | `{}` | no |
 | <a name="input_tracing_config"></a> [tracing\_config](#input\_tracing\_config) | Configuration for lambda tracing. | <pre>object({<br/>    mode                  = optional(string, null)<br/>    capture_http_requests = optional(bool, false)<br/>    capture_error         = optional(bool, false)<br/>  })</pre> | `{}` | no |
-| <a name="input_use_dedicated_host"></a> [use\_dedicated\_host](#input\_use\_dedicated\_host) | Use a dedicated host for the runner instances. | `bool` | `false` | no |
+| <a name="input_use_dedicated_host"></a> [use\_dedicated\_host](#input\_use\_dedicated\_host) | Experimental! Can be removed / changed without trigger a major release. Whether to use EC2 dedicated hosts for the runners. Needed for macos runners Note that using dedicated hosts can increase cost significantly. | `bool` | `false` | no |
 | <a name="input_user_agent"></a> [user\_agent](#input\_user\_agent) | User agent used for API calls. | `string` | `null` | no |
 | <a name="input_userdata_content"></a> [userdata\_content](#input\_userdata\_content) | Alternative user-data content, replacing the templated one. By providing your own user\_data you have to take care of installing all required software, including the action runner and registering the runner.  Be-aware configuration parameters in SSM as well as tags are treated as internals. Changes will not trigger a breaking release. | `string` | `null` | no |
 | <a name="input_userdata_post_install"></a> [userdata\_post\_install](#input\_userdata\_post\_install) | User-data script snippet to insert after GitHub action runner install | `string` | `""` | no |

From 8492f56692c9261acd762acbdcb1c6b04916353d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 11 Mar 2026 19:32:12 +0000
Subject: [PATCH 35/46] docs: auto update terraform docs

---
 README.md                      | 1 +
 modules/runners/README.md      | 1 +
 modules/runners/pool/README.md | 2 +-
 3 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 64671fb1db..7f86b601c7 100644
--- a/README.md
+++ b/README.md
@@ -199,6 +199,7 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_runner_hook_job_completed"></a> [runner\_hook\_job\_completed](#input\_runner\_hook\_job\_completed) | Script to be ran in the runner environment at the end of every job | `string` | `""` | no |
 | <a name="input_runner_hook_job_started"></a> [runner\_hook\_job\_started](#input\_runner\_hook\_job\_started) | Script to be ran in the runner environment at the beginning of every job | `string` | `""` | no |
 | <a name="input_runner_iam_role_managed_policy_arns"></a> [runner\_iam\_role\_managed\_policy\_arns](#input\_runner\_iam\_role\_managed\_policy\_arns) | Attach AWS or customer-managed IAM policies (by ARN) to the runner IAM role | `list(string)` | `[]` | no |
+| <a name="input_runner_license_specifications"></a> [runner\_license\_specifications](#input\_runner\_license\_specifications) | The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details. | <pre>list(object({<br/>    license_configuration_arn = string<br/>  }))</pre> | `[]` | no |
 | <a name="input_runner_log_files"></a> [runner\_log\_files](#input\_runner\_log\_files) | (optional) List of logfiles to send to CloudWatch, will only be used if `enable_cloudwatch_agent` is set to true. Object description: `log_group_name`: Name of the log group, `prefix_log_group`: If true, the log group name will be prefixed with `/github-self-hosted-runners/<var.prefix>`, `file_path`: path to the log file, `log_stream_name`: name of the log stream, `log_class`: The log class of the log group. Valid values are `STANDARD` or `INFREQUENT_ACCESS`. Defaults to `STANDARD`. | <pre>list(object({<br/>    log_group_name   = string<br/>    prefix_log_group = bool<br/>    file_path        = string<br/>    log_stream_name  = string<br/>    log_class        = optional(string, "STANDARD")<br/>  }))</pre> | `null` | no |
 | <a name="input_runner_metadata_options"></a> [runner\_metadata\_options](#input\_runner\_metadata\_options) | Metadata options for the ec2 runner instances. By default, the module uses metadata tags for bootstrapping the runner, only disable `instance_metadata_tags` when using custom scripts for starting the runner. | `map(any)` | <pre>{<br/>  "http_endpoint": "enabled",<br/>  "http_put_response_hop_limit": 1,<br/>  "http_tokens": "required",<br/>  "instance_metadata_tags": "enabled"<br/>}</pre> | no |
 | <a name="input_runner_name_prefix"></a> [runner\_name\_prefix](#input\_runner\_name\_prefix) | The prefix used for the GitHub runner name. The prefix will be used in the default start script to prefix the instance name when register the runner in GitHub. The value is available via an EC2 tag 'ghr:runner\_name\_prefix'. | `string` | `""` | no |
diff --git a/modules/runners/README.md b/modules/runners/README.md
index bf0a4e74a0..27a017a1cf 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -186,6 +186,7 @@ yarn run dist
 | <a name="input_lambda_timeout_scale_down"></a> [lambda\_timeout\_scale\_down](#input\_lambda\_timeout\_scale\_down) | Time out for the scale down lambda in seconds. | `number` | `60` | no |
 | <a name="input_lambda_timeout_scale_up"></a> [lambda\_timeout\_scale\_up](#input\_lambda\_timeout\_scale\_up) | Time out for the scale up lambda in seconds. | `number` | `60` | no |
 | <a name="input_lambda_zip"></a> [lambda\_zip](#input\_lambda\_zip) | File location of the lambda zip file. | `string` | `null` | no |
+| <a name="input_license_specifications"></a> [license\_specifications](#input\_license\_specifications) | The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details. | <pre>list(object({<br/>    license_configuration_arn = string<br/>  }))</pre> | `[]` | no |
 | <a name="input_log_class"></a> [log\_class](#input\_log\_class) | The log class of the CloudWatch log groups for the lambda functions. Valid values are `STANDARD` or `INFREQUENT_ACCESS`. | `string` | `"STANDARD"` | no |
 | <a name="input_log_level"></a> [log\_level](#input\_log\_level) | Logging level for lambda logging. Valid values are  'silly', 'trace', 'debug', 'info', 'warn', 'error', 'fatal'. | `string` | `"info"` | no |
 | <a name="input_logging_kms_key_id"></a> [logging\_kms\_key\_id](#input\_logging\_kms\_key\_id) | Specifies the kms key id to encrypt the logs with | `string` | `null` | no |
diff --git a/modules/runners/pool/README.md b/modules/runners/pool/README.md
index a09538aced..560ad7f763 100644
--- a/modules/runners/pool/README.md
+++ b/modules/runners/pool/README.md
@@ -49,7 +49,7 @@ No modules.
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 | <a name="input_aws_partition"></a> [aws\_partition](#input\_aws\_partition) | (optional) partition for the arn if not 'aws' | `string` | `"aws"` | no |
-| <a name="input_config"></a> [config](#input\_config) | Lookup details in parent module. | <pre>object({<br/>    lambda = object({<br/>      log_level                      = string<br/>      logging_retention_in_days      = number<br/>      logging_kms_key_id             = string<br/>      log_class                      = string<br/>      reserved_concurrent_executions = number<br/>      s3_bucket                      = string<br/>      s3_key                         = string<br/>      s3_object_version              = string<br/>      security_group_ids             = list(string)<br/>      runtime                        = string<br/>      architecture                   = string<br/>      memory_size                    = number<br/>      timeout                        = number<br/>      zip                            = string<br/>      subnet_ids                     = list(string)<br/>      parameter_store_tags           = string<br/>    })<br/>    tags = map(string)<br/>    ghes = object({<br/>      url        = string<br/>      ssl_verify = string<br/>    })<br/>    github_app_parameters = object({<br/>      key_base64 = map(string)<br/>      id         = map(string)<br/>    })<br/>    subnet_ids = list(string)<br/>    runner = object({<br/>      disable_runner_autoupdate            = bool<br/>      ephemeral                            = bool<br/>      enable_jit_config                    = bool<br/>      enable_on_demand_failover_for_errors = list(string)<br/>      scale_errors                         = list(string)<br/>      boot_time_in_minutes                 = number<br/>      labels                               = list(string)<br/>      launch_template = object({<br/>        name = string<br/>      })<br/>      group_name  = string<br/>      name_prefix = string<br/>      pool_owner  = string<br/>      role = object({<br/>        arn = string<br/>      })<br/>    })<br/>    instance_types                = list(string)<br/>    instance_target_capacity_type = string<br/>    instance_allocation_strategy  = string<br/>    instance_max_spot_price       = string<br/>    prefix                        = string<br/>    pool = list(object({<br/>      schedule_expression          = string<br/>      schedule_expression_timezone = string<br/>      size                         = number<br/>    }))<br/>    role_permissions_boundary            = string<br/>    kms_key_arn                          = string<br/>    ami_kms_key_arn                      = string<br/>    ami_id_ssm_parameter_arn             = string<br/>    role_path                            = string<br/>    ssm_token_path                       = string<br/>    ssm_config_path                      = string<br/>    ami_id_ssm_parameter_name            = string<br/>    ami_id_ssm_parameter_read_policy_arn = string<br/>    arn_ssm_parameters_path_config       = string<br/>    lambda_tags                          = map(string)<br/>    user_agent                           = string<br/>  })</pre> | n/a | yes |
+| <a name="input_config"></a> [config](#input\_config) | Lookup details in parent module. | <pre>object({<br/>    lambda = object({<br/>      log_level                      = string<br/>      logging_retention_in_days      = number<br/>      logging_kms_key_id             = string<br/>      log_class                      = string<br/>      reserved_concurrent_executions = number<br/>      s3_bucket                      = string<br/>      s3_key                         = string<br/>      s3_object_version              = string<br/>      security_group_ids             = list(string)<br/>      runtime                        = string<br/>      architecture                   = string<br/>      memory_size                    = number<br/>      timeout                        = number<br/>      zip                            = string<br/>      subnet_ids                     = list(string)<br/>      parameter_store_tags           = string<br/>    })<br/>    tags = map(string)<br/>    ghes = object({<br/>      url        = string<br/>      ssl_verify = string<br/>    })<br/>    github_app_parameters = object({<br/>      key_base64 = map(string)<br/>      id         = map(string)<br/>    })<br/>    subnet_ids = list(string)<br/>    runner = object({<br/>      disable_runner_autoupdate            = bool<br/>      ephemeral                            = bool<br/>      enable_jit_config                    = bool<br/>      enable_on_demand_failover_for_errors = list(string)<br/>      scale_errors                         = list(string)<br/>      boot_time_in_minutes                 = number<br/>      labels                               = list(string)<br/>      launch_template = object({<br/>        name = string<br/>      })<br/>      group_name  = string<br/>      name_prefix = string<br/>      pool_owner  = string<br/>      role = object({<br/>        arn = string<br/>      })<br/>      use_dedicated_host = bool<br/>    })<br/>    instance_types                = list(string)<br/>    instance_target_capacity_type = string<br/>    instance_allocation_strategy  = string<br/>    instance_max_spot_price       = string<br/>    prefix                        = string<br/>    pool = list(object({<br/>      schedule_expression          = string<br/>      schedule_expression_timezone = string<br/>      size                         = number<br/>    }))<br/>    role_permissions_boundary            = string<br/>    kms_key_arn                          = string<br/>    ami_kms_key_arn                      = string<br/>    ami_id_ssm_parameter_arn             = string<br/>    role_path                            = string<br/>    ssm_token_path                       = string<br/>    ssm_config_path                      = string<br/>    ami_id_ssm_parameter_name            = string<br/>    ami_id_ssm_parameter_read_policy_arn = string<br/>    arn_ssm_parameters_path_config       = string<br/>    lambda_tags                          = map(string)<br/>    user_agent                           = string<br/>  })</pre> | n/a | yes |
 | <a name="input_tracing_config"></a> [tracing\_config](#input\_tracing\_config) | Configuration for lambda tracing. | <pre>object({<br/>    mode                  = optional(string, null)<br/>    capture_http_requests = optional(bool, false)<br/>    capture_error         = optional(bool, false)<br/>  })</pre> | `{}` | no |
 
 ## Outputs

From 78996d00044a7c46fa0f3d83c73aca5d93058b21 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Sat, 11 Apr 2026 11:55:57 +0200
Subject: [PATCH 36/46] docs: add guidance comments for mac-arm64 placement
 configuration

---
 .../multi-runner/templates/runner-configs/mac-arm64-26.yaml    | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml b/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml
index 2c4d700b31..acc44983ad 100644
--- a/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml
+++ b/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml
@@ -7,6 +7,9 @@ redrive_build_queue:
   enabled: false
   maxReceiveCount: null
 runner_config:
+  # Replace <host_resource_group_arn> and <license_configuration_arn> with the actual
+  # values for your target region. These can be obtained from the outputs of the
+  # examples/dedicated-mac-hosts example.
   placement:
     host_resource_group_arn: "<host_resource_group_arn>"
     tenancy: host

From a813befd30b5bdf3e150d7c1ec32241179dfd9fa Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 11:54:02 +0200
Subject: [PATCH 37/46] style: fix style issue

---
 lambdas/functions/control-plane/src/aws/runners.test.ts         | 2 +-
 .../functions/control-plane/src/scale-runners/scale-up.test.ts  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lambdas/functions/control-plane/src/aws/runners.test.ts b/lambdas/functions/control-plane/src/aws/runners.test.ts
index 2c332101d4..e9f6c13969 100644
--- a/lambdas/functions/control-plane/src/aws/runners.test.ts
+++ b/lambdas/functions/control-plane/src/aws/runners.test.ts
@@ -986,7 +986,7 @@ function createRunnerConfig(runnerConfig: RunnerConfig): RunnerInputParameters {
     tracingEnabled: runnerConfig.tracingEnabled,
     onDemandFailoverOnError: runnerConfig.onDemandFailoverOnError,
     scaleErrors: runnerConfig.scaleErrors,
-    source: runnerConfig.source,    
+    source: runnerConfig.source,
     useDedicatedHost: runnerConfig.useDedicatedHost,
   };
 }
diff --git a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
index 83e432add3..7277355f2c 100644
--- a/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
+++ b/lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts
@@ -113,7 +113,7 @@ const EXPECTED_RUNNER_PARAMS: RunnerInputParameters = {
   tracingEnabled: false,
   onDemandFailoverOnError: [],
   scaleErrors: ['UnfulfillableCapacity', 'MaxSpotInstanceCountExceeded', 'TargetCapacityLimitExceededException'],
-  source: 'scale-up-lambda',    
+  source: 'scale-up-lambda',
   useDedicatedHost: false,
 };
 let expectedRunnerParams: RunnerInputParameters;

From 5baf9a3b871acea8e1bfcffbe20ff23a69236cf0 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 12:12:48 +0200
Subject: [PATCH 38/46] docs: clarify macOS host capacity planning

---
 docs/mac-runners.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/mac-runners.md b/docs/mac-runners.md
index 509d045751..97635b736b 100644
--- a/docs/mac-runners.md
+++ b/docs/mac-runners.md
@@ -21,7 +21,7 @@ Running macOS runners at scale introduces challenges that do not exist with Linu
 
 1. **1:1 host-to-VM ratio.** Unlike Linux where many instances share underlying hardware, each Mac VM requires its own dedicated host. To run N concurrent macOS jobs, you need at least N dedicated hosts.
 2. **Host recycle delay.** After a Mac instance is terminated, the dedicated host enters a ~50 minute cleanup cycle (scrubbing, software updates). During this window the host is unavailable. For bursty workloads, you need additional hosts to absorb demand while others recycle.
-3. **Capacity planning.** As a rule of thumb, if you expect N peak concurrent macOS jobs and each job takes T minutes, account for the extra ~50 minutes of host downtime per cycle when sizing your host pool.
+3. **Capacity planning.** Dedicated hosts must be allocated ahead of time and are limited by your AWS account quota. Reserve enough hosts for your maximum expected concurrent macOS jobs. After a job finishes and the Mac instance is terminated, add the job runtime plus approximately 50 minutes before that host can run another Mac instance. For example, a 30 minute job keeps its host unavailable for about 80 minutes total.
 
 ## Prerequisites
 

From 9ab2ee26bc83af092ba35cc58d5c8d2a3891a2d0 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 12:17:17 +0200
Subject: [PATCH 39/46] docs: document macOS license specifications

---
 README.md                         | 2 +-
 modules/multi-runner/variables.tf | 1 +
 modules/runners/README.md         | 2 +-
 modules/runners/variables.tf      | 2 +-
 variables.tf                      | 2 +-
 5 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 7f86b601c7..1b3a406b25 100644
--- a/README.md
+++ b/README.md
@@ -199,7 +199,7 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_runner_hook_job_completed"></a> [runner\_hook\_job\_completed](#input\_runner\_hook\_job\_completed) | Script to be ran in the runner environment at the end of every job | `string` | `""` | no |
 | <a name="input_runner_hook_job_started"></a> [runner\_hook\_job\_started](#input\_runner\_hook\_job\_started) | Script to be ran in the runner environment at the beginning of every job | `string` | `""` | no |
 | <a name="input_runner_iam_role_managed_policy_arns"></a> [runner\_iam\_role\_managed\_policy\_arns](#input\_runner\_iam\_role\_managed\_policy\_arns) | Attach AWS or customer-managed IAM policies (by ARN) to the runner IAM role | `list(string)` | `[]` | no |
-| <a name="input_runner_license_specifications"></a> [runner\_license\_specifications](#input\_runner\_license\_specifications) | The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details. | <pre>list(object({<br/>    license_configuration_arn = string<br/>  }))</pre> | `[]` | no |
+| <a name="input_runner_license_specifications"></a> [runner\_license\_specifications](#input\_runner\_license\_specifications) | Optional EC2 License Manager license configuration ARNs for the runner launch template. Required for macOS dedicated-host runners when the host resource group uses a Mac dedicated host license configuration. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details. | <pre>list(object({<br/>    license_configuration_arn = string<br/>  }))</pre> | `[]` | no |
 | <a name="input_runner_log_files"></a> [runner\_log\_files](#input\_runner\_log\_files) | (optional) List of logfiles to send to CloudWatch, will only be used if `enable_cloudwatch_agent` is set to true. Object description: `log_group_name`: Name of the log group, `prefix_log_group`: If true, the log group name will be prefixed with `/github-self-hosted-runners/<var.prefix>`, `file_path`: path to the log file, `log_stream_name`: name of the log stream, `log_class`: The log class of the log group. Valid values are `STANDARD` or `INFREQUENT_ACCESS`. Defaults to `STANDARD`. | <pre>list(object({<br/>    log_group_name   = string<br/>    prefix_log_group = bool<br/>    file_path        = string<br/>    log_stream_name  = string<br/>    log_class        = optional(string, "STANDARD")<br/>  }))</pre> | `null` | no |
 | <a name="input_runner_metadata_options"></a> [runner\_metadata\_options](#input\_runner\_metadata\_options) | Metadata options for the ec2 runner instances. By default, the module uses metadata tags for bootstrapping the runner, only disable `instance_metadata_tags` when using custom scripts for starting the runner. | `map(any)` | <pre>{<br/>  "http_endpoint": "enabled",<br/>  "http_put_response_hop_limit": 1,<br/>  "http_tokens": "required",<br/>  "instance_metadata_tags": "enabled"<br/>}</pre> | no |
 | <a name="input_runner_name_prefix"></a> [runner\_name\_prefix](#input\_runner\_name\_prefix) | The prefix used for the GitHub runner name. The prefix will be used in the default start script to prefix the instance name when register the runner in GitHub. The value is available via an EC2 tag 'ghr:runner\_name\_prefix'. | `string` | `""` | no |
diff --git a/modules/multi-runner/variables.tf b/modules/multi-runner/variables.tf
index ad4fcece1f..9c1abb8dde 100644
--- a/modules/multi-runner/variables.tf
+++ b/modules/multi-runner/variables.tf
@@ -253,6 +253,7 @@ variable "multi_runner_config" {
         vpc_id: "The VPC for security groups of the action runners. If not set uses the value of `var.vpc_id`."
         subnet_ids: "List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. If not set, uses the value of `var.subnet_ids`."
         idle_config: "List of time period that can be defined as cron expression to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."
+        license_specifications: "Optional EC2 License Manager license configuration ARNs for the runner launch template. Required for macOS dedicated-host runners when the host resource group uses a Mac dedicated host license configuration."
         use_dedicated_host: "Experimental! Can be removed / changed without trigger a major release. Whether to use EC2 dedicated hosts for the runners. Needed for macos runners Note that using dedicated hosts can increase cost significantly."
         runner_log_files: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."
         block_device_mappings: "The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`."
diff --git a/modules/runners/README.md b/modules/runners/README.md
index 27a017a1cf..5e5ee3835f 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -186,7 +186,7 @@ yarn run dist
 | <a name="input_lambda_timeout_scale_down"></a> [lambda\_timeout\_scale\_down](#input\_lambda\_timeout\_scale\_down) | Time out for the scale down lambda in seconds. | `number` | `60` | no |
 | <a name="input_lambda_timeout_scale_up"></a> [lambda\_timeout\_scale\_up](#input\_lambda\_timeout\_scale\_up) | Time out for the scale up lambda in seconds. | `number` | `60` | no |
 | <a name="input_lambda_zip"></a> [lambda\_zip](#input\_lambda\_zip) | File location of the lambda zip file. | `string` | `null` | no |
-| <a name="input_license_specifications"></a> [license\_specifications](#input\_license\_specifications) | The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details. | <pre>list(object({<br/>    license_configuration_arn = string<br/>  }))</pre> | `[]` | no |
+| <a name="input_license_specifications"></a> [license\_specifications](#input\_license\_specifications) | Optional EC2 License Manager license configuration ARNs for the runner launch template. Required for macOS dedicated-host runners when the host resource group uses a Mac dedicated host license configuration. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details. | <pre>list(object({<br/>    license_configuration_arn = string<br/>  }))</pre> | `[]` | no |
 | <a name="input_log_class"></a> [log\_class](#input\_log\_class) | The log class of the CloudWatch log groups for the lambda functions. Valid values are `STANDARD` or `INFREQUENT_ACCESS`. | `string` | `"STANDARD"` | no |
 | <a name="input_log_level"></a> [log\_level](#input\_log\_level) | Logging level for lambda logging. Valid values are  'silly', 'trace', 'debug', 'info', 'warn', 'error', 'fatal'. | `string` | `"info"` | no |
 | <a name="input_logging_kms_key_id"></a> [logging\_kms\_key\_id](#input\_logging\_kms\_key\_id) | Specifies the kms key id to encrypt the logs with | `string` | `null` | no |
diff --git a/modules/runners/variables.tf b/modules/runners/variables.tf
index 925e426145..27601ce65b 100644
--- a/modules/runners/variables.tf
+++ b/modules/runners/variables.tf
@@ -688,7 +688,7 @@ variable "placement" {
 }
 
 variable "license_specifications" {
-  description = "The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details."
+  description = "Optional EC2 License Manager license configuration ARNs for the runner launch template. Required for macOS dedicated-host runners when the host resource group uses a Mac dedicated host license configuration. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details."
   type = list(object({
     license_configuration_arn = string
   }))
diff --git a/variables.tf b/variables.tf
index 37a3df78a0..f4fef35ced 100644
--- a/variables.tf
+++ b/variables.tf
@@ -919,7 +919,7 @@ variable "runner_placement" {
 }
 
 variable "runner_license_specifications" {
-  description = "The license specifications for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details."
+  description = "Optional EC2 License Manager license configuration ARNs for the runner launch template. Required for macOS dedicated-host runners when the host resource group uses a Mac dedicated host license configuration. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#license_specification for details."
   type = list(object({
     license_configuration_arn = string
   }))

From 7bb164b5f35b2441f907fb0b2ca7a089dd881515 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 12:28:49 +0200
Subject: [PATCH 40/46] docs: set macOS examples to on-demand capacity

---
 docs/mac-runners.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/mac-runners.md b/docs/mac-runners.md
index 97635b736b..a68dfdbadc 100644
--- a/docs/mac-runners.md
+++ b/docs/mac-runners.md
@@ -57,6 +57,7 @@ module "runners" {
   runner_os           = "osx"
   runner_architecture = "arm64"  # or "x64" for Intel Mac instances
   instance_types      = ["mac2.metal"]
+  instance_target_capacity_type = "on-demand"
 
   # Dedicated host settings (required for macOS)
   use_dedicated_host = true
@@ -110,6 +111,7 @@ multi_runner_config = {
       runner_os           = "osx"
       runner_architecture = "arm64"
       instance_types      = ["mac2.metal"]
+      instance_target_capacity_type = "on-demand"
       use_dedicated_host  = true
       placement = {
         host_resource_group_arn = "<arn-of-your-host-resource-group>"

From b783af947390eed05adfa76a78b8f0ea24696cda Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 12:29:39 +0200
Subject: [PATCH 41/46] docs: remove macOS multi-runner sample

---
 .../runner-configs/mac-arm64-26.yaml          | 43 -------------------
 1 file changed, 43 deletions(-)
 delete mode 100644 examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml

diff --git a/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml b/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml
deleted file mode 100644
index acc44983ad..0000000000
--- a/examples/multi-runner/templates/runner-configs/mac-arm64-26.yaml
+++ /dev/null
@@ -1,43 +0,0 @@
-matcherConfig:
-  exactMatch: true
-  labelMatchers:
-    - [self-hosted, osx, arm64]
-fifo: true
-redrive_build_queue:
-  enabled: false
-  maxReceiveCount: null
-runner_config:
-  # Replace <host_resource_group_arn> and <license_configuration_arn> with the actual
-  # values for your target region. These can be obtained from the outputs of the
-  # examples/dedicated-mac-hosts example.
-  placement:
-    host_resource_group_arn: "<host_resource_group_arn>"
-    tenancy: host
-  license_specifications:
-    - license_configuration_arn: "<license_configuration_arn>"
-  runner_os: osx
-  runner_architecture: arm64
-  runner_user: ec2-user
-  runner_name_prefix: macos_26_
-  enable_ssm_on_runners: true
-  credit_specification: unlimited
-  instance_types:
-    - mac2.metal
-  ami:
-    id_ssm_parameter_arn: ${ami_id_ssm_parameter_arn}
-  ami:
-    owners:
-      - amazon
-    filter:
-      name:
-        - amzn-ec2-macos-26*
-      state:
-        - available    
-  runners_maximum_count: 1
-  delay_webhook_event: 0
-  scale_down_schedule_expression: cron(* * * * ? *)
-  runner_hook_job_started: |
-    echo "Running pre job hook as $(whoami)"
-  runner_hook_job_completed: |
-    echo "Running post job hook as $(whoami)"
-

From 539836fcd7d0a6f2fb16cd837137ca67a555ae77 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 12:31:04 +0200
Subject: [PATCH 42/46] chore: clarify runner binary extensions

---
 modules/runner-binaries-syncer/main.tf | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/modules/runner-binaries-syncer/main.tf b/modules/runner-binaries-syncer/main.tf
index 2b1e212262..c7db3051e0 100644
--- a/modules/runner-binaries-syncer/main.tf
+++ b/modules/runner-binaries-syncer/main.tf
@@ -1,5 +1,11 @@
 locals {
-  action_runner_distribution_object_key = "actions-runner-${var.runner_os}.${var.runner_os == "windows" ? "zip" : "tar.gz"}"
+  action_runner_distribution_extensions = {
+    linux   = "tar.gz"
+    osx     = "tar.gz"
+    windows = "zip"
+  }
+
+  action_runner_distribution_object_key = "actions-runner-${var.runner_os}.${local.action_runner_distribution_extensions[var.runner_os]}"
 }
 
 resource "aws_s3_bucket" "action_dist" {

From 629748a7203d75697e2de9d7838ba10bd67dea4d Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 12:40:51 +0200
Subject: [PATCH 43/46] fix: harden macOS runner install script

---
 modules/runners/templates/install-runner-osx.sh | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/modules/runners/templates/install-runner-osx.sh b/modules/runners/templates/install-runner-osx.sh
index 73abce4500..4239dcee59 100644
--- a/modules/runners/templates/install-runner-osx.sh
+++ b/modules/runners/templates/install-runner-osx.sh
@@ -1,11 +1,15 @@
 # shellcheck shell=bash
 
+set -euo pipefail
+
 ## install the runner (macOS)
 
-s3_location=${S3_LOCATION_RUNNER_DISTRIBUTION}
-architecture=${RUNNER_ARCHITECTURE}
+s3_location=${S3_LOCATION_RUNNER_DISTRIBUTION:-}
+architecture=${RUNNER_ARCHITECTURE:-}
+runner_tarball_url=${RUNNER_TARBALL_URL:-}
+user_name=${user_name:-ec2-user}
 
-if [ -z "$RUNNER_TARBALL_URL" ] && [ -z "$s3_location" ]; then
+if [ -z "$runner_tarball_url" ] && [ -z "$s3_location" ]; then
   echo "Neither RUNNER_TARBALL_URL or s3_location are set"
   exit 1
 fi
@@ -19,9 +23,9 @@ echo "Creating actions-runner directory for the GH Action installation"
 sudo mkdir -p /opt/actions-runner
 cd /opt/actions-runner || exit 1
 
-if [[ -n "$RUNNER_TARBALL_URL" ]]; then
-  echo "Downloading the GH Action runner from $RUNNER_TARBALL_URL to $file_name"
-  curl -s -o "$file_name" -L "$RUNNER_TARBALL_URL"
+if [[ -n "$runner_tarball_url" ]]; then
+  echo "Downloading the GH Action runner from $runner_tarball_url to $file_name"
+  curl -s -o "$file_name" -L "$runner_tarball_url"
 else
   echo "Retrieving REGION from AWS API"
   token="$(curl -s -f -X PUT "http://169.254.169.254/latest/api/token" \

From 55e78a386d55259d51bdd0e99ec0f49806761d95 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 13:06:09 +0200
Subject: [PATCH 44/46] fix: let macOS runner config lookup retry

---
 modules/runners/templates/start-runner-osx.sh | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/modules/runners/templates/start-runner-osx.sh b/modules/runners/templates/start-runner-osx.sh
index c3ea08af20..a6da66116d 100644
--- a/modules/runners/templates/start-runner-osx.sh
+++ b/modules/runners/templates/start-runner-osx.sh
@@ -1,7 +1,5 @@
 #!/bin/bash
 
-set -euo pipefail
-
 # macOS variant of start-runner.sh
 
 tag_instance_with_runner_id() {
@@ -112,18 +110,11 @@ token_path=$(echo "$parameters" | jq -r '.[] | select(.Name == "'$ssm_config_pat
 echo "Retrieved /$ssm_config_path/token_path parameter - ($token_path)"
 
 echo "Get GH Runner config from AWS SSM"
-config=$(aws ssm get-parameter \
-  --name "$token_path"/"$instance_id" \
-  --with-decryption \
-  --region "$region" | jq -r ".Parameter | .Value")
-
+config=$(aws ssm get-parameter --name "$token_path"/"$instance_id" --with-decryption --region "$region" | jq -r ".Parameter | .Value")
 while [[ -z "$config" ]]; do
   echo "Waiting for GH Runner config to become available in AWS SSM"
   sleep 1
-  config=$(aws ssm get-parameter \
-    --name "$token_path"/"$instance_id" \
-    --with-decryption \
-    --region "$region" | jq -r ".Parameter | .Value")
+  config=$(aws ssm get-parameter --name "$token_path"/"$instance_id" --with-decryption --region "$region" | jq -r ".Parameter | .Value")
 done
 
 echo "Delete GH Runner token from AWS SSM"

From 6acbe4b3a622319ae2e5395c623ccded48c686c5 Mon Sep 17 00:00:00 2001
From: edersonbrilhante <contato@edersonbrilhante.com.br>
Date: Wed, 10 Jun 2026 13:25:21 +0200
Subject: [PATCH 45/46] fix: undo change in install-runner-osx.sh

---
 modules/runners/templates/install-runner-osx.sh | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/modules/runners/templates/install-runner-osx.sh b/modules/runners/templates/install-runner-osx.sh
index 4239dcee59..ed848dad27 100644
--- a/modules/runners/templates/install-runner-osx.sh
+++ b/modules/runners/templates/install-runner-osx.sh
@@ -4,12 +4,10 @@ set -euo pipefail
 
 ## install the runner (macOS)
 
-s3_location=${S3_LOCATION_RUNNER_DISTRIBUTION:-}
-architecture=${RUNNER_ARCHITECTURE:-}
-runner_tarball_url=${RUNNER_TARBALL_URL:-}
-user_name=${user_name:-ec2-user}
+s3_location=${S3_LOCATION_RUNNER_DISTRIBUTION}
+architecture=${RUNNER_ARCHITECTURE}
 
-if [ -z "$runner_tarball_url" ] && [ -z "$s3_location" ]; then
+if [ -z "$RUNNER_TARBALL_URL" ] && [ -z "$s3_location" ]; then
   echo "Neither RUNNER_TARBALL_URL or s3_location are set"
   exit 1
 fi

From ce5cc1c41d76c3c0ed10993ea7c2a0d9f0c4ac04 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 10 Jun 2026 12:36:33 +0000
Subject: [PATCH 46/46] docs: auto update terraform docs

---
 README.md                                       | 6 +++---
 examples/default/README.md                      | 4 ++--
 examples/ephemeral/README.md                    | 4 ++--
 examples/external-managed-ssm-secrets/README.md | 2 +-
 examples/multi-runner/README.md                 | 6 +++---
 examples/permissions-boundary/README.md         | 2 +-
 examples/prebuilt/README.md                     | 6 +++---
 modules/multi-runner/README.md                  | 7 +++----
 modules/runners/README.md                       | 6 +++---
 9 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 1b3a406b25..fa697d8dcd 100644
--- a/README.md
+++ b/README.md
@@ -68,14 +68,14 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 | <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 6.21 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 6.33 |
 | <a name="provider_random"></a> [random](#provider\_random) | ~> 3.0 |
 
 ## Modules
@@ -189,7 +189,7 @@ Join our discord community via [this invite link](https://discord.gg/bxgXW8jJGh)
 | <a name="input_runner_binaries_syncer_lambda_timeout"></a> [runner\_binaries\_syncer\_lambda\_timeout](#input\_runner\_binaries\_syncer\_lambda\_timeout) | Time out of the binaries sync lambda in seconds. | `number` | `300` | no |
 | <a name="input_runner_binaries_syncer_lambda_zip"></a> [runner\_binaries\_syncer\_lambda\_zip](#input\_runner\_binaries\_syncer\_lambda\_zip) | File location of the binaries sync lambda zip file. | `string` | `null` | no |
 | <a name="input_runner_boot_time_in_minutes"></a> [runner\_boot\_time\_in\_minutes](#input\_runner\_boot\_time\_in\_minutes) | The minimum time for an EC2 runner to boot and register as a runner. | `number` | `5` | no |
-| <a name="input_runner_cpu_options"></a> [runner\_cpu\_options](#input\_runner\_cpu\_options) | The CPU options for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#cpu-options for details. Note that not all instance types support CPU options, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#instance-cpu-options | <pre>object({<br/>    core_count       = number<br/>    threads_per_core = number<br/>  })</pre> | `null` | no |
+| <a name="input_runner_cpu_options"></a> [runner\_cpu\_options](#input\_runner\_cpu\_options) | The CPU options for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#cpu-options for details. Note that not all instance types support CPU options, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#instance-cpu-options | <pre>object({<br/>    core_count            = optional(number)<br/>    threads_per_core      = optional(number)<br/>    amd_sev_snp           = optional(string)<br/>    nested_virtualization = optional(string)<br/>  })</pre> | `null` | no |
 | <a name="input_runner_credit_specification"></a> [runner\_credit\_specification](#input\_runner\_credit\_specification) | The credit option for CPU usage of a T instance. Can be unset, "standard" or "unlimited". | `string` | `null` | no |
 | <a name="input_runner_disable_default_labels"></a> [runner\_disable\_default\_labels](#input\_runner\_disable\_default\_labels) | Disable default labels for the runners (os, architecture and `self-hosted`). If enabled, the runner will only have the extra labels provided in `runner_extra_labels`. In case you on own start script is used, this configuration parameter needs to be parsed via SSM. | `bool` | `false` | no |
 | <a name="input_runner_ec2_tags"></a> [runner\_ec2\_tags](#input\_runner\_ec2\_tags) | Map of tags that will be added to the launch template instance tag specifications. | `map(string)` | `{}` | no |
diff --git a/examples/default/README.md b/examples/default/README.md
index 2eae797fd7..c75e37831f 100644
--- a/examples/default/README.md
+++ b/examples/default/README.md
@@ -34,7 +34,7 @@ terraform output -raw webhook_secret
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 | <a name="requirement_local"></a> [local](#requirement\_local) | ~> 2.0 |
 | <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
 
@@ -42,7 +42,7 @@ terraform output -raw webhook_secret
 
 | Name | Version |
 |------|---------|
-| <a name="provider_random"></a> [random](#provider\_random) | 3.7.2 |
+| <a name="provider_random"></a> [random](#provider\_random) | 3.8.1 |
 
 ## Modules
 
diff --git a/examples/ephemeral/README.md b/examples/ephemeral/README.md
index 04f2177d7e..e6bf4961b4 100644
--- a/examples/ephemeral/README.md
+++ b/examples/ephemeral/README.md
@@ -33,7 +33,7 @@ terraform output webhook_secret
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 | <a name="requirement_local"></a> [local](#requirement\_local) | ~> 2.0 |
 | <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
 
@@ -41,7 +41,7 @@ terraform output webhook_secret
 
 | Name | Version |
 |------|---------|
-| <a name="provider_random"></a> [random](#provider\_random) | 3.7.2 |
+| <a name="provider_random"></a> [random](#provider\_random) | 3.8.1 |
 
 ## Modules
 
diff --git a/examples/external-managed-ssm-secrets/README.md b/examples/external-managed-ssm-secrets/README.md
index 5a9a725dd3..af9c95a38c 100644
--- a/examples/external-managed-ssm-secrets/README.md
+++ b/examples/external-managed-ssm-secrets/README.md
@@ -80,7 +80,7 @@ terraform output -raw webhook_secret
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 | <a name="requirement_local"></a> [local](#requirement\_local) | ~> 2.0 |
 | <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
 
diff --git a/examples/multi-runner/README.md b/examples/multi-runner/README.md
index 8f14b48503..f0a737b790 100644
--- a/examples/multi-runner/README.md
+++ b/examples/multi-runner/README.md
@@ -53,7 +53,7 @@ terraform output -raw webhook_secret
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 | <a name="requirement_local"></a> [local](#requirement\_local) | ~> 2.0 |
 | <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
 
@@ -61,8 +61,8 @@ terraform output -raw webhook_secret
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.22.1 |
-| <a name="provider_random"></a> [random](#provider\_random) | 3.7.2 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.35.1 |
+| <a name="provider_random"></a> [random](#provider\_random) | 3.8.1 |
 
 ## Modules
 
diff --git a/examples/permissions-boundary/README.md b/examples/permissions-boundary/README.md
index a5b1857d62..523e10edda 100644
--- a/examples/permissions-boundary/README.md
+++ b/examples/permissions-boundary/README.md
@@ -35,7 +35,7 @@ terraform apply
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 | <a name="requirement_local"></a> [local](#requirement\_local) | ~> 2.0 |
 | <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
 
diff --git a/examples/prebuilt/README.md b/examples/prebuilt/README.md
index c2d66139d4..f90a47261e 100644
--- a/examples/prebuilt/README.md
+++ b/examples/prebuilt/README.md
@@ -78,7 +78,7 @@ terraform output webhook_secret
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 | <a name="requirement_local"></a> [local](#requirement\_local) | ~> 2.0 |
 | <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
 
@@ -86,8 +86,8 @@ terraform output webhook_secret
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.22.1 |
-| <a name="provider_random"></a> [random](#provider\_random) | 3.7.2 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.35.1 |
+| <a name="provider_random"></a> [random](#provider\_random) | 3.8.1 |
 
 ## Modules
 
diff --git a/modules/multi-runner/README.md b/modules/multi-runner/README.md
index 15d584ca51..caa7993dee 100644
--- a/modules/multi-runner/README.md
+++ b/modules/multi-runner/README.md
@@ -79,14 +79,14 @@ module "multi-runner" {
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 | <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 6.21 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 6.33 |
 | <a name="provider_random"></a> [random](#provider\_random) | ~> 3.0 |
 
 ## Modules
@@ -152,8 +152,7 @@ module "multi-runner" {
 | <a name="input_logging_retention_in_days"></a> [logging\_retention\_in\_days](#input\_logging\_retention\_in\_days) | Specifies the number of days you want to retain log events for the lambda log group. Possible values are: 0, 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, and 3653. | `number` | `180` | no |
 | <a name="input_matcher_config_parameter_store_tier"></a> [matcher\_config\_parameter\_store\_tier](#input\_matcher\_config\_parameter\_store\_tier) | The tier of the parameter store for the matcher configuration. Valid values are `Standard`, and `Advanced`. | `string` | `"Standard"` | no |
 | <a name="input_metrics"></a> [metrics](#input\_metrics) | Configuration for metrics created by the module, by default metrics are disabled to avoid additional costs. When metrics are enable all metrics are created unless explicit configured otherwise. | <pre>object({<br/>    enable    = optional(bool, false)<br/>    namespace = optional(string, "GitHub Runners")<br/>    metric = optional(object({<br/>      enable_github_app_rate_limit    = optional(bool, true)<br/>      enable_job_retry                = optional(bool, true)<br/>      enable_spot_termination_warning = optional(bool, true)<br/>    }), {})<br/>  })</pre> | `{}` | no |
-| <a name="input_multi_runner_config"></a> [multi\_runner\_config](#input\_multi\_runner\_config) | multi\_runner\_config = {<br/>      runner\_config: {<br/>        runner\_os: "The EC2 Operating System type to use for action runner instances (linux,windows)."<br/>        runner\_architecture: "The platform architecture of the runner instance\_type."<br/>        runner\_metadata\_options: "(Optional) Metadata options for the ec2 runner instances."<br/>        ami: "(Optional) AMI configuration for the action runner instances. This object allows you to specify all AMI-related settings in one place."<br/>        create\_service\_linked\_role\_spot: (Optional) create the serviced linked role for spot instances that is required by the scale-up lambda.<br/>        credit\_specification: "(Optional) The credit specification of the runner instance\_type. Can be unset, `standard` or `unlimited`.<br/>        delay\_webhook\_event: "The number of seconds the event accepted by the webhook is invisible on the queue before the scale up lambda will receive the event."<br/>        disable\_runner\_autoupdate: "Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/)"<br/>        ebs\_optimized: "The EC2 EBS optimized configuration."<br/>        enable\_ephemeral\_runners: "Enable ephemeral runners, runners will only be used once."<br/>        enable\_job\_queued\_check: "Enables JIT configuration for creating runners instead of registration token based registraton. JIT configuration will only be applied for ephemeral runners. By default JIT configuration is enabled for ephemeral runners an can be disabled via this override. When running on GHES without support for JIT configuration this variable should be set to true for ephemeral runners."<br/>        enable\_on\_demand\_failover\_for\_errors: "Enable on-demand failover. For example to fall back to on demand when no spot capacity is available the variable can be set to `InsufficientInstanceCapacity`. When not defined the default behavior is to retry later."<br/>        scale\_errors: "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"<br/>        enable\_organization\_runners: "Register runners to organization, instead of repo level"<br/>        enable\_runner\_binaries\_syncer: "Option to disable the lambda to sync GitHub runner distribution, useful when using a pre-build AMI."<br/>        enable\_ssm\_on\_runners: "Enable to allow access the runner instances for debugging purposes via SSM. Note that this adds additional permissions to the runner instances."<br/>        enable\_userdata: "Should the userdata script be enabled for the runner. Set this to false if you are using your own prebuilt AMI."<br/>        instance\_allocation\_strategy: "The allocation strategy for spot instances. AWS recommends to use `capacity-optimized` however the AWS default is `lowest-price`."<br/>        instance\_max\_spot\_price: "Max price price for spot instances per hour. This variable will be passed to the create fleet as max spot price for the fleet."<br/>        instance\_target\_capacity\_type: "Default lifecycle used for runner instances, can be either `spot` or `on-demand`."<br/>        instance\_types: "List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux and Windows Server Core for win)."<br/>        job\_queue\_retention\_in\_seconds: "The number of seconds the job is held in the queue before it is purged"<br/>        minimum\_running\_time\_in\_minutes: "The time an ec2 action runner should be running at minimum before terminated if not busy."<br/>        pool\_runner\_owner: "The pool will deploy runners to the GitHub org ID, set this value to the org to which you want the runners deployed. Repo level is not supported."<br/>        runner\_additional\_security\_group\_ids: "List of additional security groups IDs to apply to the runner. If added outside the multi\_runner\_config block, the additional security group(s) will be applied to all runner configs. If added inside the multi\_runner\_config, the additional security group(s) will be applied to the individual runner."<br/>        runner\_as\_root: "Run the action runner under the root user. Variable `runner_run_as` will be ignored."<br/>        runner\_boot\_time\_in\_minutes: "The minimum time for an EC2 runner to boot and register as a runner."<br/>        runner\_disable\_default\_labels: "Disable default labels for the runners (os, architecture and `self-hosted`). If enabled, the runner will only have the extra labels provided in `runner_extra_labels`. In case you on own start script is used, this configuration parameter needs to be parsed via SSM."<br/>        runner\_extra\_labels: "Extra (custom) labels for the runners (GitHub). Separate each label by a comma. Labels checks on the webhook can be enforced by setting `multi_runner_config.matcherConfig.exactMatch`. GitHub read-only labels should not be provided."<br/>        runner\_group\_name: "Name of the runner group."<br/>        runner\_name\_prefix: "Prefix for the GitHub runner name."<br/>        runner\_run\_as: "Run the GitHub actions agent as user."<br/>        runners\_maximum\_count: "The maximum number of runners that will be created. Setting the variable to `-1` desiables the maximum check."<br/>        scale\_down\_schedule\_expression: "Scheduler expression to check every x for scale down."<br/>        scale\_up\_reserved\_concurrent\_executions: "Amount of reserved concurrent executions for the scale-up lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations."<br/>        userdata\_template: "Alternative user-data template, replacing the default template. By providing your own user\_data you have to take care of installing all required software, including the action runner. Variables userdata\_pre/post\_install are ignored."<br/>        enable\_jit\_config "Overwrite the default behavior for JIT configuration. By default JIT configuration is enabled for ephemeral runners and disabled for non-ephemeral runners. In case of GHES check first if the JIT config API is available. In case you are upgrading from 3.x to 4.x you can set `enable_jit_config` to `false` to avoid a breaking change when having your own AMI."<br/>        enable\_runner\_detailed\_monitoring: "Should detailed monitoring be enabled for the runner. Set this to true if you want to use detailed monitoring. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html for details."<br/>        enable\_cloudwatch\_agent: "Enabling the cloudwatch agent on the ec2 runner instances, the runner contains default config. Configuration can be overridden via `cloudwatch_config`."<br/>        cloudwatch\_config: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        userdata\_pre\_install: "Script to be ran before the GitHub Actions runner is installed on the EC2 instances"<br/>        userdata\_post\_install: "Script to be ran after the GitHub Actions runner is installed on the EC2 instances"<br/>        runner\_hook\_job\_started: "Script to be ran in the runner environment at the beginning of every job"<br/>        runner\_hook\_job\_completed: "Script to be ran in the runner environment at the end of every job"<br/>        runner\_ec2\_tags: "Map of tags that will be added to the launch template instance tag specifications."<br/>        runner\_iam\_role\_managed\_policy\_arns: "Attach AWS or customer-managed IAM policies (by ARN) to the runner IAM role"<br/>        vpc\_id: "The VPC for security groups of the action runners. If not set uses the value of `var.vpc_id`."<br/>        subnet\_ids: "List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. If not set, uses the value of `var.subnet_ids`."<br/>        idle\_config: "List of time period that can be defined as cron expression to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."<br/>        runner\_log\_files: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        block\_device\_mappings: "The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`."<br/>        job\_retry: "Experimental! Can be removed / changed without trigger a major release. Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app."<br/>        pool\_config: "The configuration for updating the pool. The `pool_size` to adjust to by the events triggered by the `schedule_expression`. For example you can configure a cron expression for week days to adjust the pool to 10 and another expression for the weekend to adjust the pool to 1. Use `schedule_expression_timezone` to override the schedule time zone (defaults to UTC)."<br/>      }<br/>      matcherConfig: {<br/>        labelMatchers: "The list of list of labels supported by the runner configuration. `[[self-hosted, linux, x64, example]]`"<br/>        exactMatch: "If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ workflow label matches it will trigger the webhook."<br/>        priority: "If set it defines the priority of the matcher, the matcher with the lowest priority will be evaluated first. Default is 999, allowed values 0-999."<br/>      }<br/>      redrive\_build\_queue: "Set options to attach (optional) a dead letter queue to the build queue, the queue between the webhook and the scale up lambda. You have the following options. 1. Disable by setting `enabled` to false. 2. Enable by setting `enabled` to `true`, `maxReceiveCount` to a number of max retries."<br/>    } | <pre>map(object({<br/>    runner_config = object({<br/>      runner_os           = string<br/>      runner_architecture = string<br/>      runner_metadata_options = optional(map(any), {<br/>        instance_metadata_tags      = "enabled"<br/>        http_endpoint               = "enabled"<br/>        http_tokens                 = "required"<br/>        http_put_response_hop_limit = 1<br/>      })<br/>      ami = optional(object({<br/>        filter               = optional(map(list(string)), { state = ["available"] })<br/>        owners               = optional(list(string), ["amazon"])<br/>        id_ssm_parameter_arn = optional(string, null)<br/>        kms_key_arn          = optional(string, null)<br/>      }), null)<br/>      create_service_linked_role_spot      = optional(bool, false)<br/>      credit_specification                 = optional(string, null)<br/>      delay_webhook_event                  = optional(number, 30)<br/>      disable_runner_autoupdate            = optional(bool, false)<br/>      ebs_optimized                        = optional(bool, false)<br/>      enable_ephemeral_runners             = optional(bool, false)<br/>      enable_job_queued_check              = optional(bool, null)<br/>      enable_on_demand_failover_for_errors = optional(list(string), [])<br/>      scale_errors = optional(list(string), [<br/>        "UnfulfillableCapacity",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "TargetCapacityLimitExceededException",<br/>        "RequestLimitExceeded",<br/>        "ResourceLimitExceeded",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "MaxSpotFleetRequestCountExceeded",<br/>        "InsufficientInstanceCapacity",<br/>        "InsufficientCapacityOnHost",<br/>      ])<br/>      enable_organization_runners             = optional(bool, false)<br/>      enable_runner_binaries_syncer           = optional(bool, true)<br/>      enable_ssm_on_runners                   = optional(bool, false)<br/>      enable_userdata                         = optional(bool, true)<br/>      instance_allocation_strategy            = optional(string, "lowest-price")<br/>      instance_max_spot_price                 = optional(string, null)<br/>      instance_target_capacity_type           = optional(string, "spot")<br/>      instance_types                          = list(string)<br/>      job_queue_retention_in_seconds          = optional(number, 86400)<br/>      minimum_running_time_in_minutes         = optional(number, null)<br/>      pool_runner_owner                       = optional(string, null)<br/>      runner_as_root                          = optional(bool, false)<br/>      runner_boot_time_in_minutes             = optional(number, 5)<br/>      runner_disable_default_labels           = optional(bool, false)<br/>      runner_extra_labels                     = optional(list(string), [])<br/>      runner_group_name                       = optional(string, "Default")<br/>      runner_name_prefix                      = optional(string, "")<br/>      runner_run_as                           = optional(string, "ec2-user")<br/>      runners_maximum_count                   = number<br/>      runner_additional_security_group_ids    = optional(list(string), [])<br/>      scale_down_schedule_expression          = optional(string, "cron(*/5 * * * ? *)")<br/>      scale_up_reserved_concurrent_executions = optional(number, 1)<br/>      userdata_template                       = optional(string, null)<br/>      userdata_content                        = optional(string, null)<br/>      enable_jit_config                       = optional(bool, null)<br/>      enable_runner_detailed_monitoring       = optional(bool, false)<br/>      enable_cloudwatch_agent                 = optional(bool, true)<br/>      cloudwatch_config                       = optional(string, null)<br/>      userdata_pre_install                    = optional(string, "")<br/>      userdata_post_install                   = optional(string, "")<br/>      runner_hook_job_started                 = optional(string, "")<br/>      runner_hook_job_completed               = optional(string, "")<br/>      runner_ec2_tags                         = optional(map(string), {})<br/>      runner_iam_role_managed_policy_arns     = optional(list(string), [])<br/>      vpc_id                                  = optional(string, null)<br/>      subnet_ids                              = optional(list(string), null)<br/>      idle_config = optional(list(object({<br/>        cron             = string<br/>        timeZone         = string<br/>        idleCount        = number<br/>        evictionStrategy = optional(string, "oldest_first")<br/>      })), [])<br/>      cpu_options = optional(object({<br/>        core_count       = number<br/>        threads_per_core = number<br/>      }), null)<br/>      placement = optional(object({<br/>        affinity                = optional(string)<br/>        availability_zone       = optional(string)<br/>        group_id                = optional(string)<br/>        group_name              = optional(string)<br/>        host_id                 = optional(string)<br/>        host_resource_group_arn = optional(string)<br/>        spread_domain           = optional(string)<br/>        tenancy                 = optional(string)<br/>        partition_number        = optional(number)<br/>      }), null)<br/>      runner_log_files = optional(list(object({<br/>        log_group_name   = string<br/>        prefix_log_group = bool<br/>        file_path        = string<br/>        log_stream_name  = string<br/>        log_class        = optional(string, "STANDARD")<br/>      })), null)<br/>      block_device_mappings = optional(list(object({<br/>        delete_on_termination = optional(bool, true)<br/>        device_name           = optional(string, "/dev/xvda")<br/>        encrypted             = optional(bool, true)<br/>        iops                  = optional(number)<br/>        kms_key_id            = optional(string)<br/>        snapshot_id           = optional(string)<br/>        throughput            = optional(number)<br/>        volume_size           = number<br/>        volume_type           = optional(string, "gp3")<br/>        })), [{<br/>        volume_size = 30<br/>      }])<br/>      pool_config = optional(list(object({<br/>        schedule_expression          = string<br/>        schedule_expression_timezone = optional(string)<br/>        size                         = number<br/>      })), [])<br/>      job_retry = optional(object({<br/>        enable             = optional(bool, false)<br/>        delay_in_seconds   = optional(number, 300)<br/>        delay_backoff      = optional(number, 2)<br/>        lambda_memory_size = optional(number, 256)<br/>        lambda_timeout     = optional(number, 30)<br/>        max_attempts       = optional(number, 1)<br/>      }), {})<br/>    })<br/>    matcherConfig = object({<br/>      labelMatchers = list(list(string))<br/>      exactMatch    = optional(bool, false)<br/>      priority      = optional(number, 999)<br/>    })<br/>    redrive_build_queue = optional(object({<br/>      enabled         = bool<br/>      maxReceiveCount = number<br/>      }), {<br/>      enabled         = false<br/>      maxReceiveCount = null<br/>    })<br/>  }))</pre> | n/a | yes |
-| <a name="input_multi_runner_config"></a> [multi\_runner\_config](#input\_multi\_runner\_config) | multi\_runner\_config = {<br/>      runner\_config: {<br/>        runner\_os: "The EC2 Operating System type to use for action runner instances (linux,windows)."<br/>        runner\_architecture: "The platform architecture of the runner instance\_type."<br/>        runner\_metadata\_options: "(Optional) Metadata options for the ec2 runner instances."<br/>        ami: "(Optional) AMI configuration for the action runner instances. This object allows you to specify all AMI-related settings in one place."<br/>        create\_service\_linked\_role\_spot: (Optional) create the serviced linked role for spot instances that is required by the scale-up lambda.<br/>        credit\_specification: "(Optional) The credit specification of the runner instance\_type. Can be unset, `standard` or `unlimited`.<br/>        delay\_webhook\_event: "The number of seconds the event accepted by the webhook is invisible on the queue before the scale up lambda will receive the event."<br/>        disable\_runner\_autoupdate: "Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/)"<br/>        ebs\_optimized: "The EC2 EBS optimized configuration."<br/>        enable\_ephemeral\_runners: "Enable ephemeral runners, runners will only be used once."<br/>        enable\_dynamic\_labels: "Experimental! Can be removed / changed without trigger a major release. Enable dynamic labels with 'ghr-' prefix. When enabled, jobs can use 'ghr-ec2-<config>:<value>' labels to dynamically configure EC2 instances (e.g., 'ghr-ec2-instance-type:t3.large') and 'ghr-run-<label>' to add unique labels dynamically to runners."<br/>        enable\_job\_queued\_check: Enables JIT configuration for creating runners instead of registration token based registraton. JIT configuration will only be applied for ephemeral runners. By default JIT configuration is enabled for ephemeral runners an can be disabled via this override. When running on GHES without support for JIT configuration this variable should be set to true for ephemeral runners."<br/>        enable\_on\_demand\_failover\_for\_errors: "Enable on-demand failover. For example to fall back to on demand when no spot capacity is available the variable can be set to `InsufficientInstanceCapacity`. When not defined the default behavior is to retry later."<br/>        scale\_errors: "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"<br/>        enable\_organization\_runners: "Register runners to organization, instead of repo level"<br/>        enable\_runner\_binaries\_syncer: "Option to disable the lambda to sync GitHub runner distribution, useful when using a pre-build AMI."<br/>        enable\_ssm\_on\_runners: "Enable to allow access the runner instances for debugging purposes via SSM. Note that this adds additional permissions to the runner instances."<br/>        enable\_userdata: "Should the userdata script be enabled for the runner. Set this to false if you are using your own prebuilt AMI."<br/>        instance\_allocation\_strategy: "The allocation strategy for spot instances. AWS recommends to use `capacity-optimized` however the AWS default is `lowest-price`."<br/>        instance\_max\_spot\_price: "Max price price for spot instances per hour. This variable will be passed to the create fleet as max spot price for the fleet."<br/>        instance\_target\_capacity\_type: "Default lifecycle used for runner instances, can be either `spot` or `on-demand`."<br/>        instance\_types: "List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux and Windows Server Core for win)."<br/>        job\_queue\_retention\_in\_seconds: "The number of seconds the job is held in the queue before it is purged"<br/>        minimum\_running\_time\_in\_minutes: "The time an ec2 action runner should be running at minimum before terminated if not busy."<br/>        pool\_runner\_owner: "The pool will deploy runners to the GitHub org ID, set this value to the org to which you want the runners deployed. Repo level is not supported."<br/>        runner\_additional\_security\_group\_ids: "List of additional security groups IDs to apply to the runner. If added outside the multi\_runner\_config block, the additional security group(s) will be applied to all runner configs. If added inside the multi\_runner\_config, the additional security group(s) will be applied to the individual runner."<br/>        runner\_as\_root: "Run the action runner under the root user. Variable `runner_run_as` will be ignored."<br/>        runner\_boot\_time\_in\_minutes: "The minimum time for an EC2 runner to boot and register as a runner."<br/>        runner\_disable\_default\_labels: "Disable default labels for the runners (os, architecture and `self-hosted`). If enabled, the runner will only have the extra labels provided in `runner_extra_labels`. In case you on own start script is used, this configuration parameter needs to be parsed via SSM."<br/>        runner\_extra\_labels: "Extra (custom) labels for the runners (GitHub). Separate each label by a comma. Labels checks on the webhook can be enforced by setting `multi_runner_config.matcherConfig.exactMatch`. GitHub read-only labels should not be provided."<br/>        runner\_group\_name: "Name of the runner group."<br/>        runner\_name\_prefix: "Prefix for the GitHub runner name."<br/>        runner\_run\_as: "Run the GitHub actions agent as user."<br/>        runners\_maximum\_count: "The maximum number of runners that will be created. Setting the variable to `-1` desiables the maximum check."<br/>        scale\_down\_schedule\_expression: "Scheduler expression to check every x for scale down."<br/>        scale\_up\_reserved\_concurrent\_executions: "Amount of reserved concurrent executions for the scale-up lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations."<br/>        userdata\_template: "Alternative user-data template, replacing the default template. By providing your own user\_data you have to take care of installing all required software, including the action runner. Variables userdata\_pre/post\_install are ignored."<br/>        enable\_jit\_config "Overwrite the default behavior for JIT configuration. By default JIT configuration is enabled for ephemeral runners and disabled for non-ephemeral runners. In case of GHES check first if the JIT config API is available. In case you are upgrading from 3.x to 4.x you can set `enable_jit_config` to `false` to avoid a breaking change when having your own AMI."<br/>        enable\_runner\_detailed\_monitoring: "Should detailed monitoring be enabled for the runner. Set this to true if you want to use detailed monitoring. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html for details."<br/>        enable\_cloudwatch\_agent: "Enabling the cloudwatch agent on the ec2 runner instances, the runner contains default config. Configuration can be overridden via `cloudwatch_config`."<br/>        cloudwatch\_config: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        userdata\_pre\_install: "Script to be ran before the GitHub Actions runner is installed on the EC2 instances"<br/>        userdata\_post\_install: "Script to be ran after the GitHub Actions runner is installed on the EC2 instances"<br/>        runner\_hook\_job\_started: "Script to be ran in the runner environment at the beginning of every job"<br/>        runner\_hook\_job\_completed: "Script to be ran in the runner environment at the end of every job"<br/>        runner\_ec2\_tags: "Map of tags that will be added to the launch template instance tag specifications."<br/>        runner\_iam\_role\_managed\_policy\_arns: "Attach AWS or customer-managed IAM policies (by ARN) to the runner IAM role"<br/>        vpc\_id: "The VPC for security groups of the action runners. If not set uses the value of `var.vpc_id`."<br/>        subnet\_ids: "List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. If not set, uses the value of `var.subnet_ids`."<br/>        idle\_config: "List of time period that can be defined as cron expression to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."<br/>        runner\_log\_files: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        block\_device\_mappings: "The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`."<br/>        job\_retry: "Experimental! Can be removed / changed without trigger a major release. Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app."<br/>        pool\_config: "The configuration for updating the pool. The `pool_size` to adjust to by the events triggered by the `schedule_expression`. For example you can configure a cron expression for week days to adjust the pool to 10 and another expression for the weekend to adjust the pool to 1. Use `schedule_expression_timezone` to override the schedule time zone (defaults to UTC)."<br/>      }<br/>      matcherConfig: {<br/>        labelMatchers: "The list of list of labels supported by the runner configuration. `[[self-hosted, linux, x64, example]]`"<br/>        exactMatch: "If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ workflow label matches it will trigger the webhook."<br/>        priority: "If set it defines the priority of the matcher, the matcher with the lowest priority will be evaluated first. Default is 999, allowed values 0-999."<br/>      }<br/>      redrive\_build\_queue: "Set options to attach (optional) a dead letter queue to the build queue, the queue between the webhook and the scale up lambda. You have the following options. 1. Disable by setting `enabled` to false. 2. Enable by setting `enabled` to `true`, `maxReceiveCount` to a number of max retries."<br/>    } | <pre>map(object({<br/>    runner_config = object({<br/>      runner_os           = string<br/>      runner_architecture = string<br/>      runner_metadata_options = optional(map(any), {<br/>        instance_metadata_tags      = "enabled"<br/>        http_endpoint               = "enabled"<br/>        http_tokens                 = "required"<br/>        http_put_response_hop_limit = 1<br/>      })<br/>      ami = optional(object({<br/>        filter               = optional(map(list(string)), { state = ["available"] })<br/>        owners               = optional(list(string), ["amazon"])<br/>        id_ssm_parameter_arn = optional(string, null)<br/>        kms_key_arn          = optional(string, null)<br/>      }), null)<br/>      create_service_linked_role_spot      = optional(bool, false)<br/>      credit_specification                 = optional(string, null)<br/>      delay_webhook_event                  = optional(number, 30)<br/>      disable_runner_autoupdate            = optional(bool, false)<br/>      ebs_optimized                        = optional(bool, false)<br/>      enable_ephemeral_runners             = optional(bool, false)<br/>      enable_job_queued_check              = optional(bool, null)<br/>      enable_on_demand_failover_for_errors = optional(list(string), [])<br/>      scale_errors = optional(list(string), [<br/>        "UnfulfillableCapacity",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "TargetCapacityLimitExceededException",<br/>        "RequestLimitExceeded",<br/>        "ResourceLimitExceeded",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "MaxSpotFleetRequestCountExceeded",<br/>        "InsufficientInstanceCapacity",<br/>        "InsufficientCapacityOnHost",<br/>      ])<br/>      enable_organization_runners             = optional(bool, false)<br/>      enable_runner_binaries_syncer           = optional(bool, true)<br/>      enable_ssm_on_runners                   = optional(bool, false)<br/>      enable_userdata                         = optional(bool, true)<br/>      instance_allocation_strategy            = optional(string, "lowest-price")<br/>      instance_max_spot_price                 = optional(string, null)<br/>      instance_target_capacity_type           = optional(string, "spot")<br/>      instance_types                          = list(string)<br/>      job_queue_retention_in_seconds          = optional(number, 86400)<br/>      minimum_running_time_in_minutes         = optional(number, null)<br/>      pool_runner_owner                       = optional(string, null)<br/>      runner_as_root                          = optional(bool, false)<br/>      runner_boot_time_in_minutes             = optional(number, 5)<br/>      runner_disable_default_labels           = optional(bool, false)<br/>      runner_extra_labels                     = optional(list(string), [])<br/>      runner_group_name                       = optional(string, "Default")<br/>      runner_name_prefix                      = optional(string, "")<br/>      runner_run_as                           = optional(string, "ec2-user")<br/>      runners_maximum_count                   = number<br/>      runner_additional_security_group_ids    = optional(list(string), [])<br/>      scale_down_schedule_expression          = optional(string, "cron(*/5 * * * ? *)")<br/>      scale_up_reserved_concurrent_executions = optional(number, 1)<br/>      userdata_template                       = optional(string, null)<br/>      userdata_content                        = optional(string, null)<br/>      enable_jit_config                       = optional(bool, null)<br/>      enable_runner_detailed_monitoring       = optional(bool, false)<br/>      enable_cloudwatch_agent                 = optional(bool, true)<br/>      cloudwatch_config                       = optional(string, null)<br/>      userdata_pre_install                    = optional(string, "")<br/>      userdata_post_install                   = optional(string, "")<br/>      runner_hook_job_started                 = optional(string, "")<br/>      runner_hook_job_completed               = optional(string, "")<br/>      runner_ec2_tags                         = optional(map(string), {})<br/>      runner_iam_role_managed_policy_arns     = optional(list(string), [])<br/>      vpc_id                                  = optional(string, null)<br/>      subnet_ids                              = optional(list(string), null)<br/>      idle_config = optional(list(object({<br/>        cron             = string<br/>        timeZone         = string<br/>        idleCount        = number<br/>        evictionStrategy = optional(string, "oldest_first")<br/>      })), [])<br/>      cpu_options = optional(object({<br/>        core_count       = number<br/>        threads_per_core = number<br/>      }), null)<br/>      placement = optional(object({<br/>        affinity                = optional(string)<br/>        availability_zone       = optional(string)<br/>        group_id                = optional(string)<br/>        group_name              = optional(string)<br/>        host_id                 = optional(string)<br/>        host_resource_group_arn = optional(string)<br/>        spread_domain           = optional(string)<br/>        tenancy                 = optional(string)<br/>        partition_number        = optional(number)<br/>      }), null)<br/>      runner_log_files = optional(list(object({<br/>        log_group_name   = string<br/>        prefix_log_group = bool<br/>        file_path        = string<br/>        log_stream_name  = string<br/>        log_class        = optional(string, "STANDARD")<br/>      })), null)<br/>      block_device_mappings = optional(list(object({<br/>        delete_on_termination = optional(bool, true)<br/>        device_name           = optional(string, "/dev/xvda")<br/>        encrypted             = optional(bool, true)<br/>        iops                  = optional(number)<br/>        kms_key_id            = optional(string)<br/>        snapshot_id           = optional(string)<br/>        throughput            = optional(number)<br/>        volume_size           = number<br/>        volume_type           = optional(string, "gp3")<br/>        })), [{<br/>        volume_size = 30<br/>      }])<br/>      pool_config = optional(list(object({<br/>        schedule_expression          = string<br/>        schedule_expression_timezone = optional(string)<br/>        size                         = number<br/>      })), [])<br/>      job_retry = optional(object({<br/>        enable             = optional(bool, false)<br/>        delay_in_seconds   = optional(number, 300)<br/>        delay_backoff      = optional(number, 2)<br/>        lambda_memory_size = optional(number, 256)<br/>        lambda_timeout     = optional(number, 30)<br/>        max_attempts       = optional(number, 1)<br/>      }), {})<br/>    })<br/>    matcherConfig = object({<br/>      labelMatchers = list(list(string))<br/>      exactMatch    = optional(bool, false)<br/>      priority      = optional(number, 999)<br/>    })<br/>    redrive_build_queue = optional(object({<br/>      enabled         = bool<br/>      maxReceiveCount = number<br/>      }), {<br/>      enabled         = false<br/>      maxReceiveCount = null<br/>    })<br/>  }))</pre> | n/a | yes |
+| <a name="input_multi_runner_config"></a> [multi\_runner\_config](#input\_multi\_runner\_config) | multi\_runner\_config = {<br/>      runner\_config: {<br/>        runner\_os: "The EC2 Operating System type to use for action runner instances (linux, osx, windows)."<br/>        runner\_architecture: "The platform architecture of the runner instance\_type."<br/>        runner\_metadata\_options: "(Optional) Metadata options for the ec2 runner instances."<br/>        ami: "(Optional) AMI configuration for the action runner instances. This object allows you to specify all AMI-related settings in one place."<br/>        create\_service\_linked\_role\_spot: (Optional) create the serviced linked role for spot instances that is required by the scale-up lambda.<br/>        credit\_specification: "(Optional) The credit specification of the runner instance\_type. Can be unset, `standard` or `unlimited`.<br/>        delay\_webhook\_event: "The number of seconds the event accepted by the webhook is invisible on the queue before the scale up lambda will receive the event."<br/>        disable\_runner\_autoupdate: "Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/)"<br/>        ebs\_optimized: "The EC2 EBS optimized configuration."<br/>        enable\_ephemeral\_runners: "Enable ephemeral runners, runners will only be used once."<br/>        enable\_dynamic\_labels: "Experimental! Can be removed / changed without trigger a major release. Enable dynamic labels with 'ghr-' prefix. When enabled, jobs can use 'ghr-ec2-<config>:<value>' labels to dynamically configure EC2 instances (e.g., 'ghr-ec2-instance-type:t3.large') and 'ghr-run-<label>' to add unique labels dynamically to runners."<br/>        enable\_job\_queued\_check: Enables JIT configuration for creating runners instead of registration token based registraton. JIT configuration will only be applied for ephemeral runners. By default JIT configuration is enabled for ephemeral runners an can be disabled via this override. When running on GHES without support for JIT configuration this variable should be set to true for ephemeral runners."<br/>        enable\_on\_demand\_failover\_for\_errors: "Enable on-demand failover. For example to fall back to on demand when no spot capacity is available the variable can be set to `InsufficientInstanceCapacity`. When not defined the default behavior is to retry later."<br/>        scale\_errors: "List of aws error codes that should trigger retry during scale up. This list will replace the default errors defined in the variable `defaultScaleErrors` in https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/functions/control-plane/src/aws/runners.ts"<br/>        enable\_organization\_runners: "Register runners to organization, instead of repo level"<br/>        enable\_runner\_binaries\_syncer: "Option to disable the lambda to sync GitHub runner distribution, useful when using a pre-build AMI."<br/>        enable\_ssm\_on\_runners: "Enable to allow access the runner instances for debugging purposes via SSM. Note that this adds additional permissions to the runner instances."<br/>        enable\_userdata: "Should the userdata script be enabled for the runner. Set this to false if you are using your own prebuilt AMI."<br/>        instance\_allocation\_strategy: "The allocation strategy for spot instances. AWS recommends to use `capacity-optimized` however the AWS default is `lowest-price`."<br/>        instance\_max\_spot\_price: "Max price price for spot instances per hour. This variable will be passed to the create fleet as max spot price for the fleet."<br/>        instance\_target\_capacity\_type: "Default lifecycle used for runner instances, can be either `spot` or `on-demand`."<br/>        instance\_types: "List of instance types for the action runner. Defaults are based on runner\_os (al2023 for linux, macOS Sequoia for osx, Windows Server Core for win)."<br/>        job\_queue\_retention\_in\_seconds: "The number of seconds the job is held in the queue before it is purged"<br/>        minimum\_running\_time\_in\_minutes: "The time an ec2 action runner should be running at minimum before terminated if not busy."<br/>        pool\_runner\_owner: "The pool will deploy runners to the GitHub org ID, set this value to the org to which you want the runners deployed. Repo level is not supported."<br/>        runner\_additional\_security\_group\_ids: "List of additional security groups IDs to apply to the runner. If added outside the multi\_runner\_config block, the additional security group(s) will be applied to all runner configs. If added inside the multi\_runner\_config, the additional security group(s) will be applied to the individual runner."<br/>        runner\_as\_root: "Run the action runner under the root user. Variable `runner_run_as` will be ignored."<br/>        runner\_boot\_time\_in\_minutes: "The minimum time for an EC2 runner to boot and register as a runner."<br/>        runner\_disable\_default\_labels: "Disable default labels for the runners (os, architecture and `self-hosted`). If enabled, the runner will only have the extra labels provided in `runner_extra_labels`. In case you on own start script is used, this configuration parameter needs to be parsed via SSM."<br/>        runner\_extra\_labels: "Extra (custom) labels for the runners (GitHub). Separate each label by a comma. Labels checks on the webhook can be enforced by setting `multi_runner_config.matcherConfig.exactMatch`. GitHub read-only labels should not be provided."<br/>        runner\_group\_name: "Name of the runner group."<br/>        runner\_name\_prefix: "Prefix for the GitHub runner name."<br/>        runner\_run\_as: "Run the GitHub actions agent as user."<br/>        runners\_maximum\_count: "The maximum number of runners that will be created. Setting the variable to `-1` desiables the maximum check."<br/>        scale\_down\_schedule\_expression: "Scheduler expression to check every x for scale down."<br/>        scale\_up\_reserved\_concurrent\_executions: "Amount of reserved concurrent executions for the scale-up lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations."<br/>        userdata\_template: "Alternative user-data template, replacing the default template. By providing your own user\_data you have to take care of installing all required software, including the action runner. Variables userdata\_pre/post\_install are ignored."<br/>        enable\_jit\_config "Overwrite the default behavior for JIT configuration. By default JIT configuration is enabled for ephemeral runners and disabled for non-ephemeral runners. In case of GHES check first if the JIT config API is available. In case you are upgrading from 3.x to 4.x you can set `enable_jit_config` to `false` to avoid a breaking change when having your own AMI."<br/>        enable\_runner\_detailed\_monitoring: "Should detailed monitoring be enabled for the runner. Set this to true if you want to use detailed monitoring. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html for details."<br/>        enable\_cloudwatch\_agent: "Enabling the cloudwatch agent on the ec2 runner instances, the runner contains default config. Configuration can be overridden via `cloudwatch_config`."<br/>        cloudwatch\_config: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        userdata\_pre\_install: "Script to be ran before the GitHub Actions runner is installed on the EC2 instances"<br/>        userdata\_post\_install: "Script to be ran after the GitHub Actions runner is installed on the EC2 instances"<br/>        runner\_hook\_job\_started: "Script to be ran in the runner environment at the beginning of every job"<br/>        runner\_hook\_job\_completed: "Script to be ran in the runner environment at the end of every job"<br/>        runner\_ec2\_tags: "Map of tags that will be added to the launch template instance tag specifications."<br/>        runner\_iam\_role\_managed\_policy\_arns: "Attach AWS or customer-managed IAM policies (by ARN) to the runner IAM role"<br/>        vpc\_id: "The VPC for security groups of the action runners. If not set uses the value of `var.vpc_id`."<br/>        subnet\_ids: "List of subnets in which the action runners will be launched, the subnets needs to be subnets in the `vpc_id`. If not set, uses the value of `var.subnet_ids`."<br/>        idle\_config: "List of time period that can be defined as cron expression to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."<br/>        license\_specifications: "Optional EC2 License Manager license configuration ARNs for the runner launch template. Required for macOS dedicated-host runners when the host resource group uses a Mac dedicated host license configuration."<br/>        use\_dedicated\_host: "Experimental! Can be removed / changed without trigger a major release. Whether to use EC2 dedicated hosts for the runners. Needed for macos runners Note that using dedicated hosts can increase cost significantly."<br/>        runner\_log\_files: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."<br/>        block\_device\_mappings: "The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`."<br/>        job\_retry: "Experimental! Can be removed / changed without trigger a major release. Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app."<br/>        pool\_config: "The configuration for updating the pool. The `pool_size` to adjust to by the events triggered by the `schedule_expression`. For example you can configure a cron expression for week days to adjust the pool to 10 and another expression for the weekend to adjust the pool to 1. Use `schedule_expression_timezone` to override the schedule time zone (defaults to UTC)."<br/>      }<br/>      matcherConfig: {<br/>        labelMatchers: "The list of list of labels supported by the runner configuration. `[[self-hosted, linux, x64, example]]`"<br/>        exactMatch: "If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ workflow label matches it will trigger the webhook."<br/>        priority: "If set it defines the priority of the matcher, the matcher with the lowest priority will be evaluated first. Default is 999, allowed values 0-999."<br/>      }<br/>      redrive\_build\_queue: "Set options to attach (optional) a dead letter queue to the build queue, the queue between the webhook and the scale up lambda. You have the following options. 1. Disable by setting `enabled` to false. 2. Enable by setting `enabled` to `true`, `maxReceiveCount` to a number of max retries."<br/>    } | <pre>map(object({<br/>    runner_config = object({<br/>      runner_os           = string<br/>      runner_architecture = string<br/>      runner_metadata_options = optional(map(any), {<br/>        instance_metadata_tags      = "enabled"<br/>        http_endpoint               = "enabled"<br/>        http_tokens                 = "required"<br/>        http_put_response_hop_limit = 1<br/>      })<br/>      ami = optional(object({<br/>        filter               = optional(map(list(string)), { state = ["available"] })<br/>        owners               = optional(list(string), ["amazon"])<br/>        id_ssm_parameter_arn = optional(string, null)<br/>        kms_key_arn          = optional(string, null)<br/>      }), null)<br/>      create_service_linked_role_spot      = optional(bool, false)<br/>      credit_specification                 = optional(string, null)<br/>      delay_webhook_event                  = optional(number, 30)<br/>      disable_runner_autoupdate            = optional(bool, false)<br/>      ebs_optimized                        = optional(bool, false)<br/>      enable_ephemeral_runners             = optional(bool, false)<br/>      enable_job_queued_check              = optional(bool, null)<br/>      enable_on_demand_failover_for_errors = optional(list(string), [])<br/>      scale_errors = optional(list(string), [<br/>        "UnfulfillableCapacity",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "TargetCapacityLimitExceededException",<br/>        "RequestLimitExceeded",<br/>        "ResourceLimitExceeded",<br/>        "MaxSpotInstanceCountExceeded",<br/>        "MaxSpotFleetRequestCountExceeded",<br/>        "InsufficientInstanceCapacity",<br/>        "InsufficientCapacityOnHost",<br/>      ])<br/>      enable_organization_runners             = optional(bool, false)<br/>      enable_runner_binaries_syncer           = optional(bool, true)<br/>      enable_ssm_on_runners                   = optional(bool, false)<br/>      enable_userdata                         = optional(bool, true)<br/>      instance_allocation_strategy            = optional(string, "lowest-price")<br/>      instance_max_spot_price                 = optional(string, null)<br/>      instance_target_capacity_type           = optional(string, "spot")<br/>      instance_types                          = list(string)<br/>      job_queue_retention_in_seconds          = optional(number, 86400)<br/>      minimum_running_time_in_minutes         = optional(number, null)<br/>      pool_runner_owner                       = optional(string, null)<br/>      runner_as_root                          = optional(bool, false)<br/>      runner_boot_time_in_minutes             = optional(number, 5)<br/>      runner_disable_default_labels           = optional(bool, false)<br/>      runner_extra_labels                     = optional(list(string), [])<br/>      runner_group_name                       = optional(string, "Default")<br/>      runner_name_prefix                      = optional(string, "")<br/>      runner_run_as                           = optional(string, "ec2-user")<br/>      runners_maximum_count                   = number<br/>      runner_additional_security_group_ids    = optional(list(string), [])<br/>      scale_down_schedule_expression          = optional(string, "cron(*/5 * * * ? *)")<br/>      scale_up_reserved_concurrent_executions = optional(number, 1)<br/>      userdata_template                       = optional(string, null)<br/>      userdata_content                        = optional(string, null)<br/>      enable_jit_config                       = optional(bool, null)<br/>      enable_runner_detailed_monitoring       = optional(bool, false)<br/>      enable_cloudwatch_agent                 = optional(bool, true)<br/>      cloudwatch_config                       = optional(string, null)<br/>      userdata_pre_install                    = optional(string, "")<br/>      userdata_post_install                   = optional(string, "")<br/>      runner_hook_job_started                 = optional(string, "")<br/>      runner_hook_job_completed               = optional(string, "")<br/>      runner_ec2_tags                         = optional(map(string), {})<br/>      runner_iam_role_managed_policy_arns     = optional(list(string), [])<br/>      vpc_id                                  = optional(string, null)<br/>      subnet_ids                              = optional(list(string), null)<br/>      idle_config = optional(list(object({<br/>        cron             = string<br/>        timeZone         = string<br/>        idleCount        = number<br/>        evictionStrategy = optional(string, "oldest_first")<br/>      })), [])<br/>      cpu_options = optional(object({<br/>        core_count            = optional(number)<br/>        threads_per_core      = optional(number)<br/>        amd_sev_snp           = optional(string)<br/>        nested_virtualization = optional(string)<br/>      }), null)<br/>      placement = optional(object({<br/>        affinity                = optional(string)<br/>        availability_zone       = optional(string)<br/>        group_id                = optional(string)<br/>        group_name              = optional(string)<br/>        host_id                 = optional(string)<br/>        host_resource_group_arn = optional(string)<br/>        spread_domain           = optional(string)<br/>        tenancy                 = optional(string)<br/>        partition_number        = optional(number)<br/>      }), null)<br/>      license_specifications = optional(list(object({<br/>        license_configuration_arn = string<br/>      })), [])<br/>      use_dedicated_host = optional(bool, false)<br/>      runner_log_files = optional(list(object({<br/>        log_group_name   = string<br/>        prefix_log_group = bool<br/>        file_path        = string<br/>        log_stream_name  = string<br/>        log_class        = optional(string, "STANDARD")<br/>      })), null)<br/>      block_device_mappings = optional(list(object({<br/>        delete_on_termination = optional(bool, true)<br/>        device_name           = optional(string, "/dev/xvda")<br/>        encrypted             = optional(bool, true)<br/>        iops                  = optional(number)<br/>        kms_key_id            = optional(string)<br/>        snapshot_id           = optional(string)<br/>        throughput            = optional(number)<br/>        volume_size           = number<br/>        volume_type           = optional(string, "gp3")<br/>        })), [{<br/>        volume_size = 30<br/>      }])<br/>      pool_config = optional(list(object({<br/>        schedule_expression          = string<br/>        schedule_expression_timezone = optional(string)<br/>        size                         = number<br/>      })), [])<br/>      job_retry = optional(object({<br/>        enable             = optional(bool, false)<br/>        delay_in_seconds   = optional(number, 300)<br/>        delay_backoff      = optional(number, 2)<br/>        lambda_memory_size = optional(number, 256)<br/>        lambda_timeout     = optional(number, 30)<br/>        max_attempts       = optional(number, 1)<br/>      }), {})<br/>    })<br/>    matcherConfig = object({<br/>      labelMatchers = list(list(string))<br/>      exactMatch    = optional(bool, false)<br/>      priority      = optional(number, 999)<br/>    })<br/>    redrive_build_queue = optional(object({<br/>      enabled         = bool<br/>      maxReceiveCount = number<br/>      }), {<br/>      enabled         = false<br/>      maxReceiveCount = null<br/>    })<br/>  }))</pre> | n/a | yes |
 | <a name="input_parameter_store_tags"></a> [parameter\_store\_tags](#input\_parameter\_store\_tags) | Map of tags that will be added to all the SSM Parameter Store parameters created by the Lambda function. | `map(string)` | `{}` | no |
 | <a name="input_pool_lambda_reserved_concurrent_executions"></a> [pool\_lambda\_reserved\_concurrent\_executions](#input\_pool\_lambda\_reserved\_concurrent\_executions) | Amount of reserved concurrent executions for the scale-up lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations. | `number` | `1` | no |
 | <a name="input_pool_lambda_timeout"></a> [pool\_lambda\_timeout](#input\_pool\_lambda\_timeout) | Time out for the pool lambda in seconds. | `number` | `60` | no |
diff --git a/modules/runners/README.md b/modules/runners/README.md
index 5e5ee3835f..e4e97efc66 100644
--- a/modules/runners/README.md
+++ b/modules/runners/README.md
@@ -53,13 +53,13 @@ yarn run dist
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.21 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 6.21 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 6.33 |
 
 ## Modules
 
@@ -142,7 +142,7 @@ yarn run dist
 | <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS region. | `string` | n/a | yes |
 | <a name="input_block_device_mappings"></a> [block\_device\_mappings](#input\_block\_device\_mappings) | The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`. | <pre>list(object({<br/>    delete_on_termination = optional(bool, true)<br/>    device_name           = optional(string, "/dev/xvda")<br/>    encrypted             = optional(bool, true)<br/>    iops                  = optional(number)<br/>    kms_key_id            = optional(string)<br/>    snapshot_id           = optional(string)<br/>    throughput            = optional(number)<br/>    volume_size           = number<br/>    volume_type           = optional(string, "gp3")<br/>  }))</pre> | <pre>[<br/>  {<br/>    "volume_size": 30<br/>  }<br/>]</pre> | no |
 | <a name="input_cloudwatch_config"></a> [cloudwatch\_config](#input\_cloudwatch\_config) | (optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details. | `string` | `null` | no |
-| <a name="input_cpu_options"></a> [cpu\_options](#input\_cpu\_options) | The CPU options for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#cpu-options for details. Note that not all instance types support CPU options, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#instance-cpu-options | <pre>object({<br/>    core_count       = number<br/>    threads_per_core = number<br/>  })</pre> | `null` | no |
+| <a name="input_cpu_options"></a> [cpu\_options](#input\_cpu\_options) | The CPU options for the instance. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template#cpu-options for details. Note that not all instance types support CPU options, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#instance-cpu-options | <pre>object({<br/>    core_count            = optional(number)<br/>    threads_per_core      = optional(number)<br/>    amd_sev_snp           = optional(string)<br/>    nested_virtualization = optional(string)<br/>  })</pre> | `null` | no |
 | <a name="input_create_service_linked_role_spot"></a> [create\_service\_linked\_role\_spot](#input\_create\_service\_linked\_role\_spot) | (optional) create the service linked role for spot instances that is required by the scale-up lambda. | `bool` | `false` | no |
 | <a name="input_credit_specification"></a> [credit\_specification](#input\_credit\_specification) | The credit option for CPU usage of a T instance. Can be unset, "standard" or "unlimited". | `string` | `null` | no |
 | <a name="input_disable_runner_autoupdate"></a> [disable\_runner\_autoupdate](#input\_disable\_runner\_autoupdate) | Disable the auto update of the github runner agent. Be aware there is a grace period of 30 days, see also the [GitHub article](https://github.blog/changelog/2022-02-01-github-actions-self-hosted-runners-can-now-disable-automatic-updates/) | `bool` | `false` | no |