GitHub Runners on AWS

https://github-aws-runners.github.io/terraform-aws-github-runner
Admin
A Terraform module that creates auto-scaling GitHub Actions self-hosted runners on AWS spot...
Tokens:24,018
Snippets:349
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runner-binaries-syncer

Navigate to the lambda directory and install required packages using yarn.

```bash
cd lambdas/runners
yarn install
```

--------------------------------

### Initialize and Apply Setup Workspace

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/permissions-boundary

Execute these commands to initialize and apply the setup workspace for creating roles and policies.

```bash
cd setup
terraform init
terraform apply
cd ..
```

--------------------------------

### Install Lambda Dependencies

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/webhook

Commands to install dependencies for the webhook Lambda function.

```bash
cd lambdas/webhook
yarn install
```

--------------------------------

### Configure AMI Housekeeper Module

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/ami-housekeeper

Example configuration for deploying the AMI Housekeeper module with specific cleanup criteria and filters.

```hcl
module "ami_housekeeper" {
  source = "path to module"

  prefix = "my-prefix"

  ami_cleanup_config = {
    ssmParameterNames = ["*/ami-id"]
    minimumDaysOld    = 30
    filters = [
      {
        Name   = "tag:Packer"
        Values = ["true"]
      }
    ]
    dryRun = true
  }

  log_level = "debug"
}
```

--------------------------------

### Configure macOS in multi-runner setup

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/mac-runners

Shows how to include a macOS runner configuration within a multi-runner module setup.

```hcl
multi_runner_config = {
  "mac-arm64" = {
    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>"
      }
      license_specifications = ["<arn-of-your-license-configuration>"]
      runner_extra_labels    = ["osx", "arm64"]
    }
    matcherConfig = {
      labelMatchers = [["self-hosted", "osx", "arm64"]]
      exactMatch    = false
    }
  }
}
```

--------------------------------

### Build Lambda Functions

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/termination-watcher

Install dependencies and build the Lambda function locally using Node.js and Yarn.

```bash
cd lambdas
yarn install && yarn dist
```

--------------------------------

### Configure IAM Module Usage

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/setup-iam-permissions

Example configuration for the IAM module, including required namespace definitions for boundaries and roles.

```hcl
module "iam" {
  source = "../../"

  environment = "default"
  account_id  = "123456789

  namespaces = {
    boundary_namespace         = "boundaries"
    role_namespace             = "runners"
    policy_namespace           = "runners"
    instance_profile_namespace = "runners"
  }
}

output "role" {
  value = module.iam.role
}

output "boundary" {
  value = module.iam.boundary
}
```

--------------------------------

### Initialize, Validate, and Build Packer Image

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/ami-examples

Commands to initialize Packer, validate the configuration, and build a custom Linux AL2023 AMI for GitHub runners. Ensure you have Packer installed and AWS credentials configured.

```bash
packer init .
packer validate .
packer build github_agent.linux.pkr.hcl

```

--------------------------------

### Configure runner module with AMI filter

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/prebuilt

Example configuration for the runners module using a specific AMI filter and owner ID.

```hcl
module "runners" {
  ...
  # set the name of the ami to use
  ami = {
    filter = { name = ["github-runner-al2023-x86_64-2023*"], state = ["available"] }
    # provide the owner id of
    owners = ["<your owner id>"]
  }

  enable_userdata = false
  ...
}
```

--------------------------------

### Configure GitHub Runner Terraform Module

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/getting-started

Example configuration for the github-runner module. Ensure the github_app.key_base64 is a valid base64-encoded string of your private key.

```hcl
module "github-runner" {
  source  = "github-aws-runners/github-runner/aws"
  version = "REPLACE_WITH_VERSION"

  aws_region = "eu-west-1"
  vpc_id     = "vpc-123"
  subnet_ids = ["subnet-123", "subnet-456"]

  prefix = "gh-ci"

  github_app = {
    key_base64     = "base64string"
    id             = "1"
    webhook_secret = "webhook_secret"
  }

  webhook_lambda_zip                = "lambdas-download/webhook.zip"
  runner_binaries_syncer_lambda_zip = "lambdas-download/runner-binaries-syncer.zip"
  runners_lambda_zip                = "lambdas-download/runners.zip"
  enable_organization_runners = true
}

```

