feat: Enterprise-level runners

Author: dmitrykiselev27

README.md

@@ -24,7 +24,7 @@ This [Terraform](https://www.terraform.io/) module creates the required infrastr
 - OS support: Linux (x64/arm64) and Windows
 - Multi-Runner: Create multiple runner configurations with a single deployment
 - GitHub cloud, GitHub Cloud with Data Residency and GitHub Enterprise Server (GHES) support.
-- Org and repo level runners. enterprise level runners are not supported (yet).
+- Org and repo level runners. Enterprise level runners are supported via PAT-based authentication.
 
 
 ## Getting started

docs/examples/enterprise.md

@@ -0,0 +1 @@
+--8<-- "examples/enterprise/README.md"

docs/getting-started.md

@@ -91,7 +91,8 @@ module "github-runner" {
   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
+
+  runner_registration_level = "org"
 }
 ```
 

examples/default/main.tf

@@ -50,8 +50,8 @@ module "runners" {
   # runner_binaries_syncer_lambda_zip = "../lambdas-download/runner-binaries-syncer.zip"
   # runners_lambda_zip                = "../lambdas-download/runners.zip"
 
-  enable_organization_runners = true
-  runner_extra_labels         = ["default", "example"]
+  runner_registration_level = "org"
+  runner_extra_labels       = ["default", "example"]
 
   # enable access to the runners via SSM
   enable_ssm_on_runners = true

examples/enterprise/README.md

@@ -0,0 +1,82 @@
+# Enterprise Runner Example
+
+This example demonstrates how to deploy GitHub self-hosted runners at the **Enterprise level** using PAT-based authentication.
+
+## Prerequisites
+
+1. **GitHub Enterprise Account** — You need a GitHub Enterprise Cloud account with admin access.
+2. **Enterprise PAT** — Create one or more Personal Access Tokens with the `manage_runners:enterprise` scope:
+   - Go to your GitHub account settings → Developer settings → Personal access tokens (classic)
+   - Create a new token with the `manage_runners:enterprise` scope
+   - Save the token securely — you'll need it for the `enterprise_pat` variable
+   - **Tip**: To distribute API calls and avoid rate limiting, create multiple PATs (from different accounts if possible) and provide them as a comma-separated string. The Lambda functions will randomly select one PAT per invocation.
+3. **Enterprise Webhook** — Configure an enterprise-level webhook to send `workflow_job` events to the module's webhook endpoint. Choose a random secret for the webhook — you'll need it for the `webhook_secret` parameter.
+
+> **Note**: Enterprise runners do **not** require a GitHub App. Only a webhook secret is needed to verify incoming webhook payloads. The PAT handles all GitHub API interactions.
+
+## Configuration
+
+```hcl
+module "runners" {
+  source = "../../"
+
+  # Enterprise runner registration
+  runner_registration_level = "enterprise"
+  enterprise_slug           = "my-enterprise"
+
+  # Enterprise PAT — stored in AWS SSM Parameter Store as SecureString
+  # Single PAT:
+  enterprise_pat = {
+    pat = var.enterprise_pat
+  }
+
+  # Multiple PATs (comma-separated) for rate limit distribution:
+  # enterprise_pat = {
+  #   pat = "ghp_token1,ghp_token2,ghp_token3"
+  # }
+
+  # No GitHub App is required for enterprise runners.
+  # Only the webhook_secret is needed to verify incoming webhook payloads.
+  github_app = {
+    webhook_secret = random_id.random.hex
+  }
+
+  # ... other configuration
+}
+```
+
+## Variables
+
+| Name | Description | Type | Required |
+|------|-------------|------|----------|
+| `enterprise_slug` | The slug of the GitHub Enterprise account | string | Yes |
+| `enterprise_pat` | PAT with `manage_runners:enterprise` scope | string (sensitive) | Yes |
+| `environment` | Environment name prefix | string | No |
+| `aws_region` | AWS region for deployment | string | No |
+
+The `github_app` block only requires `webhook_secret` — the `key_base64` and `id` fields are **not** needed for enterprise runners.
+
+## Verification
+
+After deployment:
+
+1. Check the webhook endpoint in the Terraform outputs
+2. Configure the enterprise webhook to point to the endpoint
+3. Trigger a workflow run in any repository under the enterprise
+4. Verify runners appear in **Enterprise Settings → Actions → Runners**
+
+## Migration from Organization Runners
+
+If you're migrating from organization-level runners:
+
+```hcl
+# Before
+enable_organization_runners = true
+
+# After
+runner_registration_level = "enterprise"
+enterprise_slug           = "my-enterprise"
+enterprise_pat = {
+  pat = var.enterprise_pat
+}
+```

examples/enterprise/main.tf

@@ -0,0 +1,61 @@
+locals {
+  environment = var.environment != null ? var.environment : "enterprise"
+  aws_region  = var.aws_region
+}
+
+resource "random_id" "random" {
+  byte_length = 20
+}
+
+module "base" {
+  source = "../base"
+
+  prefix     = local.environment
+  aws_region = local.aws_region
+}
+
+module "runners" {
+  source                          = "../../"
+  create_service_linked_role_spot = true
+  aws_region                      = local.aws_region
+  vpc_id                          = module.base.vpc.vpc_id
+  subnet_ids                      = module.base.vpc.private_subnets
+
+  prefix = local.environment
+  tags = {
+    Project = "Enterprise Runners"
+  }
+
+  # Enterprise runners do not require a GitHub App.
+  # Only the webhook_secret is needed to verify incoming webhook payloads.
+  github_app = {
+    webhook_secret = random_id.random.hex
+  }
+
+  # Enterprise runner registration level
+  runner_registration_level = "enterprise"
+  enterprise_slug           = var.enterprise_slug
+
+  # Enterprise PAT for authentication
+  enterprise_pat = {
+    pat = var.enterprise_pat
+  }
+
+  # Runner labels
+  runner_extra_labels = ["enterprise", "example"]
+
+  # enable access to the runners via SSM
+  enable_ssm_on_runners = true
+
+  instance_types = ["m7a.large", "m5.large"]
+
+  # override delay of events in seconds
+  delay_webhook_event   = 5
+  runners_maximum_count = 5
+
+  # override scaling down
+  scale_down_schedule_expression = "cron(* * * * ? *)"
+
+  enable_user_data_debug_logging_runner = true
+}
+

examples/enterprise/outputs.tf

@@ -0,0 +1,15 @@
+output "runners" {
+  value = {
+    lambda_syncer_name = module.runners.binaries_syncer.lambda.function_name
+  }
+}
+
+output "webhook_endpoint" {
+  value = module.runners.webhook.endpoint
+}
+
+output "webhook_secret" {
+  sensitive = true
+  value     = random_id.random.hex
+}
+

examples/enterprise/providers.tf

@@ -0,0 +1,10 @@
+provider "aws" {
+  region = local.aws_region
+
+  default_tags {
+    tags = {
+      Example = local.environment
+    }
+  }
+}
+

examples/enterprise/variables.tf

@@ -0,0 +1,23 @@
+variable "enterprise_slug" {
+  description = "The slug of the GitHub Enterprise account. Example: 'my-enterprise'."
+  type        = string
+}
+
+variable "enterprise_pat" {
+  description = "Personal Access Token with 'manage_runners:enterprise' scope for enterprise runner management."
+  type        = string
+  sensitive   = true
+}
+
+variable "environment" {
+  description = "Environment name, used as prefix."
+  type        = string
+  default     = null
+}
+
+variable "aws_region" {
+  description = "AWS region."
+  type        = string
+  default     = "eu-west-1"
+}
+

examples/enterprise/versions.tf

@@ -0,0 +1,18 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 6.21"
+    }
+    local = {
+      source  = "hashicorp/local"
+      version = "~> 2.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "~> 3.0"
+    }
+  }
+  required_version = ">= 1.3.0"
+}
+