--------------------------------

### Log output for spot notifications

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Example of the JSON log structure generated by the termination watcher and handler for spot warnings and terminations.

```json
{
    "level": "INFO",
    "message": "Received spot notification for ${metricName}",
    "environment": "default",
    "instanceId": "i-0039b8826b3dcea55",
    "instanceType": "c5.large",
    "instanceLaunchTime": "2024-03-15T08:10:34.000Z",
    "instanceRunningTimeInSeconds": 68,
    "tags": [
        {
            "Key": "ghr:environment",
            "Value": "default"
        }
        ... all tags ...
    ]
}
```

--------------------------------

### View scale-up function log message structure

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Example of the JSON log output generated by the scale-up Lambda function.

```json
{
  "level": "INFO",
  "message": "Received event",
  "service": "runners-scale-up",
  "timestamp": "2023-03-20T08:15:27.448Z",
  "xray_trace_id": "1-6418161e-08825c2f575213ef760531bf",
  "module": "scale-up",
  "region": "eu-west-1",
  "environment": "my-linux-x64",
  "aws-request-id": "eef1efb7-4c07-555f-9a67-b3255448ee60",
  "function-name": "my-linux-x64-scale-up",
  "runner": {
    "type": "Repo",
    "owner": "test-runners/multi-runner"
  },
  "github": {
    "event": "workflow_job",
    "workflow_job_id": "1234"
  }
}
```

--------------------------------

### Identify Scale-Down Bypass Logs

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/additional_notes

Example log message generated when the scale-down process encounters a protected runner.

```text
Runner 'i-xxxxxxxxxxxx' has bypass-removal tag set, skipping removal. Remove the tag to allow scale-down.
```

--------------------------------

### Configure EventBridge and Custom Event Rules

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Example showing how to disable the default EventBridge mode and define custom CloudWatch event rules and IAM roles for event processing.

```hcl
module "runners" {
  source = "github-aws-runners/github-runners/aws"

  ...
  eventbridge = {
    enable = false
  }
  ...
}

locals {
  event_bus_name = module.runners.webhook.eventbridge.event_bus.name
}

resource "aws_cloudwatch_event_rule" "example" {
  name           = "${local.prefix}-github-events-all"
  description    = "Capture all GitHub events"
  event_bus_name = local.event_bus_name
  event_pattern  = <<EOF
{
  "source": [{
    "prefix": "github"
  }]
}
EOF
}

resource "aws_cloudwatch_event_target" "main" {
  rule           = aws_cloudwatch_event_rule.example.name
  arn            = <arn of target>
  event_bus_name = local.event_bus_name
  role_arn       = aws_iam_role.event_rule_firehose_role.arn
}

data "aws_iam_policy_document" "event_rule_firehose_role" {
  statement {
    actions = ["sts:AssumeRole"]

    principals {
      type        = "Service"
      identifiers = ["events.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "event_rule_role" {
  name               = "${local.prefix}-eventbridge-github-rule"
  assume_role_policy = data.aws_iam_policy_document.event_rule_firehose_role.json
}

data aws_iam_policy_document firehose_stream {
  statement {
    INSERT_YOUR_POLICY_HERE_TO_ACCESS_THE_TARGET
  }
}

resource "aws_iam_role_policy" "event_rule_firehose_role" {
  name = "target-event-rule-firehose"
  role = aws_iam_role.event_rule_firehose_role.name
  policy = data.aws_iam_policy_document.firehose_stream.json
}
```

--------------------------------

### Initialize and Apply Terraform

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/getting-started

Standard commands to initialize the Terraform workspace and apply the configuration.

```bash
terraform init
terraform apply

```

--------------------------------

### Initialize and Apply Terraform Module

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/lambda-download

Initialize Terraform and apply the module, specifying the desired module version. This process downloads the necessary Lambda distributions.

```bash
terraform init
terraform apply -var=module_version=<VERSION>

```

--------------------------------

### Download Lambda Releases

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/permissions-boundary

Download the required lambda releases by initializing and applying the configuration in the lambdas-download directory.

```bash
cd ../lambdas-download
terraform init
terraform apply -var=module_version=<VERSION>
cd -
```

--------------------------------

### Placement Configuration Object

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Schema for defining instance placement options.

```hcl
object({
    affinity                = optional(string)
    availability_zone       = optional(string)
    group_id                = optional(string)
    group_name              = optional(string)
    host_id                 = optional(string)
    host_resource_group_arn = optional(string)
    spread_domain           = optional(string)
    tenancy                 = optional(string)
    partition_number        = optional(number)
  })
```

--------------------------------

### Define License Specifications

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Specifies the structure for EC2 License Manager configurations, required for specific macOS dedicated-host runner setups.

```hcl
list(object({  
    license_configuration_arn = string  
  }))
```

--------------------------------

### Download Lambda Releases

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/ephemeral

Initialize and apply Terraform configurations within the lambdas-download directory to prepare the necessary Lambda functions.

```bash
cd lambdas-download
terraform init
terraform apply
cd ..
```

--------------------------------

### Configure Lambda artifact download module

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/download-lambda

Define the source location and list of Lambda functions with their respective tags to be downloaded.

```hcl
module "lambdas" {
  source = "<source location>"
  lambdas = [
    {
      name = "webhook"
      tag  = "v0.15.0"
    },
    {
      name = "runners"
      tag  = "v0.15.0"
    },
    {
      name = "runner-binaries-syncer"
      tag  = "v0.15.0"
    }
  ]
}
```

--------------------------------

### Run tests

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runner-binaries-syncer

Execute the test suite using vitest, which includes mocked AWS and GitHub calls.

```bash
yarn run test
```

--------------------------------

### Configure Instance Termination Watcher

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Defines the configuration schema for the beta instance termination watcher feature.

```hcl
object({  
    enable = optional(bool, false)  
    features = optional(object({  
      enable_spot_termination_handler              = optional(bool, true)  
      enable_spot_termination_notification_watcher = optional(bool, true)  
    }), {})  
    enable_runner_deregistration = optional(bool, true)  
    memory_size                  = optional(number, null)  
    s3_key                       = optional(string, null)  
    s3_object_version            = optional(string, null)  
    timeout                      = optional(number, null)  
    zip                          = optional(string, null)  
  })
```

--------------------------------

### Configure attribute-based instance selection

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Defines hardware requirements such as vCPU count, memory, and CPU manufacturer to allow the fleet to select appropriate instances.

```yaml
jobs:
  test:
    runs-on:
      - self-hosted
      - linux
      - ghr-ec2-vcpu-count-min:2
      - ghr-ec2-vcpu-count-max:8
      - ghr-ec2-memory-mib-min:8192
      - ghr-ec2-cpu-manufacturers:intel;amd
      - ghr-ec2-burstable-performance:excluded
```

--------------------------------

### Define CPU Options

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Schema for configuring instance CPU options such as core count and thread settings.

```hcl
object({
    core_count            = optional(number)
    threads_per_core      = optional(number)
    amd_sev_snp           = optional(string)
    nested_virtualization = optional(string)
  })
```

--------------------------------

### Configure AMI using SSM parameter

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Provide an SSM parameter ARN containing the AMI ID to allow the scale-up lambda to look up the image at runtime.

```hcl
ami = {
  id_ssm_parameter_arn = "arn:aws:ssm:region:account:parameter/path/to/ami/parameter"
}
```

--------------------------------

### Instance Termination Watcher Configuration

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/multi-runner

Configures the spot termination watcher Lambda function, including feature flags and resource settings.

```hcl
object({  
    enable = optional(bool, false)  
    features = optional(object({  
      enable_spot_termination_handler              = optional(bool, true)  
      enable_spot_termination_notification_watcher = optional(bool, true)  
    }), {})  
    enable_runner_deregistration = optional(bool, true)  
    environment_variables        = optional(map(string), {})  
    memory_size                  = optional(number, null)  
    s3_key                       = optional(string, null)  
    s3_object_version            = optional(string, null)  
    timeout                      = optional(number, null)  
    zip                          = optional(string, null)  
  })
```

--------------------------------

### Deploy Termination Watcher

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/termination-watcher

Initialize and apply the Terraform configuration for the termination watcher.

```hcl
terraform init
terraform apply
```

--------------------------------

### Configure Redrive Build Queue

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Defines the structure and default values for attaching a dead letter queue to the build queue.

```hcl
object({  
    enabled         = bool  
    maxReceiveCount = number  
  })
```

```json
{
  "enabled": false,  
  "maxReceiveCount": null  
}
```

--------------------------------

### SSM Parameter Names

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/external-managed-ssm-secrets

Required SSM parameter paths for GitHub App configuration.

```text
/github-action-runners/app/github_app_id           (Your GitHub App ID)
/github-action-runners/app/github_app_key_base64   (Your GitHub App Private Key)
/github-action-runners/app/github_app_webhook_secret (Your Installation ID)
```

--------------------------------

### Package source code

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runner-binaries-syncer

Compile TypeScript and JavaScript sources into a single file using ncc.

```bash
yarn run dist
```

--------------------------------

### Create SSM Parameters via AWS CLI

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/external-managed-ssm-secrets

Commands to create secure SSM parameters for GitHub App credentials.

```bash
   # GitHub App ID
   aws ssm put-parameter \
     --name "/github-action-runners/app/github_app_id" \
     --value "YOUR_APP_ID" \
     --type "SecureString"

   # GitHub App Private Key
   aws ssm put-parameter \
     --name "/github-action-runners/app/github_app_key_base64" \
     --value "YOUR_PRIVATE_KEY" \
     --type "SecureString"

   # GitHub App Installation ID
   aws ssm put-parameter \
     --name "/github-action-runners/app/github_app_webhook_secret" \
     --value "YOUR_INSTALLATION_ID" \
     --type "SecureString"
```

--------------------------------

### Configure Runner CPU Options

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Defines the CPU options for the runner instance, including core count and thread settings.

```hcl
object({  
    core_count            = optional(number)  
    threads_per_core      = optional(number)  
    amd_sev_snp           = optional(string)  
    nested_virtualization = optional(string)  
  })
```

--------------------------------

### Define Multi-Runner Configuration Inputs

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/multi-runner

Configuration schema for multi-runner module inputs, including lifecycle hooks, VPC settings, and resource specifications.

```hcl
      userdata_pre_install                                           = optional(string, "")  
      userdata_post_install                                          = optional(string, "")  
      runner_hook_job_started                                        = optional(string, "")  
      runner_hook_job_completed                                      = optional(string, "")  
      runner_ec2_tags                                                = optional(map(string), {})  
      runner_iam_role_managed_policy_arns                            = optional(list(string), [])  
      vpc_id                                                         = optional(string, null)  
      subnet_ids                                                     = optional(list(string), null)  
      idle_config = optional(list(object({  
        cron             = string  
        timeZone         = string  
        idleCount        = number  
        evictionStrategy = optional(string, "oldest_first")  
      })), [])  
      cpu_options = optional(object({  
        core_count            = optional(number)  
        threads_per_core      = optional(number)  
        amd_sev_snp           = optional(string)  
        nested_virtualization = optional(string)  
      }), null)  
      placement = optional(object({  
        affinity                = optional(string)  
        availability_zone       = optional(string)  
        group_id                = optional(string)  
        group_name              = optional(string)  
        host_id                 = optional(string)  
        host_resource_group_arn = optional(string)  
        spread_domain           = optional(string)  
        tenancy                 = optional(string)  
        partition_number        = optional(number)  
      }), null)  
      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  
        file_path        = string  
        log_stream_name  = string  
        log_class        = optional(string, "STANDARD")  
      })), null)  
      block_device_mappings = optional(list(object({  
        delete_on_termination      = optional(bool, true)  
        device_name                = optional(string, "/dev/xvda")  
        encrypted                  = optional(bool, true)  
        iops                       = optional(number)  
        kms_key_id                 = optional(string)  
        snapshot_id                = optional(string)  
        throughput                 = optional(number)  
        volume_initialization_rate = optional(number)  
        volume_size                = number  
        volume_type                = optional(string, "gp3")  
        })), [{  
        volume_size = 30  
      }])  
      pool_config = optional(list(object({  
        schedule_expression          = string  
        schedule_expression_timezone = optional(string)  
        size                         = number  
      })), [])  
      job_retry = optional(object({  
        enable             = optional(bool, false)  
        delay_in_seconds   = optional(number, 300)  
        delay_backoff      = optional(number, 2)  
        lambda_memory_size = optional(number, 256)  
        lambda_timeout     = optional(number, 30)  
        max_attempts       = optional(number, 1)  
      }), {})  
      iam_overrides = optional(object({  
        override_instance_profile = optional(bool, null)  
        instance_profile_name     = optional(string, null)  
        override_runner_role      = optional(bool, null)  
        runner_role_arn           = optional(string, null)  
        }), {  
        override_instance_profile = false  
        instance_profile_name     = null  
        override_runner_role      = false  
        runner_role_arn           = null  
      })  
    })  
    matcherConfig = object({  
      labelMatchers           = list(list(string))  
      exactMatch              = optional(bool, false)  
      bidirectionalLabelMatch = optional(bool, false)  
      priority                = optional(number, 999)  
      enableDynamicLabels     = optional(bool, false)  
      awsDynamicLabelsPolicy  = optional(any, null)  
    })  
    redrive_build_queue = optional(object({  
      enabled         = bool  
      maxReceiveCount = number  
      }), {  
      enabled         = false  
      maxReceiveCount = null  
    })  
  }))
```

--------------------------------

### Configure AMI using filters

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Define AMI filters and owners to dynamically look up an image, which the module then stores in an SSM parameter.

```hcl
ami = {
  filter = {
    name   = ["ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-*"]
    state  = ["available"]
  }
  owners = ["amazon"]
}
```

--------------------------------

### Configure basic macOS runner

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/mac-runners

Defines the required settings for macOS runners, including dedicated host and license specifications.

```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"]
  instance_target_capacity_type = "on-demand"

  # 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...
}
```

--------------------------------

### Enable SSM Parameter Store High Throughput

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/rate-limits-and-tuning

Updates the service setting to enable high-throughput mode for SSM Parameter Store, increasing the default 40 TPS limit.

```bash
aws ssm update-service-setting \
  --setting-id arn:aws:ssm:<region>:<account-id>:servicesetting/ssm/parameter-store/high-throughput-enabled \
  --setting-value true
```

--------------------------------

### Define Parameter Store Tags

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/multi-runner

Configuration for tagging SSM Parameter Store parameters created by the Lambda function.

```hcl
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
```

--------------------------------

### Configure Idle Runner Scaling

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Structure for defining cron-based idle runner counts to prevent scaling to zero during specific periods.

```hcl
list(object({  
    cron             = string  
    timeZone         = string  
    idleCount        = number  
    evictionStrategy = optional(string, "oldest_first")  
  }))
```

--------------------------------

### Define GitHub App Parameters

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Configuration structure for multiple GitHub Apps to distribute API rate limits.

```hcl
object({  
    key_base64      = list(map(string))  
    id              = list(map(string))  
    installation_id = list(object({ name = string, arn = string }))  
  })
```

--------------------------------

### GitHub App Parameters Input

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/webhook

Terraform object structure for defining GitHub App Parameter Store settings.

```hcl
object({
    webhook_secret = map(string)
  })
```

--------------------------------

### Metrics Configuration Object

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Configures the metrics generated by the module, allowing for granular control over specific metric types.

```hcl
object({  
    enable    = optional(bool, false)  
    namespace = optional(string, "GitHub Runners")  
    metric = optional(object({  
      enable_github_app_rate_limit    = optional(bool, true)  
      enable_job_retry                = optional(bool, true)  
      enable_spot_termination_warning = optional(bool, true)  
    }), {})  
  })
```

--------------------------------

### Configure idle runners with cron expressions

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Defines the schedule, time zone, and number of idle runners to maintain, along with the instance eviction strategy.

```hcl
idle_config = [{
   cron             = "* * 9-17 * * 1-5"
   timeZone         = "Europe/Amsterdam"
   idleCount        = 2
   # Defaults to 'oldest_first'
   evictionStrategy = "oldest_first"
}]
```

--------------------------------

### GitHub App Input Configuration

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/permissions-boundary

The required structure for the github_app input variable.

```hcl
object({  
    id         = string  
    key_base64 = string  
  })
```

--------------------------------

### Runner Log Files Configuration

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Defines the structure for configuring log files to be sent to CloudWatch.

```hcl
list(object({  
    log_group_name   = string  
    prefix_log_group = bool  
    file_path        = string  
    log_stream_name  = string  
    log_class        = optional(string, "STANDARD")  
  }))
```

--------------------------------

### Metadata Options Configuration

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Default metadata settings for EC2 runner instances.

```hcl
{
  "http_endpoint": "enabled",
  "http_put_response_hop_limit": 1,
  "http_tokens": "required",
  "instance_metadata_tags": "enabled"
}
```

--------------------------------

### Define Block Device Mappings

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Configuration schema for EC2 instance block devices and the default value for a 30GB volume.

```hcl
list(object({
    delete_on_termination      = optional(bool, true)
    device_name                = optional(string, "/dev/xvda")
    encrypted                  = optional(bool, true)
    iops                       = optional(number)
    kms_key_id                 = optional(string)
    snapshot_id                = optional(string)
    throughput                 = optional(number)
    volume_initialization_rate = optional(number)
    volume_size                = number
    volume_type                = optional(string, "gp3")
  }))
```

```json
[
  {
    "volume_size": 30
  }
]
```

--------------------------------

### GitHub App Configuration Object

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Defines the structure for GitHub App authentication, supporting both direct values and SSM parameter references.

```hcl
object({  
    key_base64 = optional(string)  
    key_base64_ssm = optional(object({  
      arn  = string  
      name = string  
    }))  
    id = optional(string)  
    id_ssm = optional(object({  
      arn  = string  
      name = string  
    }))  
    webhook_secret = optional(string)  
    webhook_secret_ssm = optional(object({  
      arn  = string  
      name = string  
    }))  
  })
```

--------------------------------

### Define ssm_housekeeper input

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Configuration schema for the SSM housekeeper lambda function.

```hcl
object({
    schedule_expression = optional(string, "rate(1 day)")
    state               = optional(string, "ENABLED")
    lambda_memory_size  = optional(number, 512)
    lambda_timeout      = optional(number, 60)
    config = object({
      tokenPath      = optional(string)
      minimumDaysOld = optional(number, 1)
      dryRun         = optional(bool, false)
    })
  })
```

```json
{
  "config": {}
}
```

--------------------------------

### Enable and Configure Dynamic Labels

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Configures the runner module to accept dynamic labels and applies a security policy to restrict specific EC2 parameters.

```hcl
module "runners" {
  source = "github-aws-runners/github-runners/aws"

  ...
  enable_dynamic_labels = true
  aws_dynamic_labels_policy = {
    blocked_keys = ["image-id", "subnet-id"]

    restricted_keys = {
      "instance-type" = {
        allowed = ["m5.*", "c5.*"]
        denied  = ["m5.metal"]
      }

      "ebs-volume-size" = {
        max = 200
      }
    }
  }
  ...
}
```

--------------------------------

### Cron expression syntax reference

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Visual representation of the supported cron expression format used for scheduling idle runners.

```text
*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    |
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, optional)
```

--------------------------------

### Configure SSM Housekeeper Lambda

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/multi-runner

Defines the structure for the SSM housekeeper lambda configuration.

```hcl
object({
    schedule_expression = optional(string, "rate(1 day)")
    enabled             = optional(bool, true)
    lambda_memory_size  = optional(number, 512)
    lambda_timeout      = optional(number, 60)
    config = object({
      tokenPath      = optional(string)
      minimumDaysOld = optional(number, 1)
      dryRun         = optional(bool, false)
    })
  })
```

```json
{
  "config": {}
}
```

--------------------------------

### Define sqs_build_queue input

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Structure for the SQS queue used to consume build events.

```hcl
object({
    arn = string
    url = string
  })
```

--------------------------------

### Specify instance type and EBS volume

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration

Overrides default instance settings by specifying a specific instance type and custom EBS volume configuration.

```yaml
jobs:
  build:
    runs-on:
      - self-hosted
      - linux
      - ghr-ec2-instance-type:c5.2xlarge
      - ghr-ec2-ebs-volume-size:200
      - ghr-ec2-ebs-volume-type:gp3
```

--------------------------------

### S3 Runner Binaries Configuration

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Defines the structure for specifying the S3 bucket details for cached GitHub binaries.

```hcl
object({  
    arn = string  
    id  = string  
    key = string  
  })
```

--------------------------------

### Define Multi-Runner Configuration Schema

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/multi-runner

Use this map object structure to define the configuration for multiple runners, including OS, architecture, and scaling parameters.

```hcl
map(object({  
    runner_config = object({  
      runner_os           = string  
      runner_architecture = string  
      runner_metadata_options = optional(map(any), {  
        instance_metadata_tags      = "enabled"  
        http_endpoint               = "enabled"  
        http_tokens                 = "required"  
        http_put_response_hop_limit = 1  
      })  
      ami = optional(object({  
        filter               = optional(map(list(string)), { state = ["available"] })  
        owners               = optional(list(string), ["amazon"])  
        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",  
      ])  
      enable_organization_runners                                    = optional(bool, false)  
      enable_runner_binaries_syncer                                  = optional(bool, true)  
      enable_ssm_on_runners                                          = optional(bool, false)  
      enable_userdata                                                = optional(bool, true)  
      instance_allocation_strategy                                   = optional(string, "lowest-price")  
      instance_type_priorities                                       = optional(map(number), null)  
      instance_max_spot_price                                        = optional(string, null)  
      instance_target_capacity_type                                  = optional(string, "spot")  
      instance_types                                                 = list(string)  
      job_queue_retention_in_seconds                                 = optional(number, 86400)  
      minimum_running_time_in_minutes                                = optional(number, null)  
      pool_runner_owner                                              = optional(string, null)  
      runner_as_root                                                 = optional(bool, false)  
      runner_boot_time_in_minutes                                    = optional(number, 5)  
      runner_disable_default_labels                                  = optional(bool, false)  
      runner_extra_labels                                            = optional(list(string), [])  
      runner_group_name                                              = optional(string, "Default")  
      runner_name_prefix                                             = optional(string, "")  
      runner_run_as                                                  = optional(string, "ec2-user")  
      runners_maximum_count                                          = number  
      runner_additional_security_group_ids                           = optional(list(string), [])  
      scale_down_schedule_expression                                 = optional(string, "cron(_/5 * * * ? _)")  
      scale_up_reserved_concurrent_executions                        = optional(number, 1)  
      lambda_event_source_mapping_batch_size                         = optional(number, null)  
      lambda_event_source_mapping_maximum_batching_window_in_seconds = optional(number, null)  
      userdata_template                                              = optional(string, null)  
      userdata_content                                               = optional(string, null)  
      enable_jit_config                                              = optional(bool, null)  
      enable_runner_detailed_monitoring                              = optional(bool, false)  
      enable_cloudwatch_agent                                        = optional(bool, true)  
      cloudwatch_config                                              = optional(string, null)  
```

--------------------------------

### Configure AMI Housekeeper Cleanup Settings

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/ami-housekeeper

Defines the structure for the cleanup_config object, allowing customization of AMI filters, dry run behavior, and retention policies.

```hcl
object({  
    amiFilters = optional(list(object({  
      Name   = string  
      Values = list(string)  
      })),  
      [{  
        Name : "state",  
        Values : ["available"],  
        },  
        {  
          Name : "image-type",  
          Values : ["machine"],  
      }]  
    )  
    dryRun              = optional(bool, false)  
    launchTemplateNames = optional(list(string))  
    maxItems            = optional(number)  
    minimumDaysOld      = optional(number, 30)  
    ssmParameterNames   = optional(list(string))  
  })
```

--------------------------------

### Configure multi-runner module

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/multi-runner

Defines the multi-runner module with specific configurations for different runner types, including label matchers and instance settings.

```hcl
module "multi-runner" {
  prefix = "multi-runner"

  github_app = {
    # app details
  }

  # Optional: distribute GitHub API rate limit across multiple apps
  # additional_github_apps = [
  #   {
  #     key_base64      = "base64-encoded-private-key"
  #     id              = "123456"
  #     installation_id = "789"  # optional, avoids an API call per invocation
  #   },
  # ]

  multi_runner_config = {
    "linux-arm" = {
      matcherConfig : {
        labelMatchers = [["self-hosted", "linux", "arm64", "arm"]]
        exactMatch    = true
      }
      runner_config = {
        runner_os                      = "linux"
        runner_architecture            = "arm64"
        runner_extra_labels            = "arm"
        enable_ssm_on_runners          = true
        instance_types                 = ["t4g.large", "c6g.large"]
        ...
      }
      ...
    },
    "linux-x64" = {
      matcherConfig : {
        labelMatchers = [["self-hosted", "linux", "x64"]]
        exactMatch    = false
      }
      runner_config = {
        runner_os                       = "linux"
        runner_architecture             = "x64"
        instance_types                  = ["m5ad.large", "m5a.large"]
        enable_ephemeral_runners        = true
        delay_webhook_event = 0
        ...
      }
      ...
    }
  }

}
```

--------------------------------

### Configure additional GitHub Apps

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Defines the structure for additional GitHub Apps to distribute API rate limit usage.

```hcl
list(object({  
    key_base64          = optional(string)  
    key_base64_ssm      = optional(object({ arn = string, name = string }))  
    id                  = optional(string)  
    id_ssm              = optional(object({ arn = string, name = string }))  
    installation_id     = optional(string)  
    installation_id_ssm = optional(object({ arn = string, name = string }))  
  }))
```

--------------------------------

### Pool Configuration Object

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners

Schema for defining pool size adjustments based on schedule expressions.

```hcl
list(object({
    schedule_expression          = string
    schedule_expression_timezone = optional(string)
    size                         = number
  }))
```

--------------------------------

### SSM Housekeeper Configuration Object

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Defines the structure for the SSM housekeeper lambda configuration, including schedule and timeout settings.

```hcl
object({  
    schedule_expression = optional(string, "rate(1 day)")  
    enabled             = optional(bool, true)  
    lambda_memory_size  = optional(number, 512)  
    lambda_timeout      = optional(number, 60)  
    config = object({  
      tokenPath      = optional(string)  
      minimumDaysOld = optional(number, 1)  
      dryRun         = optional(bool, false)  
    })  
  })
```

--------------------------------

### Define host_groups input variable

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/dedicated-mac-hosts

Defines the structure for the host_groups map, specifying instance types and availability zones for Mac hosts.

```hcl
map(object({  
    name               = string  
    host_instance_type = string  
    hosts = list(object({  
      name              = string  
      availability_zone = string  
    }))  
  }))
```

--------------------------------

### Configure Runner Binaries S3 Encryption

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Sets the server-side encryption configuration for the runner-binaries S3 bucket.

```json
{
  "rule": {  
    "apply_server_side_encryption_by_default": {  
      "sse_algorithm": "AES256"  
    }  
  }
}
```

--------------------------------

### Override macOS AMI

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/mac-runners

Demonstrates how to override the default 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"
}
```

--------------------------------

### Configure AMI settings

Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners

Specifies AMI configuration including filters, owners, and SSM parameter overrides.

```hcl
object({  
    filter               = optional(map(list(string)), { state = ["available"] })  
    owners               = optional(list(string), ["amazon"])  
    id_ssm_parameter_arn = optional(string, null)  
    kms_key_arn          = optional(string, null)  
  })
```
Tokens:
Raw