@cloudsnorkel/cdk-github-runners 0.15.0 → 0.15.1

package/.jsii

@@ -8501,7 +8501,7 @@
     "stability": "experimental"
   },
   "homepage": "https://github.com/CloudSnorkel/cdk-github-runners.git",
-  "jsiiVersion": "5.9.31 (build 550e607)",
+  "jsiiVersion": "5.9.33 (build 8ebb533)",
   "keywords": [
     "aws",
     "aws-cdk",
@@ -8525,7 +8525,7 @@
   },
   "name": "@cloudsnorkel/cdk-github-runners",
   "readme": {
-    "markdown": "# GitHub Self-Hosted Runners CDK Constructs\n\n[![NPM](https://img.shields.io/npm/v/@cloudsnorkel/cdk-github-runners?label=npm&logo=npm)][7]\n[![PyPI](https://img.shields.io/pypi/v/cloudsnorkel.cdk-github-runners?label=pypi&logo=pypi)][6]\n[![Maven Central](https://img.shields.io/maven-central/v/com.cloudsnorkel/cdk.github.runners.svg?label=Maven%20Central&logo=apachemaven)][8]\n[![Go](https://img.shields.io/github/v/tag/CloudSnorkel/cdk-github-runners?color=red&label=go&logo=go)][11]\n[![Nuget](https://img.shields.io/nuget/v/CloudSnorkel.Cdk.Github.Runners?color=red&&logo=nuget)][12]\n[![Release](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml/badge.svg)](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml)\n[![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)][20]\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)\n\nUse this CDK construct to create ephemeral [self-hosted GitHub runners][1] on-demand inside your AWS account.\n\n* 🧩 Easy to configure GitHub integration with a web-based interface\n* 🧠 Customizable runners with decent defaults\n* 🏃🏻 Multiple runner configurations controlled by labels\n* 🔐 Everything fully hosted in your account\n* 🔃 Automatically updated build environment with latest runner version\n\nSelf-hosted runners in AWS are useful when:\n\n* You need easy access to internal resources in your actions\n* You want to pre-install some software for your actions\n* You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials][2] has more security controls)\n* You are using GitHub Enterprise Server\n\nEphemeral (or on-demand) runners are the [recommended way by GitHub][14] for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.\n\n## Table of Contents\n\n- [API](#api)\n- [Providers](#providers)\n- [Installation](#installation)\n- [Customizing](#customizing)\n  - [Composite Providers](#composite-providers)\n  - [Custom Provider Selection](#custom-provider-selection)\n  - [Warm Runners](#warm-runners)\n- [Examples](#examples)\n- [Architecture](#architecture)\n- [Troubleshooting](#troubleshooting)\n- [Monitoring](#monitoring)\n- [Getting Help](#getting-help)\n- [Contributing](#contributing)\n- [Sponsors](#sponsors)\n- [Other Options](#other-options)\n\n## API\n\nThe best way to browse API documentation is on [Constructs Hub][13]. It is available in all supported programming languages.\n\n## Providers\n\nA runner provider creates compute resources on-demand and uses [actions/runner][5] to start a runner.\n\n|                  | EC2               | CodeBuild                  | Fargate        | ECS            | Lambda        |\n|------------------|-------------------|----------------------------|----------------|----------------|---------------|\n| **Time limit**   | Unlimited         | 8 hours                    | Unlimited      | Unlimited      | 15 minutes    |\n| **vCPUs**        | Unlimited         | 2, 4, 8, or 72             | 0.25 to 4      | Unlimited      | 1 to 6        |\n| **RAM**          | Unlimited         | 3gb, 7gb, 15gb, or 145gb   | 512mb to 30gb  | Unlimited      | 128mb to 10gb |\n| **Storage**      | Unlimited         | 50gb to 824gb              | 20gb to 200gb  | Unlimited      | Up to 10gb    |\n| **Architecture** | x86_64, ARM64     | x86_64, ARM64              | x86_64, ARM64  | x86_64, ARM64  | x86_64, ARM64 |\n| **sudo**         | ✔                 | ✔                         | ✔              | ✔              | ❌           |\n| **Docker**       | ✔                 | ✔ (Linux only)            | ❌              | ✔              | ❌           |\n| **Spot pricing** | ✔                 | ❌                         | ✔              | ✔              | ❌           |\n| **OS**           | Linux, Windows    | Linux, Windows             | Linux, Windows | Linux, Windows | Linux         |\n\nThe best provider to use mostly depends on your current infrastructure. When in doubt, CodeBuild is always a good choice. Execution history and logs are easy to view, and it has no restrictive limits unless you need to run for more than 8 hours.\n\n* EC2 is useful when you want runners to have complete access to the host\n* ECS is useful when you want to control the infrastructure, like leaving the runner host running for faster startups\n* Lambda is useful for short jobs that can work within time, size and readonly system constraints\n\nYou can also create your own provider by implementing `IRunnerProvider`.\n\n## Installation\n\n1. Install and use the appropriate package\n   <details><summary>Python</summary>\n\n   ### Install\n   Available on [PyPI][6].\n   ```bash\n   pip install cloudsnorkel.cdk-github-runners\n   ```\n   ### Use\n   ```python\n   from aws_cdk import App, Stack\n   from cloudsnorkel.cdk_github_runners import GitHubRunners\n\n   app = App()\n   stack = Stack(app, \"github-runners\")\n   GitHubRunners(stack, \"runners\")\n\n   app.synth()\n   ```\n   </details>\n   <details><summary>TypeScript or JavaScript</summary>\n\n   ### Install\n   Available on [npm][7].\n   ```bash\n   npm i @cloudsnorkel/cdk-github-runners\n   ```\n   ### Use\n   ```typescript\n   import { App, Stack } from 'aws-cdk-lib';\n   import { GitHubRunners } from '@cloudsnorkel/cdk-github-runners';\n\n   const app = new App();\n   const stack = new Stack(app, 'github-runners');\n   new GitHubRunners(stack, 'runners');\n\n   app.synth();\n   ```\n   </details>\n   <details><summary>Java</summary>\n\n   ### Install\n   Available on [Maven][8].\n   ```xml\n   <dependency>\n      <groupId>com.cloudsnorkel</groupId>\n      <artifactId>cdk.github.runners</artifactId>\n   </dependency>\n   ```\n   ### Use\n   ```java\n   import software.amazon.awscdk.App;\n   import software.amazon.awscdk.Stack;\n   import com.cloudsnorkel.cdk.github.runners.GitHubRunners;\n\n   public class Example {\n     public static void main(String[] args){\n       App app = new App();\n       Stack stack = new Stack(app, \"github-runners\");\n       GitHubRunners.Builder.create(stack, \"runners\").build();\n\n       app.synth();\n     }\n   }\n   ```\n   </details>\n   <details><summary>Go</summary>\n\n   ### Install\n   Available on [GitHub][11].\n   ```bash\n   go get github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\n   ```\n   ### Use\n   ```go\n   package main\n\n   import (\n     \"github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\"\n     \"github.com/aws/aws-cdk-go/awscdk/v2\"\n     \"github.com/aws/jsii-runtime-go\"\n   )\n\n   func main() {\n     app := awscdk.NewApp(nil)\n     stack := awscdk.NewStack(app, jsii.String(\"github-runners\"), &awscdk.StackProps{})\n     cloudsnorkelcdkgithubrunners.NewGitHubRunners(stack, jsii.String(\"runners\"), &cloudsnorkelcdkgithubrunners.GitHubRunnersProps{})\n\n     app.Synth(nil)\n   }\n   ```\n   </details>\n   <details><summary>.NET</summary>\n\n   ### Install\n   Available on [Nuget][12].\n   ```bash\n   dotnet add package CloudSnorkel.Cdk.Github.Runners\n   ```\n   ### Use\n   ```csharp\n   using Amazon.CDK;\n   using CloudSnorkel;\n\n   namespace Example\n   {\n     sealed class Program\n     {\n       public static void Main(string[] args)\n       {\n         var app = new App();\n         var stack = new Stack(app, \"github-runners\");\n         new GitHubRunners(stack, \"runners\");\n         app.Synth();\n       }\n     }\n   }\n   ```\n   </details>\n2. Use `GitHubRunners` construct in your code (starting with default arguments is fine)\n3. Deploy your stack\n4. Look for the status command output similar to `aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json`\n   ```\n    ✅  github-runners-test\n\n   ✨  Deployment time: 260.01s\n\n   Outputs:\n   github-runners-test.runnersstatuscommand4A30F0F5 = aws --region us-east-1 lambda invoke --function-name github-runners-test-runnersstatus1A5771C0-mvttg8oPQnQS status.json\n   ```\n5. Execute the status command (you may need to specify `--profile` too) and open the resulting `status.json` file\n6. Open the URL in `github.setup.url` from `status.json` or [manually setup GitHub](SETUP_GITHUB.md) integration as an app or with personal access token\n7. Run status command again to confirm `github.auth.status` and `github.webhook.status` are OK\n8. Trigger a GitHub action that has a `self-hosted` label with `runs-on: [self-hosted, codebuild]` (or non-default labels you set in step 2)\n9. If the action is not successful, see [troubleshooting](#Troubleshooting)\n\n[![Demo](demo-thumbnail.jpg)](https://youtu.be/wlyv_3V8lIw)\n\n## Customizing\n\nThe default providers configured by `GitHubRunners` are useful for testing but probably not too much for actual production work. They run in the default VPC or no VPC and have no added IAM permissions. You would usually want to configure the providers yourself.\n\nFor example:\n\n```typescript\nlet vpc: ec2.Vpc;\nlet runnerSg: ec2.SecurityGroup;\nlet dbSg: ec2.SecurityGroup;\nlet bucket: s3.Bucket;\n\n// create a custom CodeBuild provider\nconst myProvider = new CodeBuildRunnerProvider(this, 'codebuild runner', {\n   labels: ['my-codebuild'],\n   vpc: vpc,\n   securityGroups: [runnerSg],\n});\n// grant some permissions to the provider\nbucket.grantReadWrite(myProvider);\ndbSg.connections.allowFrom(runnerSg, ec2.Port.tcp(3306), 'allow runners to connect to MySQL database');\n\n// create the runner infrastructure\nnew GitHubRunners(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nAnother way to customize runners is by modifying the image used to spin them up. The image contains the [runner][5], any required dependencies, and integration code with the provider. You may choose to customize this image by adding more packages, for example.\n\n```typescript\nconst myBuilder = FargateRunnerProvider.imageBuilder(this, 'image builder');\nmyBuilder.addComponent(\n  RunnerImageComponent.custom({ commands: ['apt install -y nginx xz-utils'] }),\n);\n\nconst myProvider = new FargateRunnerProvider(this, 'fargate runner', {\n   labels: ['customized-fargate'],\n   imageBuilder: myBuilder,\n});\n\n// create the runner infrastructure\nnew GitHubRunners(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nYour workflow will then look like:\n\n```yaml\nname: self-hosted example\non: push\njobs:\n  self-hosted:\n    runs-on: [self-hosted, customized-fargate]\n    steps:\n      - run: echo hello world\n```\n\nWindows images can also be customized the same way.\n\n```typescript\nconst myWindowsBuilder = FargateRunnerProvider.imageBuilder(this, 'Windows image builder', {\n   architecture: Architecture.X86_64,\n   os: Os.WINDOWS,\n});\nmyWindowsBuilder.addComponent(\n   RunnerImageComponent.custom({\n     name: 'Ninja',\n     commands: [\n       'Invoke-WebRequest -UseBasicParsing -Uri \"https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-win.zip\" -OutFile ninja.zip',\n       'Expand-Archive ninja.zip -DestinationPath C:\\\\actions',\n       'del ninja.zip',\n     ],\n   }),\n);\n\nconst myProvider = new FargateRunnerProvider(this, 'fargate runner', {\n   labels: ['customized-windows-fargate'],\n   imageBuilder: myWindowsBuilder,\n});\n\nnew GitHubRunners(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nThe runner OS and architecture is determined by the image it is set to use. For example, to create a Fargate runner provider for ARM64 set the `architecture` property for the image builder to `Architecture.ARM64` in the image builder properties.\n\n```typescript\nnew GitHubRunners(this, 'runners', {\n   providers: [\n      new FargateRunnerProvider(this, 'fargate runner', {\n         labels: ['arm64', 'fargate'],\n         imageBuilder: FargateRunnerProvider.imageBuilder(this, 'image builder', {\n            architecture: Architecture.ARM64,\n            os: Os.LINUX_UBUNTU,\n         }),\n      }),\n   ],\n});\n```\n\n### Composite Providers\n\nComposite providers allow you to combine multiple runner providers with different strategies. There are two types:\n\n**Fallback Strategy**: Try providers in order until one succeeds. Useful for trying spot instances first, then falling back to on-demand if spot capacity is unavailable.\n\n```typescript\n// Try spot instances first, fall back to on-demand if spot is unavailable\nconst ecsFallback = CompositeProvider.fallback(this, 'ECS Fallback', [\n  new EcsRunnerProvider(this, 'ECS Spot', {\n    labels: ['ecs', 'linux', 'x64'],\n    spot: true,\n    // ... other config\n  }),\n  new EcsRunnerProvider(this, 'ECS On-Demand', {\n    labels: ['ecs', 'linux', 'x64'],\n    spot: false,\n    // ... other config\n  }),\n]);\n\nnew GitHubRunners(this, 'runners', {\n  providers: [ecsFallback],\n});\n```\n\n**Weighted Distribution Strategy**: Randomly select a provider based on weights. Useful for distributing load across multiple availability zones or instance types.\n\n```typescript\n// Distribute 60% of traffic to AZ-1, 40% to AZ-2\nconst distributedProvider = CompositeProvider.distribute(this, 'Fargate Distribution', [\n  {\n    weight: 3, // 3/(3+2) = 60%\n    provider: new FargateRunnerProvider(this, 'Fargate AZ-1', {\n      labels: ['fargate', 'linux', 'x64'],\n      subnetSelection: vpc.selectSubnets({\n        availabilityZones: [vpc.availabilityZones[0]],\n      }),\n      // ... other config\n    }),\n  },\n  {\n    weight: 2, // 2/(3+2) = 40%\n    provider: new FargateRunnerProvider(this, 'Fargate AZ-2', {\n      labels: ['fargate', 'linux', 'x64'],\n      subnetSelection: vpc.selectSubnets({\n        availabilityZones: [vpc.availabilityZones[1]],\n      }),\n      // ... other config\n    }),\n  },\n]);\n\nnew GitHubRunners(this, 'runners', {\n  providers: [distributedProvider],\n});\n```\n\n**Important**: All providers in a composite must have the exact same labels. This ensures any provisioned runner can match the labels requested by the GitHub workflow job.\n\n### Custom Provider Selection\n\nBy default, providers are selected based on label matching: the first provider that has all the labels requested by the job is selected. You can customize this behavior using a provider selector Lambda function to:\n\n* Filter out certain jobs (prevent runner provisioning)\n* Dynamically select a provider based on job characteristics (repository, branch, time of day, etc.)\n* Customize labels for the runner (add, remove, or modify labels dynamically)\n\nThe selector function receives the full GitHub webhook payload, a map of all available providers and their labels, and the default provider/labels that would have been selected. It returns the provider to use (or `undefined` to skip runner creation) and the labels to assign to the runner.\n\n**Example: Route jobs to different providers based on repository**\n\n```typescript\nimport { ComputeType } from 'aws-cdk-lib/aws-codebuild';\nimport { Function, Code, Runtime } from 'aws-cdk-lib/aws-lambda';\nimport { GitHubRunners, CodeBuildRunnerProvider } from '@cloudsnorkel/cdk-github-runners';\n\nconst defaultProvider = new CodeBuildRunnerProvider(this, 'default', {\n  labels: ['custom-runner', 'default'],\n});\nconst productionProvider = new CodeBuildRunnerProvider(this, 'production', {\n  labels: ['custom-runner', 'production'],\n  computeType: ComputeType.LARGE,\n});\n\nconst providerSelector = new Function(this, 'provider-selector', {\n  runtime: Runtime.NODEJS_LATEST,\n  handler: 'index.handler',\n  code: Code.fromInline(`\n    exports.handler = async (event) => {\n      const { payload, providers, defaultProvider, defaultLabels } = event;\n\n      // Route production repos to dedicated provider\n      if (payload.repository.name.includes('prod')) {\n        return {\n          provider: '${productionProvider.node.path}',\n          labels: ['custom-runner', 'production', 'modified-via-selector'],\n        };\n      }\n\n      // Filter out draft PRs\n      if (payload.workflow_job.head_branch?.startsWith('draft/')) {\n        return { provider: undefined }; // Skip runner provisioning\n      }\n\n      // Use default for everything else\n      return {\n        provider: defaultProvider,\n        labels: defaultLabels,\n      };\n    };\n  `),\n});\n\nnew GitHubRunners(this, 'runners', {\n   providers: [defaultProvider, productionProvider],\n   providerSelector: providerSelector,\n});\n```\n\n**Example: Add dynamic labels based on job metadata**\n\n```typescript\nconst providerSelector = new Function(this, 'provider-selector', {\n  runtime: Runtime.NODEJS_LATEST,\n  handler: 'index.handler',\n  code: Code.fromInline(`\n    exports.handler = async (event) => {\n      const { payload, defaultProvider, defaultLabels } = event;\n\n      // Add branch name as a label\n      const branch = payload.workflow_job.head_branch || 'unknown';\n      const labels = [...(defaultLabels || []), 'branch:' + branch];\n\n      return {\n        provider: defaultProvider,\n        labels: labels,\n      };\n    };\n  `),\n});\n```\n\n**Important considerations:**\n\n* ⚠️ **Label matching responsibility**: You are responsible for ensuring the selected provider's labels match what the job requires. If labels don't match, the runner will be provisioned but GitHub Actions won't assign the job to it.\n* ⚠️ **No guarantee of assignment**: Provider selection only determines which provider will provision a runner. GitHub Actions may still route the job to any available runner with matching labels. For reliable provider assignment, consider repo-level runner registration (the default).\n* ⚡ **Performance**: The selector runs synchronously during webhook processing. Keep it fast and efficient—the webhook has a 30-second timeout total.\n\n### Warm Runners\n\nWarm runners are pre-provisioned and stay idle until a job arrives, reducing startup latency. Use `AlwaysOnWarmRunner` for 24/7 pools or `ScheduledWarmRunner` for time-windowed pools. You specify the provider directly.\n\n```typescript\nimport { AlwaysOnWarmRunner, CodeBuildRunnerProvider, GitHubRunners } from '@cloudsnorkel/cdk-github-runners';\n\nconst provider = new CodeBuildRunnerProvider(this, 'provider', { labels: ['codebuild', 'linux'] });\nconst runners = new GitHubRunners(this, 'runners', { providers: [provider] });\n\nnew AlwaysOnWarmRunner(this, 'warm', {\n  runners,\n  provider,\n  count: 2,\n  owner: 'my-org',\n  repo: 'my-repo',\n});\n```\n\nWarm runner pools can be stacked. If you want 2 warm runners always available but 3 during peak work hours, you can create one pool with 2 runners always on and another pool with 1 runner during work hours.\n\n```typescript\nimport { aws_events as events, Duration } from 'aws-cdk-lib';\nimport { AlwaysOnWarmRunner, ScheduledWarmRunner, CodeBuildRunnerProvider, GitHubRunners } from '@cloudsnorkel/cdk-github-runners';\n\nconst provider = new CodeBuildRunnerProvider(this, 'provider', { labels: ['codebuild', 'linux'] });\nconst runners = new GitHubRunners(this, 'runners', { providers: [provider] });\n\nnew AlwaysOnWarmRunner(this, 'warm', {\n  runners,\n  provider,\n  count: 2,\n  owner: 'my-org',\n  repo: 'my-repo',\n});\n\nnew ScheduledWarmRunner(this, 'work hours warm', {\n  runners,\n  provider,\n  count: 1,\n  owner: 'my-org',\n  repo: 'my-repo',\n  schedule: events.Schedule.cron({ hour: '13', minute: '0', weekDay: 'MON-FRI' }),\n  duration: Duration.hours(2),\n});\n```\n\nSee the [warm-runners example](examples/typescript/warm-runners/) for a complete setup.\n\n## Examples\n\nWe provide comprehensive examples in the [`examples/`](examples/) folder to help you get started quickly:\n\n### Getting Started\n- **[Simple CodeBuild](examples/typescript/simple-codebuild/)** - Basic setup with just a CodeBuild provider (also available in [Python](examples/python/simple-codebuild/))\n- **[Warm Runners](examples/typescript/warm-runners/)** - Pre-provisioned runners for low-latency job starts (also available in [Python](examples/python/warm-runners/))\n\n### Provider Configuration\n- **[Composite Provider](examples/typescript/composite-provider/)** - Fallback and weighted distribution strategies (also available in [Python](examples/python/composite-provider/))\n- **[Provider Selector](examples/typescript/provider-selector/)** - Custom provider selection with Lambda function (also available in [Python](examples/python/provider-selector/))\n- **[EC2 Windows Provider](examples/typescript/ec2-windows-provider/)** - EC2 configuration for Windows runners (also available in [Python](examples/python/ec2-windows-provider/))\n- **[Split Stacks](examples/typescript/split-stacks/)** - Split image builders and providers across multiple stacks (also available in [Python](examples/python/split-stacks/))\n\n### Compute & Performance\n- **[Compute Options](examples/typescript/compute-options/)** - Configure CPU, memory, and instance types for different providers (also available in [Python](examples/python/compute-options/))\n- **[Spot Instances](examples/typescript/spot-instances/)** - Use spot instances for cost savings across EC2, Fargate, and ECS (also available in [Python](examples/python/spot-instances/))\n- **[Storage Options](examples/typescript/storage-options/)** - Custom EBS storage options for EC2 runners (also available in [Python](examples/python/storage-options/))\n- **[ECS Scaling](examples/typescript/ecs-scaling/)** - Custom autoscaling group scaling policies for ECS providers (also available in [Python](examples/python/ecs-scaling/))\n\n### Security & Access\n- **[IAM Permissions](examples/typescript/iam-permissions/)** - Grant AWS IAM permissions to runners (also available in [Python](examples/python/iam-permissions/))\n- **[Network Access](examples/typescript/network-access/)** - Configure network access with VPCs and security groups (also available in [Python](examples/python/network-access/))\n- **[Access Control](examples/typescript/access-control/)** - Configure access control for webhook and setup functions (also available in [Python](examples/python/access-control/))\n\n### Customization\n- **[Add Software](examples/typescript/add-software/)** - Add custom software to runner images (also available in [Python](examples/python/add-software/))\n- **[GPU](examples/typescript/gpu/)** - GPU support with NVIDIA drivers across EC2, CodeBuild, and ECS (also available in [Python](examples/python/gpu/))\n\n### Enterprise & Monitoring\n- **[GHES](examples/typescript/ghes/)** - Configure runners for GitHub Enterprise Server (also available in [Python](examples/python/ghes/))\n- **[Monitoring](examples/typescript/monitoring/)** - Set up CloudWatch alarms and SNS notifications (also available in [Python](examples/python/monitoring/))\n\nEach example is self-contained with its own dependencies and README. Start with the simple examples and work your way up to more advanced configurations.\n\nAnother good and very full example is the [integration test](test/default.integ.ts).\n\nIf you have more to share, please open a PR adding examples to the `examples` folder.\n\n## Architecture\n\n![Architecture diagram](architecture.svg)\n\n## Troubleshooting\n\nRunners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. Configuration issue related errors like pointing to a missing AMI will not be retried. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.\n\n1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK\n2. Make sure `runs-on` in the workflow matches the expected labels set in the runner provider\n3. Diagnose relevant executions of the orchestrator step function by visiting the URL in `troubleshooting.stepFunctionUrl` from `status.json`\n   1. If the execution failed, check your runner provider configuration for errors\n   2. If the execution is still running for a long time, check the execution events to see why runner starting is being retried\n   3. If there are no relevant executions, move to the next step\n4. Confirm the webhook Lambda was called by visiting the URL in `troubleshooting.webhookHandlerUrl` from `status.json`\n   1. If it's not called or logs errors, confirm the webhook settings on the GitHub side\n   2. If you see too many errors, make sure you're only sending `workflow_job` events\n5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`\n\nAll logs are saved in CloudWatch.\n* Log group names can be found in `status.json` for each provider, image builder, and other parts of the system\n* Some useful Logs Insights queries can be enabled with `GitHubRunners.createLogsInsightsQueries()`\n\nTo get `status.json`, check out the CloudFormation stack output for a command that generates it. The command looks like:\n\n```\naws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json\n```\n\n## Monitoring\n\nThere are two important ways to monitor your runners:\n\n1. Make sure runners don't fail to start. When that happens, jobs may sit and wait. Use `GitHubRunners.metricFailed()` to get a metric for the number of failed runner starts. You should use this metric to trigger an alarm.\n2. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.\n\nOther useful metrics to track:\n\n1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.\n2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.\n\n## Getting Help\n\nNeed help? We're here for you!\n\n* 💬 **GitHub Discussions**: Ask questions, share ideas, or get help from the community by opening a [discussion][18]\n* 🐛 **GitHub Issues**: Report bugs or request features by opening an [issue][16]\n* 💬 **Discord**: Join our [Discord community][20] for real-time help and discussions\n\n## Contributing\n\nIf you use and love this project, please consider contributing.\n\n1. 🪳 If you see something, say something. [Issues][16] help improve the quality of the project.\n   * Include relevant logs and package versions for bugs.\n   * When possible, describe the use-case behind feature requests.\n1. 🛠️ [Pull requests][17] are welcome.\n   * Run `npm run build` before submitting to make sure all tests pass.\n   * Allow edits from maintainers so small adjustments can be made easily.\n1. 💵 Consider [sponsoring][15] the project to show your support and optionally get your name listed below.\n\n## Sponsors\n\nThanks to our generous sponsors who helped make this project possible!\n\n<table>\n  <tr>\n    <td align=\"center\">\n      <a href=\"https://github.com/threat-down\">\n        <img src=\"https://github.com/threat-down.png?size=100\" width=\"100\" height=\"100\" alt=\"ThreatDown\" />\n        <br />\n        <sub><b>ThreatDown</b></sub>\n      </a>\n    </td>\n    <td align=\"center\">\n      <a href=\"https://github.com/magicbell\">\n        <img src=\"https://github.com/magicbell.png?size=100\" width=\"100\" height=\"100\" alt=\"MagicBell\" />\n        <br />\n        <sub><b>MagicBell</b></sub>\n      </a>\n    </td>\n    <td align=\"center\">\n      <a href=\"https://github.com/fragment-dev\">\n        <img src=\"https://github.com/fragment-dev.png?size=100\" width=\"100\" height=\"100\" alt=\"Fragment\" />\n        <br />\n        <sub><b>Fragment</b></sub>\n      </a>\n    </td>\n    <td align=\"center\">\n      <a href=\"https://github.com/andresionek91\">\n        <img src=\"https://github.com/andresionek91.png?size=100\" width=\"100\" height=\"100\" alt=\"Andre Sionek\" />\n        <br />\n        <sub><b>Andre Sionek</b></sub>\n      </a>\n    </td>\n  </tr>\n</table>\n\n## Other Options\n\n1. [github-aws-runners/terraform-aws-github-runner][3] if you're using Terraform\n2. [actions/actions-runner-controller][4] if you're using Kubernetes\n\n\n[1]: https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners\n[2]: https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions\n[3]: https://github.com/github-aws-runners/terraform-aws-github-runner\n[4]: https://github.com/actions/actions-runner-controller\n[5]: https://github.com/actions/runner\n[6]: https://pypi.org/project/cloudsnorkel.cdk-github-runners\n[7]: https://www.npmjs.com/package/@cloudsnorkel/cdk-github-runners\n[8]: https://central.sonatype.com/artifact/com.cloudsnorkel/cdk.github.runners/\n[9]: https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps\n[10]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token\n[11]: https://pkg.go.dev/github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\n[12]: https://www.nuget.org/packages/CloudSnorkel.Cdk.Github.Runners/\n[13]: https://constructs.dev/packages/@cloudsnorkel/cdk-github-runners/\n[14]: https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling\n[15]: https://github.com/sponsors/CloudSnorkel\n[16]: https://github.com/CloudSnorkel/cdk-github-runners/issues\n[17]: https://github.com/CloudSnorkel/cdk-github-runners/pulls\n[18]: https://github.com/CloudSnorkel/cdk-github-runners/discussions\n[20]: https://discord.gg/vdrTUTqQKv\n"
+    "markdown": "# GitHub Self-Hosted Runners CDK Constructs\n\n[![NPM](https://img.shields.io/npm/v/@cloudsnorkel/cdk-github-runners?label=npm&logo=npm)][7]\n[![PyPI](https://img.shields.io/pypi/v/cloudsnorkel.cdk-github-runners?label=pypi&logo=pypi)][6]\n[![Maven Central](https://img.shields.io/maven-central/v/com.cloudsnorkel/cdk.github.runners.svg?label=Maven%20Central&logo=apachemaven)][8]\n[![Go](https://img.shields.io/github/v/tag/CloudSnorkel/cdk-github-runners?color=red&label=go&logo=go)][11]\n[![Nuget](https://img.shields.io/nuget/v/CloudSnorkel.Cdk.Github.Runners?color=red&&logo=nuget)][12]\n[![Release](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml/badge.svg)](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml)\n[![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)][20]\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)\n\nUse this CDK construct to create ephemeral [self-hosted GitHub runners][1] on-demand inside your AWS account.\n\n* 🧩 Easy to configure GitHub integration with a web-based interface\n* 🧠 Customizable runners with decent defaults\n* 🏃🏻 Multiple runner configurations controlled by labels\n* 🔐 Everything fully hosted in your account\n* 🔃 Automatically updated build environment with latest runner version\n\nSelf-hosted runners in AWS are useful when:\n\n* You need easy access to internal resources in your actions\n* You want to pre-install some software for your actions\n* You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials][2] has more security controls)\n* You are using GitHub Enterprise Server\n\nEphemeral (or on-demand) runners are the [recommended way by GitHub][14] for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.\n\n## Table of Contents\n\n- [API](#api)\n- [Providers](#providers)\n- [Installation](#installation)\n- [Customizing](#customizing)\n  - [Composite Providers](#composite-providers)\n  - [Custom Provider Selection](#custom-provider-selection)\n  - [Warm Runners](#warm-runners)\n- [Examples](#examples)\n- [Architecture](#architecture)\n- [Troubleshooting](#troubleshooting)\n- [Monitoring](#monitoring)\n- [Getting Help](#getting-help)\n- [Contributing](#contributing)\n- [Sponsors](#sponsors)\n- [Other Options](#other-options)\n\n## API\n\nThe best way to browse API documentation is on [Constructs Hub][13]. It is available in all supported programming languages.\n\n## Providers\n\nA runner provider creates compute resources on-demand and uses [actions/runner][5] to start a runner.\n\n|                  | EC2               | CodeBuild                  | Fargate        | ECS            | Lambda        |\n|------------------|-------------------|----------------------------|----------------|----------------|---------------|\n| **Time limit**   | Unlimited         | 36 hours (default 1 hour)  | Unlimited      | Unlimited      | 15 minutes    |\n| **vCPUs**        | Unlimited         | 2, 4, 8, or 72             | 0.25 to 4      | Unlimited      | 1 to 6        |\n| **RAM**          | Unlimited         | 3gb, 7gb, 15gb, or 145gb   | 512mb to 30gb  | Unlimited      | 128mb to 10gb |\n| **Storage**      | Unlimited         | 50gb to 824gb              | 20gb to 200gb  | Unlimited      | Up to 10gb    |\n| **Architecture** | x86_64, ARM64     | x86_64, ARM64              | x86_64, ARM64  | x86_64, ARM64  | x86_64, ARM64 |\n| **sudo**         | ✔                 | ✔                         | ✔              | ✔              | ❌           |\n| **Docker**       | ✔                 | ✔ (Linux only)            | ❌              | ✔              | ❌           |\n| **Spot pricing** | ✔                 | ❌                         | ✔              | ✔              | ❌           |\n| **OS**           | Linux, Windows    | Linux, Windows             | Linux, Windows | Linux, Windows | Linux         |\n\nThe best provider to use mostly depends on your current infrastructure. When in doubt, CodeBuild is always a good choice. Execution history and logs are easy to view, and it has no restrictive limits unless you need to run for more than 8 hours.\n\n* EC2 is useful when you want runners to have complete access to the host\n* ECS is useful when you want to control the infrastructure, like leaving the runner host running for faster startups\n* Lambda is useful for short jobs that can work within time, size and readonly system constraints\n\nYou can also create your own provider by implementing `IRunnerProvider`.\n\n## Installation\n\n1. Install and use the appropriate package\n   <details><summary>Python</summary>\n\n   ### Install\n   Available on [PyPI][6].\n   ```bash\n   pip install cloudsnorkel.cdk-github-runners\n   ```\n   ### Use\n   ```python\n   from aws_cdk import App, Stack\n   from cloudsnorkel.cdk_github_runners import GitHubRunners\n\n   app = App()\n   stack = Stack(app, \"github-runners\")\n   GitHubRunners(stack, \"runners\")\n\n   app.synth()\n   ```\n   </details>\n   <details><summary>TypeScript or JavaScript</summary>\n\n   ### Install\n   Available on [npm][7].\n   ```bash\n   npm i @cloudsnorkel/cdk-github-runners\n   ```\n   ### Use\n   ```typescript\n   import { App, Stack } from 'aws-cdk-lib';\n   import { GitHubRunners } from '@cloudsnorkel/cdk-github-runners';\n\n   const app = new App();\n   const stack = new Stack(app, 'github-runners');\n   new GitHubRunners(stack, 'runners');\n\n   app.synth();\n   ```\n   </details>\n   <details><summary>Java</summary>\n\n   ### Install\n   Available on [Maven][8].\n   ```xml\n   <dependency>\n      <groupId>com.cloudsnorkel</groupId>\n      <artifactId>cdk.github.runners</artifactId>\n   </dependency>\n   ```\n   ### Use\n   ```java\n   import software.amazon.awscdk.App;\n   import software.amazon.awscdk.Stack;\n   import com.cloudsnorkel.cdk.github.runners.GitHubRunners;\n\n   public class Example {\n     public static void main(String[] args){\n       App app = new App();\n       Stack stack = new Stack(app, \"github-runners\");\n       GitHubRunners.Builder.create(stack, \"runners\").build();\n\n       app.synth();\n     }\n   }\n   ```\n   </details>\n   <details><summary>Go</summary>\n\n   ### Install\n   Available on [GitHub][11].\n   ```bash\n   go get github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\n   ```\n   ### Use\n   ```go\n   package main\n\n   import (\n     \"github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\"\n     \"github.com/aws/aws-cdk-go/awscdk/v2\"\n     \"github.com/aws/jsii-runtime-go\"\n   )\n\n   func main() {\n     app := awscdk.NewApp(nil)\n     stack := awscdk.NewStack(app, jsii.String(\"github-runners\"), &awscdk.StackProps{})\n     cloudsnorkelcdkgithubrunners.NewGitHubRunners(stack, jsii.String(\"runners\"), &cloudsnorkelcdkgithubrunners.GitHubRunnersProps{})\n\n     app.Synth(nil)\n   }\n   ```\n   </details>\n   <details><summary>.NET</summary>\n\n   ### Install\n   Available on [Nuget][12].\n   ```bash\n   dotnet add package CloudSnorkel.Cdk.Github.Runners\n   ```\n   ### Use\n   ```csharp\n   using Amazon.CDK;\n   using CloudSnorkel;\n\n   namespace Example\n   {\n     sealed class Program\n     {\n       public static void Main(string[] args)\n       {\n         var app = new App();\n         var stack = new Stack(app, \"github-runners\");\n         new GitHubRunners(stack, \"runners\");\n         app.Synth();\n       }\n     }\n   }\n   ```\n   </details>\n2. Use `GitHubRunners` construct in your code (starting with default arguments is fine)\n3. Deploy your stack\n4. Look for the status command output similar to `aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json`\n   ```\n    ✅  github-runners-test\n\n   ✨  Deployment time: 260.01s\n\n   Outputs:\n   github-runners-test.runnersstatuscommand4A30F0F5 = aws --region us-east-1 lambda invoke --function-name github-runners-test-runnersstatus1A5771C0-mvttg8oPQnQS status.json\n   ```\n5. Execute the status command (you may need to specify `--profile` too) and open the resulting `status.json` file\n6. Open the URL in `github.setup.url` from `status.json` or [manually setup GitHub](SETUP_GITHUB.md) integration as an app or with personal access token\n7. Run status command again to confirm `github.auth.status` and `github.webhook.status` are OK\n8. Trigger a GitHub action that has a `self-hosted` label with `runs-on: [self-hosted, codebuild]` (or non-default labels you set in step 2)\n9. If the action is not successful, see [troubleshooting](#Troubleshooting)\n\n[![Demo](demo-thumbnail.jpg)](https://youtu.be/wlyv_3V8lIw)\n\n## Customizing\n\nThe default providers configured by `GitHubRunners` are useful for testing but probably not too much for actual production work. They run in the default VPC or no VPC and have no added IAM permissions. You would usually want to configure the providers yourself.\n\nFor example:\n\n```typescript\nlet vpc: ec2.Vpc;\nlet runnerSg: ec2.SecurityGroup;\nlet dbSg: ec2.SecurityGroup;\nlet bucket: s3.Bucket;\n\n// create a custom CodeBuild provider\nconst myProvider = new CodeBuildRunnerProvider(this, 'codebuild runner', {\n   labels: ['my-codebuild'],\n   vpc: vpc,\n   securityGroups: [runnerSg],\n});\n// grant some permissions to the provider\nbucket.grantReadWrite(myProvider);\ndbSg.connections.allowFrom(runnerSg, ec2.Port.tcp(3306), 'allow runners to connect to MySQL database');\n\n// create the runner infrastructure\nnew GitHubRunners(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nAnother way to customize runners is by modifying the image used to spin them up. The image contains the [runner][5], any required dependencies, and integration code with the provider. You may choose to customize this image by adding more packages, for example.\n\n```typescript\nconst myBuilder = FargateRunnerProvider.imageBuilder(this, 'image builder');\nmyBuilder.addComponent(\n  RunnerImageComponent.custom({ commands: ['apt install -y nginx xz-utils'] }),\n);\n\nconst myProvider = new FargateRunnerProvider(this, 'fargate runner', {\n   labels: ['customized-fargate'],\n   imageBuilder: myBuilder,\n});\n\n// create the runner infrastructure\nnew GitHubRunners(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nYour workflow will then look like:\n\n```yaml\nname: self-hosted example\non: push\njobs:\n  self-hosted:\n    runs-on: [self-hosted, customized-fargate]\n    steps:\n      - run: echo hello world\n```\n\nWindows images can also be customized the same way.\n\n```typescript\nconst myWindowsBuilder = FargateRunnerProvider.imageBuilder(this, 'Windows image builder', {\n   architecture: Architecture.X86_64,\n   os: Os.WINDOWS,\n});\nmyWindowsBuilder.addComponent(\n   RunnerImageComponent.custom({\n     name: 'Ninja',\n     commands: [\n       'Invoke-WebRequest -UseBasicParsing -Uri \"https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-win.zip\" -OutFile ninja.zip',\n       'Expand-Archive ninja.zip -DestinationPath C:\\\\actions',\n       'del ninja.zip',\n     ],\n   }),\n);\n\nconst myProvider = new FargateRunnerProvider(this, 'fargate runner', {\n   labels: ['customized-windows-fargate'],\n   imageBuilder: myWindowsBuilder,\n});\n\nnew GitHubRunners(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nThe runner OS and architecture is determined by the image it is set to use. For example, to create a Fargate runner provider for ARM64 set the `architecture` property for the image builder to `Architecture.ARM64` in the image builder properties.\n\n```typescript\nnew GitHubRunners(this, 'runners', {\n   providers: [\n      new FargateRunnerProvider(this, 'fargate runner', {\n         labels: ['arm64', 'fargate'],\n         imageBuilder: FargateRunnerProvider.imageBuilder(this, 'image builder', {\n            architecture: Architecture.ARM64,\n            os: Os.LINUX_UBUNTU,\n         }),\n      }),\n   ],\n});\n```\n\n### Composite Providers\n\nComposite providers allow you to combine multiple runner providers with different strategies. There are two types:\n\n**Fallback Strategy**: Try providers in order until one succeeds. Useful for trying spot instances first, then falling back to on-demand if spot capacity is unavailable.\n\n```typescript\n// Try spot instances first, fall back to on-demand if spot is unavailable\nconst ecsFallback = CompositeProvider.fallback(this, 'ECS Fallback', [\n  new EcsRunnerProvider(this, 'ECS Spot', {\n    labels: ['ecs', 'linux', 'x64'],\n    spot: true,\n    // ... other config\n  }),\n  new EcsRunnerProvider(this, 'ECS On-Demand', {\n    labels: ['ecs', 'linux', 'x64'],\n    spot: false,\n    // ... other config\n  }),\n]);\n\nnew GitHubRunners(this, 'runners', {\n  providers: [ecsFallback],\n});\n```\n\n**Weighted Distribution Strategy**: Randomly select a provider based on weights. Useful for distributing load across multiple availability zones or instance types.\n\n```typescript\n// Distribute 60% of traffic to AZ-1, 40% to AZ-2\nconst distributedProvider = CompositeProvider.distribute(this, 'Fargate Distribution', [\n  {\n    weight: 3, // 3/(3+2) = 60%\n    provider: new FargateRunnerProvider(this, 'Fargate AZ-1', {\n      labels: ['fargate', 'linux', 'x64'],\n      subnetSelection: vpc.selectSubnets({\n        availabilityZones: [vpc.availabilityZones[0]],\n      }),\n      // ... other config\n    }),\n  },\n  {\n    weight: 2, // 2/(3+2) = 40%\n    provider: new FargateRunnerProvider(this, 'Fargate AZ-2', {\n      labels: ['fargate', 'linux', 'x64'],\n      subnetSelection: vpc.selectSubnets({\n        availabilityZones: [vpc.availabilityZones[1]],\n      }),\n      // ... other config\n    }),\n  },\n]);\n\nnew GitHubRunners(this, 'runners', {\n  providers: [distributedProvider],\n});\n```\n\n**Important**: All providers in a composite must have the exact same labels. This ensures any provisioned runner can match the labels requested by the GitHub workflow job.\n\n### Custom Provider Selection\n\nBy default, providers are selected based on label matching: the first provider that has all the labels requested by the job is selected. You can customize this behavior using a provider selector Lambda function to:\n\n* Filter out certain jobs (prevent runner provisioning)\n* Dynamically select a provider based on job characteristics (repository, branch, time of day, etc.)\n* Customize labels for the runner (add, remove, or modify labels dynamically)\n\nThe selector function receives the full GitHub webhook payload, a map of all available providers and their labels, and the default provider/labels that would have been selected. It returns the provider to use (or `undefined` to skip runner creation) and the labels to assign to the runner.\n\n**Example: Route jobs to different providers based on repository**\n\n```typescript\nimport { ComputeType } from 'aws-cdk-lib/aws-codebuild';\nimport { Function, Code, Runtime } from 'aws-cdk-lib/aws-lambda';\nimport { GitHubRunners, CodeBuildRunnerProvider } from '@cloudsnorkel/cdk-github-runners';\n\nconst defaultProvider = new CodeBuildRunnerProvider(this, 'default', {\n  labels: ['custom-runner', 'default'],\n});\nconst productionProvider = new CodeBuildRunnerProvider(this, 'production', {\n  labels: ['custom-runner', 'production'],\n  computeType: ComputeType.LARGE,\n});\n\nconst providerSelector = new Function(this, 'provider-selector', {\n  runtime: Runtime.NODEJS_LATEST,\n  handler: 'index.handler',\n  code: Code.fromInline(`\n    exports.handler = async (event) => {\n      const { payload, providers, defaultProvider, defaultLabels } = event;\n\n      // Route production repos to dedicated provider\n      if (payload.repository.name.includes('prod')) {\n        return {\n          provider: '${productionProvider.node.path}',\n          labels: ['custom-runner', 'production', 'modified-via-selector'],\n        };\n      }\n\n      // Filter out draft PRs\n      if (payload.workflow_job.head_branch?.startsWith('draft/')) {\n        return { provider: undefined }; // Skip runner provisioning\n      }\n\n      // Use default for everything else\n      return {\n        provider: defaultProvider,\n        labels: defaultLabels,\n      };\n    };\n  `),\n});\n\nnew GitHubRunners(this, 'runners', {\n   providers: [defaultProvider, productionProvider],\n   providerSelector: providerSelector,\n});\n```\n\n**Example: Add dynamic labels based on job metadata**\n\n```typescript\nconst providerSelector = new Function(this, 'provider-selector', {\n  runtime: Runtime.NODEJS_LATEST,\n  handler: 'index.handler',\n  code: Code.fromInline(`\n    exports.handler = async (event) => {\n      const { payload, defaultProvider, defaultLabels } = event;\n\n      // Add branch name as a label\n      const branch = payload.workflow_job.head_branch || 'unknown';\n      const labels = [...(defaultLabels || []), 'branch:' + branch];\n\n      return {\n        provider: defaultProvider,\n        labels: labels,\n      };\n    };\n  `),\n});\n```\n\n**Important considerations:**\n\n* ⚠️ **Label matching responsibility**: You are responsible for ensuring the selected provider's labels match what the job requires. If labels don't match, the runner will be provisioned but GitHub Actions won't assign the job to it.\n* ⚠️ **No guarantee of assignment**: Provider selection only determines which provider will provision a runner. GitHub Actions may still route the job to any available runner with matching labels. For reliable provider assignment, consider repo-level runner registration (the default).\n* ⚡ **Performance**: The selector runs synchronously during webhook processing. Keep it fast and efficient—the webhook has a 30-second timeout total.\n\n### Warm Runners\n\nWarm runners are pre-provisioned and stay idle until a job arrives, reducing startup latency. Use `AlwaysOnWarmRunner` for 24/7 pools or `ScheduledWarmRunner` for time-windowed pools. You specify the provider directly.\n\n```typescript\nimport { AlwaysOnWarmRunner, CodeBuildRunnerProvider, GitHubRunners } from '@cloudsnorkel/cdk-github-runners';\n\nconst provider = new CodeBuildRunnerProvider(this, 'provider', { labels: ['codebuild', 'linux'] });\nconst runners = new GitHubRunners(this, 'runners', { providers: [provider] });\n\nnew AlwaysOnWarmRunner(this, 'warm', {\n  runners,\n  provider,\n  count: 2,\n  owner: 'my-org',\n  repo: 'my-repo',\n});\n```\n\nWarm runner pools can be stacked. If you want 2 warm runners always available but 3 during peak work hours, you can create one pool with 2 runners always on and another pool with 1 runner during work hours.\n\n```typescript\nimport { aws_events as events, Duration } from 'aws-cdk-lib';\nimport { AlwaysOnWarmRunner, ScheduledWarmRunner, CodeBuildRunnerProvider, GitHubRunners } from '@cloudsnorkel/cdk-github-runners';\n\nconst provider = new CodeBuildRunnerProvider(this, 'provider', { labels: ['codebuild', 'linux'] });\nconst runners = new GitHubRunners(this, 'runners', { providers: [provider] });\n\nnew AlwaysOnWarmRunner(this, 'warm', {\n  runners,\n  provider,\n  count: 2,\n  owner: 'my-org',\n  repo: 'my-repo',\n});\n\nnew ScheduledWarmRunner(this, 'work hours warm', {\n  runners,\n  provider,\n  count: 1,\n  owner: 'my-org',\n  repo: 'my-repo',\n  schedule: events.Schedule.cron({ hour: '13', minute: '0', weekDay: 'MON-FRI' }),\n  duration: Duration.hours(2),\n});\n```\n\nSee the [warm-runners example](examples/typescript/warm-runners/) for a complete setup.\n\n## Examples\n\nWe provide comprehensive examples in the [`examples/`](examples/) folder to help you get started quickly:\n\n### Getting Started\n- **[Simple CodeBuild](examples/typescript/simple-codebuild/)** - Basic setup with just a CodeBuild provider (also available in [Python](examples/python/simple-codebuild/))\n- **[Warm Runners](examples/typescript/warm-runners/)** - Pre-provisioned runners for low-latency job starts (also available in [Python](examples/python/warm-runners/))\n\n### Provider Configuration\n- **[Composite Provider](examples/typescript/composite-provider/)** - Fallback and weighted distribution strategies (also available in [Python](examples/python/composite-provider/))\n- **[Provider Selector](examples/typescript/provider-selector/)** - Custom provider selection with Lambda function (also available in [Python](examples/python/provider-selector/))\n- **[EC2 Windows Provider](examples/typescript/ec2-windows-provider/)** - EC2 configuration for Windows runners (also available in [Python](examples/python/ec2-windows-provider/))\n- **[Split Stacks](examples/typescript/split-stacks/)** - Split image builders and providers across multiple stacks (also available in [Python](examples/python/split-stacks/))\n\n### Compute & Performance\n- **[Compute Options](examples/typescript/compute-options/)** - Configure CPU, memory, and instance types for different providers (also available in [Python](examples/python/compute-options/))\n- **[Spot Instances](examples/typescript/spot-instances/)** - Use spot instances for cost savings across EC2, Fargate, and ECS (also available in [Python](examples/python/spot-instances/))\n- **[Storage Options](examples/typescript/storage-options/)** - Custom EBS storage options for EC2 runners (also available in [Python](examples/python/storage-options/))\n- **[ECS Scaling](examples/typescript/ecs-scaling/)** - Custom autoscaling group scaling policies for ECS providers (also available in [Python](examples/python/ecs-scaling/))\n\n### Security & Access\n- **[IAM Permissions](examples/typescript/iam-permissions/)** - Grant AWS IAM permissions to runners (also available in [Python](examples/python/iam-permissions/))\n- **[Network Access](examples/typescript/network-access/)** - Configure network access with VPCs and security groups (also available in [Python](examples/python/network-access/))\n- **[Access Control](examples/typescript/access-control/)** - Configure access control for webhook and setup functions (also available in [Python](examples/python/access-control/))\n\n### Customization\n- **[Add Software](examples/typescript/add-software/)** - Add custom software to runner images (also available in [Python](examples/python/add-software/))\n- **[GPU](examples/typescript/gpu/)** - GPU support with NVIDIA drivers across EC2, CodeBuild, and ECS (also available in [Python](examples/python/gpu/))\n\n### Enterprise & Monitoring\n- **[GHES](examples/typescript/ghes/)** - Configure runners for GitHub Enterprise Server (also available in [Python](examples/python/ghes/))\n- **[Monitoring](examples/typescript/monitoring/)** - Set up CloudWatch alarms and SNS notifications (also available in [Python](examples/python/monitoring/))\n\nEach example is self-contained with its own dependencies and README. Start with the simple examples and work your way up to more advanced configurations.\n\nAnother good and very full example is the [integration test](test/default.integ.ts).\n\nIf you have more to share, please open a PR adding examples to the `examples` folder.\n\n## Architecture\n\n![Architecture diagram](architecture.svg)\n\n## Troubleshooting\n\nRunners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. Configuration issue related errors like pointing to a missing AMI will not be retried. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.\n\n1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK\n2. Make sure `runs-on` in the workflow matches the expected labels set in the runner provider\n3. Diagnose relevant executions of the orchestrator step function by visiting the URL in `troubleshooting.stepFunctionUrl` from `status.json`\n   1. If the execution failed, check your runner provider configuration for errors\n   2. If the execution is still running for a long time, check the execution events to see why runner starting is being retried\n   3. If there are no relevant executions, move to the next step\n4. Confirm the webhook Lambda was called by visiting the URL in `troubleshooting.webhookHandlerUrl` from `status.json`\n   1. If it's not called or logs errors, confirm the webhook settings on the GitHub side\n   2. If you see too many errors, make sure you're only sending `workflow_job` events\n5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`\n\nAll logs are saved in CloudWatch.\n* Log group names can be found in `status.json` for each provider, image builder, and other parts of the system\n* Some useful Logs Insights queries can be enabled with `GitHubRunners.createLogsInsightsQueries()`\n\nTo get `status.json`, check out the CloudFormation stack output for a command that generates it. The command looks like:\n\n```\naws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json\n```\n\n## Monitoring\n\nThere are two important ways to monitor your runners:\n\n1. Make sure runners don't fail to start. When that happens, jobs may sit and wait. Use `GitHubRunners.metricFailed()` to get a metric for the number of failed runner starts. You should use this metric to trigger an alarm.\n2. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.\n\nOther useful metrics to track:\n\n1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.\n2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.\n\n## Getting Help\n\nNeed help? We're here for you!\n\n* 💬 **GitHub Discussions**: Ask questions, share ideas, or get help from the community by opening a [discussion][18]\n* 🐛 **GitHub Issues**: Report bugs or request features by opening an [issue][16]\n* 💬 **Discord**: Join our [Discord community][20] for real-time help and discussions\n\n## Contributing\n\nIf you use and love this project, please consider contributing.\n\n1. 🪳 If you see something, say something. [Issues][16] help improve the quality of the project.\n   * Include relevant logs and package versions for bugs.\n   * When possible, describe the use-case behind feature requests.\n1. 🛠️ [Pull requests][17] are welcome.\n   * Run `npm run build` before submitting to make sure all tests pass.\n   * Allow edits from maintainers so small adjustments can be made easily.\n1. 💵 Consider [sponsoring][15] the project to show your support and optionally get your name listed below.\n\n## Sponsors\n\nThanks to our generous sponsors who helped make this project possible!\n\n<table>\n  <tr>\n    <td align=\"center\">\n      <a href=\"https://github.com/threat-down\">\n        <img src=\"https://github.com/threat-down.png?size=100\" width=\"100\" height=\"100\" alt=\"ThreatDown\" />\n        <br />\n        <sub><b>ThreatDown</b></sub>\n      </a>\n    </td>\n    <td align=\"center\">\n      <a href=\"https://github.com/magicbell\">\n        <img src=\"https://github.com/magicbell.png?size=100\" width=\"100\" height=\"100\" alt=\"MagicBell\" />\n        <br />\n        <sub><b>MagicBell</b></sub>\n      </a>\n    </td>\n    <td align=\"center\">\n      <a href=\"https://github.com/fragment-dev\">\n        <img src=\"https://github.com/fragment-dev.png?size=100\" width=\"100\" height=\"100\" alt=\"Fragment\" />\n        <br />\n        <sub><b>Fragment</b></sub>\n      </a>\n    </td>\n    <td align=\"center\">\n      <a href=\"https://github.com/andresionek91\">\n        <img src=\"https://github.com/andresionek91.png?size=100\" width=\"100\" height=\"100\" alt=\"Andre Sionek\" />\n        <br />\n        <sub><b>Andre Sionek</b></sub>\n      </a>\n    </td>\n  </tr>\n</table>\n\n## Other Options\n\n1. [github-aws-runners/terraform-aws-github-runner][3] if you're using Terraform\n2. [actions/actions-runner-controller][4] if you're using Kubernetes\n\n\n[1]: https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners\n[2]: https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions\n[3]: https://github.com/github-aws-runners/terraform-aws-github-runner\n[4]: https://github.com/actions/actions-runner-controller\n[5]: https://github.com/actions/runner\n[6]: https://pypi.org/project/cloudsnorkel.cdk-github-runners\n[7]: https://www.npmjs.com/package/@cloudsnorkel/cdk-github-runners\n[8]: https://central.sonatype.com/artifact/com.cloudsnorkel/cdk.github.runners/\n[9]: https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps\n[10]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token\n[11]: https://pkg.go.dev/github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\n[12]: https://www.nuget.org/packages/CloudSnorkel.Cdk.Github.Runners/\n[13]: https://constructs.dev/packages/@cloudsnorkel/cdk-github-runners/\n[14]: https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling\n[15]: https://github.com/sponsors/CloudSnorkel\n[16]: https://github.com/CloudSnorkel/cdk-github-runners/issues\n[17]: https://github.com/CloudSnorkel/cdk-github-runners/pulls\n[18]: https://github.com/CloudSnorkel/cdk-github-runners/discussions\n[20]: https://discord.gg/vdrTUTqQKv\n"
   },
   "repository": {
     "type": "git",
@@ -8560,8 +8560,8 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "base": "constructs.Construct",
       "docs": {
-        "example": "new AlwaysOnWarmRunner(stack, 'AlwaysOnLinux', {\n  runners,\n  provider: myProvider,\n  count: 3,\n  owner: 'my-org',\n  repo: 'my-repo',\n});",
-        "remarks": "Runners will be provisioned using the specified provider and registered in the specified repository or organization.\n\nRegistration level must match the one selected during setup. See {@link SETUP_GITHUB.md } for more information on the selection.\n\n## Limitations\n\n- Jobs will still trigger provisioning of on-demand runners, even if a warm runner ends up being used.\n- You may briefly see more than `count` runners when changing config or at rotation.\n- To remove: set `count` to 0, deploy, wait for warm runners to stop, then remove and deploy again.\n  If you don't follow this procedure, warm runners may linger until they expire.\n- Provider failures or timeouts (like Lambda provider timing out after 15 minutes) will result in a\n  gap in coverage until the retry succeeds. Current retry mechanism has built-in back-off rate and\n  can be tweaked using `retryOptions`. This will be improved in the future.",
+        "remarks": "Runners will be provisioned using the specified provider and registered in the specified repository or organization.\n\nRegistration level must match the one selected during setup.",
+        "see": "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md\n\n## Limitations\n\n- Jobs will still trigger provisioning of on-demand runners, even if a warm runner ends up being used.\n- You may briefly see more than `count` runners when changing config or at rotation.\n- To remove: set `count` to 0, deploy, wait for warm runners to stop, then remove and deploy again.\nIf you don't follow this procedure, warm runners may linger until they expire.\n- Provider failures or timeouts (like Lambda provider timing out after 15 minutes) will result in a\ngap in coverage until the retry succeeds. Current retry mechanism has built-in back-off rate and\ncan be tweaked using `retryOptions`. This will be improved in the future.\n\n```typescript\nnew AlwaysOnWarmRunner(stack, 'AlwaysOnLinux', {\nrunners,\nprovider: myProvider,\ncount: 3,\nowner: 'my-org',\nrepo: 'my-repo',\n});\n```",
         "stability": "experimental",
         "summary": "Warm runners that run 24/7. Fills at midnight UTC and each runner stays alive for 24 hours."
       },
@@ -8572,7 +8572,7 @@
         },
         "locationInModule": {
           "filename": "src/warm-runner.ts",
-          "line": 166
+          "line": 170
         },
         "parameters": [
           {
@@ -8598,7 +8598,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/warm-runner.ts",
-        "line": 159
+        "line": 163
       },
       "name": "AlwaysOnWarmRunner",
       "symbolId": "src/warm-runner:AlwaysOnWarmRunner"
@@ -8614,7 +8614,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/warm-runner.ts",
-        "line": 58
+        "line": 59
       },
       "name": "AlwaysOnWarmRunnerProps",
       "properties": [
@@ -8696,14 +8696,15 @@
           "abstract": true,
           "docs": {
             "default": "'repo'",
-            "remarks": "Choose\n'org' for org-wide runners, 'repo' for repo-level. See the setup wizard or\n{@link SETUP_GITHUB.md } for choosing repo vs org.",
+            "remarks": "Choose\n'org' for org-wide runners, 'repo' for repo-level. See the setup wizard for choosing repo vs org.",
+            "see": "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md",
             "stability": "experimental",
             "summary": "Registration level — must match how your runners are set up in GitHub."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/warm-runner.ts",
-            "line": 47
+            "line": 48
           },
           "name": "registrationLevel",
           "optional": true,
@@ -8721,7 +8722,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/warm-runner.ts",
-            "line": 52
+            "line": 53
           },
           "name": "repo",
           "optional": true,
@@ -10980,7 +10981,7 @@
               },
               "name": "parameters",
               "type": {
-                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
+                "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters"
               }
             }
           ],
@@ -11017,7 +11018,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 613
+            "line": 677
           },
           "name": "labelsFromProperties",
           "parameters": [
@@ -11084,6 +11085,28 @@
               "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus"
             }
           }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Override to inject static strings into `$.consts` on the orchestrator state machine."
+          },
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 673
+          },
+          "name": "stepFunctionConstants",
+          "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
+          "returns": {
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "primitive": "string"
+                },
+                "kind": "map"
+              }
+            }
+          }
         }
       ],
       "name": "CodeBuildRunnerProvider",
@@ -11522,7 +11545,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/composite.ts",
-        "line": 24
+        "line": 31
       },
       "methods": [
         {
@@ -11533,7 +11556,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/composite.ts",
-            "line": 66
+            "line": 73
           },
           "name": "distribute",
           "parameters": [
@@ -11585,7 +11608,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/composite.ts",
-            "line": 41
+            "line": 48
           },
           "name": "fallback",
           "parameters": [
@@ -12319,7 +12342,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/ec2.ts",
-          "line": 398
+          "line": 414
         },
         "parameters": [
           {
@@ -12346,7 +12369,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/ec2.ts",
-        "line": 655
+        "line": 679
       },
       "name": "Ec2Runner",
       "symbolId": "src/providers/ec2:Ec2Runner"
@@ -12366,7 +12389,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/ec2.ts",
-          "line": 398
+          "line": 414
         },
         "parameters": [
           {
@@ -12396,7 +12419,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/ec2.ts",
-        "line": 323
+        "line": 339
       },
       "methods": [
         {
@@ -12407,7 +12430,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 343
+            "line": 359
           },
           "name": "imageBuilder",
           "parameters": [
@@ -12446,7 +12469,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 464
+            "line": 493
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -12457,7 +12480,7 @@
               },
               "name": "parameters",
               "type": {
-                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
+                "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters"
               }
             }
           ],
@@ -12475,7 +12498,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 594
+            "line": 618
           },
           "name": "grantStateMachine",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -12494,7 +12517,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 613
+            "line": 677
           },
           "name": "labelsFromProperties",
           "parameters": [
@@ -12544,7 +12567,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 624
+            "line": 648
           },
           "name": "status",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -12561,6 +12584,28 @@
               "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus"
             }
           }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Override to inject static strings into `$.consts` on the orchestrator state machine."
+          },
+          "locationInModule": {
+            "filename": "src/providers/ec2.ts",
+            "line": 481
+          },
+          "name": "stepFunctionConstants",
+          "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
+          "returns": {
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "primitive": "string"
+                },
+                "kind": "map"
+              }
+            }
+          }
         }
       ],
       "name": "Ec2RunnerProvider",
@@ -12573,7 +12618,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 647
+            "line": 671
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -12589,7 +12634,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 370
+            "line": 386
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -12605,7 +12650,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 365
+            "line": 381
           },
           "name": "labels",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -12627,7 +12672,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 377
+            "line": 393
           },
           "name": "logGroup",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -12643,7 +12688,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 379
+            "line": 395
           },
           "name": "retryableErrors",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -12673,7 +12718,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/ec2.ts",
-        "line": 200
+        "line": 216
       },
       "name": "Ec2RunnerProviderProps",
       "properties": [
@@ -12686,7 +12731,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 213
+            "line": 229
           },
           "name": "amiBuilder",
           "optional": true,
@@ -12705,7 +12750,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 238
+            "line": 254
           },
           "name": "group",
           "optional": true,
@@ -12724,7 +12769,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 208
+            "line": 224
           },
           "name": "imageBuilder",
           "optional": true,
@@ -12743,7 +12788,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 250
+            "line": 266
           },
           "name": "instanceType",
           "optional": true,
@@ -12762,7 +12807,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 224
+            "line": 240
           },
           "name": "labels",
           "optional": true,
@@ -12786,7 +12831,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 271
+            "line": 287
           },
           "name": "securityGroup",
           "optional": true,
@@ -12804,7 +12849,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 278
+            "line": 294
           },
           "name": "securityGroups",
           "optional": true,
@@ -12828,7 +12873,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 308
+            "line": 324
           },
           "name": "spot",
           "optional": true,
@@ -12846,7 +12891,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 315
+            "line": 331
           },
           "name": "spotMaxPrice",
           "optional": true,
@@ -12863,7 +12908,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 262
+            "line": 278
           },
           "name": "storageOptions",
           "optional": true,
@@ -12882,7 +12927,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 257
+            "line": 273
           },
           "name": "storageSize",
           "optional": true,
@@ -12901,7 +12946,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 287
+            "line": 303
           },
           "name": "subnet",
           "optional": true,
@@ -12920,7 +12965,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 301
+            "line": 317
           },
           "name": "subnetSelection",
           "optional": true,
@@ -12938,7 +12983,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 294
+            "line": 310
           },
           "name": "vpc",
           "optional": true,
@@ -13055,7 +13100,7 @@
               },
               "name": "parameters",
               "type": {
-                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
+                "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters"
               }
             }
           ],
@@ -13092,7 +13137,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 613
+            "line": 677
           },
           "name": "labelsFromProperties",
           "parameters": [
@@ -13159,6 +13204,28 @@
               "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus"
             }
           }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Override to inject static strings into `$.consts` on the orchestrator state machine."
+          },
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 673
+          },
+          "name": "stepFunctionConstants",
+          "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
+          "returns": {
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "primitive": "string"
+                },
+                "kind": "map"
+              }
+            }
+          }
         }
       ],
       "name": "EcsRunnerProvider",
@@ -13754,7 +13821,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/fargate.ts",
-          "line": 363
+          "line": 364
         },
         "parameters": [
           {
@@ -13781,7 +13848,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/fargate.ts",
-        "line": 549
+        "line": 554
       },
       "name": "FargateRunner",
       "symbolId": "src/providers/fargate:FargateRunner"
@@ -13801,7 +13868,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/fargate.ts",
-          "line": 363
+          "line": 364
         },
         "parameters": [
           {
@@ -13831,7 +13898,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/fargate.ts",
-        "line": 221
+        "line": 222
       },
       "methods": [
         {
@@ -13842,7 +13909,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 261
+            "line": 262
           },
           "name": "imageBuilder",
           "parameters": [
@@ -13881,7 +13948,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 452
+            "line": 457
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -13892,7 +13959,7 @@
               },
               "name": "parameters",
               "type": {
-                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
+                "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters"
               }
             }
           ],
@@ -13910,7 +13977,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 523
+            "line": 528
           },
           "name": "grantStateMachine",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -13929,7 +13996,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 613
+            "line": 677
           },
           "name": "labelsFromProperties",
           "parameters": [
@@ -13979,7 +14046,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 526
+            "line": 531
           },
           "name": "status",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -13996,6 +14063,28 @@
               "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus"
             }
           }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Override to inject static strings into `$.consts` on the orchestrator state machine."
+          },
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 673
+          },
+          "name": "stepFunctionConstants",
+          "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
+          "returns": {
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "primitive": "string"
+                },
+                "kind": "map"
+              }
+            }
+          }
         }
       ],
       "name": "FargateRunnerProvider",
@@ -14011,7 +14100,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 242
+            "line": 243
           },
           "name": "LINUX_ARM64_DOCKERFILE_PATH",
           "static": true,
@@ -14030,7 +14119,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 231
+            "line": 232
           },
           "name": "LINUX_X64_DOCKERFILE_PATH",
           "static": true,
@@ -14047,7 +14136,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 320
+            "line": 321
           },
           "name": "assignPublicIp",
           "type": {
@@ -14062,7 +14151,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 280
+            "line": 281
           },
           "name": "cluster",
           "type": {
@@ -14077,7 +14166,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 330
+            "line": 331
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -14094,7 +14183,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 294
+            "line": 295
           },
           "name": "container",
           "type": {
@@ -14109,7 +14198,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 325
+            "line": 326
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -14127,7 +14216,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 344
+            "line": 345
           },
           "name": "image",
           "type": {
@@ -14142,7 +14231,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 299
+            "line": 300
           },
           "name": "labels",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -14164,7 +14253,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 351
+            "line": 352
           },
           "name": "logGroup",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -14180,7 +14269,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 353
+            "line": 354
           },
           "name": "retryableErrors",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -14202,7 +14291,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 337
+            "line": 338
           },
           "name": "spot",
           "type": {
@@ -14218,7 +14307,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 287
+            "line": 288
           },
           "name": "task",
           "type": {
@@ -14234,7 +14323,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 313
+            "line": 314
           },
           "name": "subnetSelection",
           "optional": true,
@@ -14251,7 +14340,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 306
+            "line": 307
           },
           "name": "vpc",
           "optional": true,
@@ -14276,7 +14365,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/fargate.ts",
-        "line": 32
+        "line": 33
       },
       "name": "FargateRunnerProviderProps",
       "properties": [
@@ -14291,7 +14380,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 119
+            "line": 120
           },
           "name": "assignPublicIp",
           "optional": true,
@@ -14309,7 +14398,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 110
+            "line": 111
           },
           "name": "cluster",
           "optional": true,
@@ -14328,7 +14417,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 138
+            "line": 139
           },
           "name": "cpu",
           "optional": true,
@@ -14347,7 +14436,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 165
+            "line": 166
           },
           "name": "ephemeralStorageGiB",
           "optional": true,
@@ -14366,7 +14455,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 73
+            "line": 74
           },
           "name": "group",
           "optional": true,
@@ -14385,7 +14474,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 40
+            "line": 41
           },
           "name": "imageBuilder",
           "optional": true,
@@ -14404,7 +14493,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 48
+            "line": 49
           },
           "name": "label",
           "optional": true,
@@ -14423,7 +14512,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 59
+            "line": 60
           },
           "name": "labels",
           "optional": true,
@@ -14447,7 +14536,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 156
+            "line": 157
           },
           "name": "memoryLimitMiB",
           "optional": true,
@@ -14466,7 +14555,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 96
+            "line": 97
           },
           "name": "securityGroup",
           "optional": true,
@@ -14484,7 +14573,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 103
+            "line": 104
           },
           "name": "securityGroups",
           "optional": true,
@@ -14508,7 +14597,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 175
+            "line": 176
           },
           "name": "spot",
           "optional": true,
@@ -14526,7 +14615,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 87
+            "line": 88
           },
           "name": "subnetSelection",
           "optional": true,
@@ -14544,7 +14633,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 80
+            "line": 81
           },
           "name": "vpc",
           "optional": true,
@@ -14647,7 +14736,7 @@
         },
         "locationInModule": {
           "filename": "src/runner.ts",
-          "line": 312
+          "line": 317
         },
         "parameters": [
           {
@@ -14677,7 +14766,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 282
+        "line": 285
       },
       "methods": [
         {
@@ -14688,7 +14777,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 921
+            "line": 945
           },
           "name": "createLogsInsightsQueries",
           "parameters": [
@@ -14713,7 +14802,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 897
+            "line": 921
           },
           "name": "failedImageBuildsTopic",
           "parameters": [
@@ -14742,7 +14831,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 873
+            "line": 897
           },
           "name": "metricFailed",
           "parameters": [
@@ -14768,7 +14857,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 817
+            "line": 841
           },
           "name": "metricJobCompleted",
           "parameters": [
@@ -14794,7 +14883,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 864
+            "line": 888
           },
           "name": "metricSucceeded",
           "parameters": [
@@ -14820,7 +14909,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 880
+            "line": 904
           },
           "name": "metricTime",
           "parameters": [
@@ -14850,7 +14939,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 298
+            "line": 301
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -14866,7 +14955,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 286
+            "line": 289
           },
           "name": "providers",
           "type": {
@@ -14895,7 +14984,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 291
+            "line": 294
           },
           "name": "secrets",
           "type": {
@@ -14909,7 +14998,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 312
+            "line": 317
           },
           "name": "props",
           "optional": true,
@@ -14931,7 +15020,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 44
+        "line": 45
       },
       "name": "GitHubRunnersProps",
       "properties": [
@@ -14946,7 +15035,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 91
+            "line": 92
           },
           "name": "allowPublicSubnet",
           "optional": true,
@@ -14964,7 +15053,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 137
+            "line": 138
           },
           "name": "extraCertificates",
           "optional": true,
@@ -14983,7 +15072,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 144
+            "line": 145
           },
           "name": "idleTimeout",
           "optional": true,
@@ -15001,7 +15090,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 151
+            "line": 152
           },
           "name": "logOptions",
           "optional": true,
@@ -15020,7 +15109,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 50
+            "line": 51
           },
           "name": "providers",
           "optional": true,
@@ -15045,14 +15134,15 @@
         {
           "abstract": true,
           "docs": {
-            "remarks": "* The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput }\n* The function returns a selected provider and its labels as {@link ProviderSelectorResult }\n* You can decline to provision a runner by returning undefined as the provider selector result\n* You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.)\n* Labels don't have to match the labels originally configured for the provider, but see warnings below\n* This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total)\n\n**WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.**\n\n**WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.**\n\n**For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. See {@link SETUP_GITHUB.md } for more details on the different registration levels. This information is also available while using the setup wizard.",
+            "remarks": "* The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput }\n* The function returns a selected provider and its labels as {@link ProviderSelectorResult }\n* You can decline to provision a runner by returning undefined as the provider selector result\n* You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.)\n* Labels don't have to match the labels originally configured for the provider, but see warnings below\n* This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total)\n\n**WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.**\n\n**WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.**\n\n**For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.",
+            "see": "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md",
             "stability": "experimental",
             "summary": "Optional Lambda function to customize provider selection logic and label assignment."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 206
+            "line": 209
           },
           "name": "providerSelector",
           "optional": true,
@@ -15071,7 +15161,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 59
+            "line": 60
           },
           "name": "requireSelfHostedLabel",
           "optional": true,
@@ -15090,7 +15180,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 188
+            "line": 189
           },
           "name": "retryOptions",
           "optional": true,
@@ -15109,7 +15199,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 100
+            "line": 101
           },
           "name": "securityGroup",
           "optional": true,
@@ -15127,7 +15217,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 109
+            "line": 110
           },
           "name": "securityGroups",
           "optional": true,
@@ -15151,7 +15241,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 158
+            "line": 159
           },
           "name": "setupAccess",
           "optional": true,
@@ -15170,7 +15260,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 177
+            "line": 178
           },
           "name": "statusAccess",
           "optional": true,
@@ -15188,7 +15278,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 75
+            "line": 76
           },
           "name": "vpc",
           "optional": true,
@@ -15206,7 +15296,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 82
+            "line": 83
           },
           "name": "vpcSubnets",
           "optional": true,
@@ -15225,7 +15315,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 170
+            "line": 171
           },
           "name": "webhookAccess",
           "optional": true,
@@ -15250,19 +15340,19 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 525
+        "line": 553
       },
       "methods": [
         {
           "abstract": true,
           "docs": {
-            "remarks": "Called by GithubRunners and shouldn't be called manually.",
+            "remarks": "If the provider has multiple attempts, each attempt should be followed by a `Catch` that deletes the failed runner. Use\n{@link IRunnerRuntimeParameters.addCatchAndCleanUp} to add the catch.\n\nCalled by GithubRunners and shouldn't be called manually.",
             "stability": "experimental",
             "summary": "Generate step function tasks that execute the runner."
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 548
+            "line": 579
           },
           "name": "getStepFunctionTask",
           "parameters": [
@@ -15272,7 +15362,7 @@
               },
               "name": "parameters",
               "type": {
-                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
+                "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters"
               }
             }
           ],
@@ -15291,7 +15381,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 556
+            "line": 593
           },
           "name": "grantStateMachine",
           "parameters": [
@@ -15315,7 +15405,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 563
+            "line": 600
           },
           "name": "status",
           "parameters": [
@@ -15339,6 +15429,28 @@
               }
             }
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Merged constants from all sub-providers for the single orchestrator `$.consts` pass. Duplicate keys across sub-providers must be avoided."
+          },
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 585
+          },
+          "name": "stepFunctionConstants",
+          "returns": {
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "primitive": "string"
+                },
+                "kind": "map"
+              }
+            }
+          }
         }
       ],
       "name": "ICompositeProvider",
@@ -15353,7 +15465,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 533
+            "line": 561
           },
           "name": "labels",
           "type": {
@@ -15375,7 +15487,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 539
+            "line": 567
           },
           "name": "providers",
           "type": {
@@ -15471,7 +15583,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 406
+        "line": 422
       },
       "name": "IRunnerAmiStatus",
       "properties": [
@@ -15484,7 +15596,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 410
+            "line": 426
           },
           "name": "launchTemplate",
           "type": {
@@ -15500,7 +15612,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 415
+            "line": 431
           },
           "name": "amiBuilderLogGroup",
           "optional": true,
@@ -15575,7 +15687,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 386
+        "line": 402
       },
       "name": "IRunnerImageStatus",
       "properties": [
@@ -15588,7 +15700,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 390
+            "line": 406
           },
           "name": "imageRepository",
           "type": {
@@ -15604,7 +15716,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 395
+            "line": 411
           },
           "name": "imageTag",
           "type": {
@@ -15620,7 +15732,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 400
+            "line": 416
           },
           "name": "imageBuilderLogGroup",
           "optional": true,
@@ -15634,7 +15746,7 @@
     "@cloudsnorkel/cdk-github-runners.IRunnerProvider": {
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "docs": {
-        "remarks": "Implementations create all required resources and return a step function task that starts those resources from {@link getStepFunctionTask}.",
+        "remarks": "Implementations create all required resources and return a step function task that starts those resources from {@link getStepFunctionTask}.\n\nThis interface is not guaranteed to be stable. If you end up implementing your own provider, please let us know so we can consider changing that contract.",
         "stability": "experimental",
         "summary": "Interface for all runner providers."
       },
@@ -15647,7 +15759,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 471
+        "line": 489
       },
       "methods": [
         {
@@ -15659,7 +15771,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 502
+            "line": 520
           },
           "name": "getStepFunctionTask",
           "parameters": [
@@ -15669,7 +15781,7 @@
               },
               "name": "parameters",
               "type": {
-                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
+                "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters"
               }
             }
           ],
@@ -15688,7 +15800,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 510
+            "line": 538
           },
           "name": "grantStateMachine",
           "parameters": [
@@ -15712,7 +15824,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 517
+            "line": 545
           },
           "name": "status",
           "parameters": [
@@ -15731,6 +15843,30 @@
               "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus"
             }
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "`{}` — {@link BaseProvider } returns an empty object; override when needed (e.g. EC2 userdata template).",
+            "remarks": "To use the constants in your provider, use `'$.consts.key'` as a path.",
+            "stability": "experimental",
+            "summary": "Static string constants injected once into the orchestrator execution input at `$.consts`. Use unique keys for dynamic values (e.g. include `this.node.path` in the key). Values must be plain strings known at synthesis time."
+          },
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 530
+          },
+          "name": "stepFunctionConstants",
+          "returns": {
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "primitive": "string"
+                },
+                "kind": "map"
+              }
+            }
+          }
         }
       ],
       "name": "IRunnerProvider",
@@ -15745,7 +15881,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 479
+            "line": 497
           },
           "name": "labels",
           "type": {
@@ -15767,7 +15903,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 486
+            "line": 504
           },
           "name": "logGroup",
           "type": {
@@ -15784,7 +15920,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 493
+            "line": 511
           },
           "name": "retryableErrors",
           "type": {
@@ -15809,7 +15945,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 421
+        "line": 437
       },
       "name": "IRunnerProviderStatus",
       "properties": [
@@ -15822,7 +15958,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 430
+            "line": 446
           },
           "name": "labels",
           "type": {
@@ -15843,7 +15979,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 425
+            "line": 441
           },
           "name": "type",
           "type": {
@@ -15859,7 +15995,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 460
+            "line": 476
           },
           "name": "ami",
           "optional": true,
@@ -15876,7 +16012,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 435
+            "line": 451
           },
           "name": "constructPath",
           "optional": true,
@@ -15893,7 +16029,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 455
+            "line": 471
           },
           "name": "image",
           "optional": true,
@@ -15910,7 +16046,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 465
+            "line": 481
           },
           "name": "logGroup",
           "optional": true,
@@ -15927,7 +16063,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 450
+            "line": 466
           },
           "name": "roleArn",
           "optional": true,
@@ -15944,7 +16080,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 445
+            "line": 461
           },
           "name": "securityGroups",
           "optional": true,
@@ -15966,7 +16102,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 440
+            "line": 456
           },
           "name": "vpcArn",
           "optional": true,
@@ -15977,42 +16113,222 @@
       ],
       "symbolId": "src/providers/common:IRunnerProviderStatus"
     },
-    "@cloudsnorkel/cdk-github-runners.ImageBuilderAsset": {
+    "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters": {
       "assembly": "@cloudsnorkel/cdk-github-runners",
-      "datatype": true,
       "docs": {
+        "remarks": "```sh\n./config.sh --unattended --url \"{REGISTRATION_URL}\" --token \"${RUNNER_TOKEN}\" --ephemeral --work _work --labels \"${RUNNER_LABEL}\" --name \"${RUNNER_NAME}\" --disableupdate\n```\n\nAll parameters are specified as step function paths and therefore must be used only in step function task parameters.",
         "stability": "experimental",
-        "summary": "An asset including file or directory to place inside the built image."
+        "summary": "Workflow job parameters as parsed from the webhook event. Pass these into your runner executor and run something like:."
       },
-      "fqn": "@cloudsnorkel/cdk-github-runners.ImageBuilderAsset",
+      "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters",
       "kind": "interface",
       "locationInModule": {
-        "filename": "src/image-builders/aws-image-builder/builder.ts",
-        "line": 97
+        "filename": "src/providers/common.ts",
+        "line": 345
       },
-      "name": "ImageBuilderAsset",
-      "properties": [
+      "methods": [
         {
           "abstract": true,
           "docs": {
+            "remarks": "It is important to fully clean up after any failed runner provisioning. GitHub\nwill fail booting a new runner if the previous one with the same name is not\nfully cleaned up.",
             "stability": "experimental",
-            "summary": "Asset to place in the image."
+            "summary": "Catches all errors and cleans up the failed runner from GitHub Actions."
           },
-          "immutable": true,
           "locationInModule": {
-            "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 106
+            "filename": "src/providers/common.ts",
+            "line": 391
           },
-          "name": "asset",
-          "type": {
-            "fqn": "aws-cdk-lib.aws_s3_assets.Asset"
-          }
-        },
+          "name": "addCatchAndCleanUp",
+          "parameters": [
+            {
+              "docs": {
+                "summary": "state whose failures should trigger cleanup."
+              },
+              "name": "state",
+              "type": {
+                "union": {
+                  "types": [
+                    {
+                      "fqn": "aws-cdk-lib.aws_stepfunctions.TaskStateBase"
+                    },
+                    {
+                      "fqn": "aws-cdk-lib.aws_stepfunctions.Parallel"
+                    },
+                    {
+                      "fqn": "aws-cdk-lib.aws_stepfunctions.Map"
+                    }
+                  ]
+                }
+              }
+            },
+            {
+              "docs": {
+                "summary": "optional subgraph to run after cleanup."
+              },
+              "name": "next",
+              "optional": true,
+              "type": {
+                "fqn": "aws-cdk-lib.aws_stepfunctions.IChainable"
+              }
+            }
+          ]
+        }
+      ],
+      "name": "IRunnerRuntimeParameters",
+      "properties": [
         {
           "abstract": true,
           "docs": {
+            "remarks": "Most of the time this will be github.com but for self-hosted GitHub instances, this will be different.",
             "stability": "experimental",
-            "summary": "Path to place asset in the image."
+            "summary": "Path to GitHub domain."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 359
+          },
+          "name": "githubDomainPath",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Path to comma-separated labels string to use for runner."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 379
+          },
+          "name": "labelsPath",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Path to repository owner name."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 364
+          },
+          "name": "ownerPath",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Repository or organization URL to register runner at."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 374
+          },
+          "name": "registrationUrl",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Path to repository name."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 369
+          },
+          "name": "repoPath",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "We specifically set the name to make troubleshooting easier.",
+            "stability": "experimental",
+            "summary": "Path to desired runner name."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 354
+          },
+          "name": "runnerNamePath",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Path to runner token used to register token."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 349
+          },
+          "name": "runnerTokenPath",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/providers/common:IRunnerRuntimeParameters"
+    },
+    "@cloudsnorkel/cdk-github-runners.ImageBuilderAsset": {
+      "assembly": "@cloudsnorkel/cdk-github-runners",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental",
+        "summary": "An asset including file or directory to place inside the built image."
+      },
+      "fqn": "@cloudsnorkel/cdk-github-runners.ImageBuilderAsset",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/image-builders/aws-image-builder/builder.ts",
+        "line": 97
+      },
+      "name": "ImageBuilderAsset",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Asset to place in the image."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/image-builders/aws-image-builder/builder.ts",
+            "line": 106
+          },
+          "name": "asset",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_s3_assets.Asset"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Path to place asset in the image."
           },
           "immutable": true,
           "locationInModule": {
@@ -16595,7 +16911,7 @@
               },
               "name": "parameters",
               "type": {
-                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
+                "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerRuntimeParameters"
               }
             }
           ],
@@ -16632,7 +16948,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 613
+            "line": 677
           },
           "name": "labelsFromProperties",
           "parameters": [
@@ -16699,6 +17015,28 @@
               "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus"
             }
           }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Override to inject static strings into `$.consts` on the orchestrator state machine."
+          },
+          "locationInModule": {
+            "filename": "src/providers/common.ts",
+            "line": 673
+          },
+          "name": "stepFunctionConstants",
+          "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
+          "returns": {
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "primitive": "string"
+                },
+                "kind": "map"
+              }
+            }
+          }
         }
       ],
       "name": "LambdaRunnerProvider",
@@ -17431,7 +17769,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 212
+        "line": 215
       },
       "name": "LogOptions",
       "properties": [
@@ -17445,7 +17783,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 223
+            "line": 226
           },
           "name": "includeExecutionData",
           "optional": true,
@@ -17463,7 +17801,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 230
+            "line": 233
           },
           "name": "level",
           "optional": true,
@@ -17480,7 +17818,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 216
+            "line": 219
           },
           "name": "logGroupName",
           "optional": true,
@@ -17499,7 +17837,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 239
+            "line": 242
           },
           "name": "logRetention",
           "optional": true,
@@ -19562,139 +19900,6 @@
       ],
       "symbolId": "src/providers/common:RunnerProviderProps"
     },
-    "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters": {
-      "assembly": "@cloudsnorkel/cdk-github-runners",
-      "datatype": true,
-      "docs": {
-        "remarks": "```sh\n./config.sh --unattended --url \"{REGISTRATION_URL}\" --token \"${RUNNER_TOKEN}\" --ephemeral --work _work --labels \"${RUNNER_LABEL}\" --name \"${RUNNER_NAME}\" --disableupdate\n```\n\nAll parameters are specified as step function paths and therefore must be used only in step function task parameters.",
-        "stability": "experimental",
-        "summary": "Workflow job parameters as parsed from the webhook event. Pass these into your runner executor and run something like:."
-      },
-      "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters",
-      "kind": "interface",
-      "locationInModule": {
-        "filename": "src/providers/common.ts",
-        "line": 345
-      },
-      "name": "RunnerRuntimeParameters",
-      "properties": [
-        {
-          "abstract": true,
-          "docs": {
-            "remarks": "Most of the time this will be github.com but for self-hosted GitHub instances, this will be different.",
-            "stability": "experimental",
-            "summary": "Path to GitHub domain."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/providers/common.ts",
-            "line": 359
-          },
-          "name": "githubDomainPath",
-          "type": {
-            "primitive": "string"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "stability": "experimental",
-            "summary": "Path to comma-separated labels string to use for runner."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/providers/common.ts",
-            "line": 379
-          },
-          "name": "labelsPath",
-          "type": {
-            "primitive": "string"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "stability": "experimental",
-            "summary": "Path to repository owner name."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/providers/common.ts",
-            "line": 364
-          },
-          "name": "ownerPath",
-          "type": {
-            "primitive": "string"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "stability": "experimental",
-            "summary": "Repository or organization URL to register runner at."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/providers/common.ts",
-            "line": 374
-          },
-          "name": "registrationUrl",
-          "type": {
-            "primitive": "string"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "stability": "experimental",
-            "summary": "Path to repository name."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/providers/common.ts",
-            "line": 369
-          },
-          "name": "repoPath",
-          "type": {
-            "primitive": "string"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "remarks": "We specifically set the name to make troubleshooting easier.",
-            "stability": "experimental",
-            "summary": "Path to desired runner name."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/providers/common.ts",
-            "line": 354
-          },
-          "name": "runnerNamePath",
-          "type": {
-            "primitive": "string"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "stability": "experimental",
-            "summary": "Path to runner token used to register token."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/providers/common.ts",
-            "line": 349
-          },
-          "name": "runnerTokenPath",
-          "type": {
-            "primitive": "string"
-          }
-        }
-      ],
-      "symbolId": "src/providers/common:RunnerRuntimeParameters"
-    },
     "@cloudsnorkel/cdk-github-runners.RunnerVersion": {
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "docs": {
@@ -19823,8 +20028,8 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "base": "constructs.Construct",
       "docs": {
-        "example": "// Rate: fill every 12 hours\nnew ScheduledWarmRunner(stack, 'Every 12 Hours', {\n  runners,\n  provider: myProvider,\n  count: 2,\n  owner: 'my-org',\n  repo: 'my-repo',\n  schedule: events.Schedule.rate(cdk.Duration.hours(5)),\n  duration: cdk.Duration.hours(12),\n});",
-        "remarks": "Runners will be provisioned using the specified provider and registered in the specified repository or organization.\n\nRegistration level must match the one selected during setup. See {@link SETUP_GITHUB.md } for more information on the selection.\n\n## Limitations\n\n- **No deployment-fill**: Unlike `AlwaysOnWarmRunner`, scheduled warm runners do not get an initial\n  fill on deploy. The first fill happens at the next schedule occurrence. If you deploy at 1pm for\n  a 2pm schedule, runners will not appear until 2pm.\n- Jobs will still trigger provisioning of on-demand runners, even if a warm runner ends up being used.\n- You may briefly see more than `count` runners when changing config or at rotation.\n- To remove: set `count` to 0, deploy, wait for warm runners to stop, then remove and deploy again.\n  If you don't follow this procedure, warm runners may linger until they expire.\n- Provider failures or timeouts (like Lambda provider timing out after 15 minutes) will result in a\n  gap in coverage until the retry succeeds. Current retry mechanism has built-in back-off rate and\n  can be tweaked using `retryOptions`. This will be improved in the future.",
+        "remarks": "Runners will be provisioned using the specified provider and registered in the specified repository or organization.\n\nRegistration level must match the one selected during setup.",
+        "see": "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md\n\n## Limitations\n\n- **No deployment-fill**: Unlike `AlwaysOnWarmRunner`, scheduled warm runners do not get an initial\nfill on deploy. The first fill happens at the next schedule occurrence. If you deploy at 1pm for\na 2pm schedule, runners will not appear until 2pm.\n- Jobs will still trigger provisioning of on-demand runners, even if a warm runner ends up being used.\n- You may briefly see more than `count` runners when changing config or at rotation.\n- To remove: set `count` to 0, deploy, wait for warm runners to stop, then remove and deploy again.\nIf you don't follow this procedure, warm runners may linger until they expire.\n- Provider failures or timeouts (like Lambda provider timing out after 15 minutes) will result in a\ngap in coverage until the retry succeeds. Current retry mechanism has built-in back-off rate and\ncan be tweaked using `retryOptions`. This will be improved in the future.\n\n```typescript\n// Cron: fill at 1pm on weekdays\nnew ScheduledWarmRunner(stack, 'Business Hours', {\nrunners,\nprovider: myProvider,\ncount: 3,\nowner: 'my-org',\nrepo: 'my-repo',\nschedule: events.Schedule.cron({ hour: '13', minute: '0', weekDay: 'MON-FRI' }),\nduration: cdk.Duration.hours(2),\n});\n```\n\n```typescript\n// Rate: fill every 12 hours\nnew ScheduledWarmRunner(stack, 'Every 12 Hours', {\nrunners,\nprovider: myProvider,\ncount: 2,\nowner: 'my-org',\nrepo: 'my-repo',\nschedule: events.Schedule.rate(cdk.Duration.hours(5)),\nduration: cdk.Duration.hours(12),\n});\n```",
         "stability": "experimental",
         "summary": "Warm runners active during a time window specified by start time (`schedule`) and duration (`duration`)."
       },
@@ -19835,7 +20040,7 @@
         },
         "locationInModule": {
           "filename": "src/warm-runner.ts",
-          "line": 275
+          "line": 283
         },
         "parameters": [
           {
@@ -19861,7 +20066,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/warm-runner.ts",
-        "line": 268
+        "line": 276
       },
       "name": "ScheduledWarmRunner",
       "symbolId": "src/warm-runner:ScheduledWarmRunner"
@@ -19877,7 +20082,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/warm-runner.ts",
-        "line": 63
+        "line": 64
       },
       "name": "ScheduledWarmRunnerProps",
       "properties": [
@@ -19907,7 +20112,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/warm-runner.ts",
-            "line": 73
+            "line": 74
           },
           "name": "duration",
           "type": {
@@ -19981,7 +20186,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/warm-runner.ts",
-            "line": 67
+            "line": 68
           },
           "name": "schedule",
           "type": {
@@ -19992,14 +20197,15 @@
           "abstract": true,
           "docs": {
             "default": "'repo'",
-            "remarks": "Choose\n'org' for org-wide runners, 'repo' for repo-level. See the setup wizard or\n{@link SETUP_GITHUB.md } for choosing repo vs org.",
+            "remarks": "Choose\n'org' for org-wide runners, 'repo' for repo-level. See the setup wizard for choosing repo vs org.",
+            "see": "https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md",
             "stability": "experimental",
             "summary": "Registration level — must match how your runners are set up in GitHub."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/warm-runner.ts",
-            "line": 47
+            "line": 48
           },
           "name": "registrationLevel",
           "optional": true,
@@ -20017,7 +20223,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/warm-runner.ts",
-            "line": 52
+            "line": 53
           },
           "name": "repo",
           "optional": true,
@@ -20285,7 +20491,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 569
+        "line": 626
       },
       "name": "StorageOptions",
       "properties": [
@@ -20301,7 +20507,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 590
+            "line": 647
           },
           "name": "iops",
           "optional": true,
@@ -20320,7 +20526,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 598
+            "line": 655
           },
           "name": "throughput",
           "optional": true,
@@ -20339,7 +20545,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 576
+            "line": 633
           },
           "name": "volumeType",
           "optional": true,
@@ -20361,7 +20567,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/composite.ts",
-        "line": 8
+        "line": 15
       },
       "name": "WeightedRunnerProvider",
       "properties": [
@@ -20374,7 +20580,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/composite.ts",
-            "line": 12
+            "line": 19
           },
           "name": "provider",
           "type": {
@@ -20391,7 +20597,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/composite.ts",
-            "line": 18
+            "line": 25
           },
           "name": "weight",
           "type": {
@@ -20648,6 +20854,6 @@
       "symbolId": "src/image-builders/aws-image-builder/deprecated/windows-components:WindowsComponents"
     }
   },
-  "version": "0.15.0",
-  "fingerprint": "lsUpiDAUxBKg7ICWZtaUHMCTYUR+KKujy9bIS462qas="
+  "version": "0.15.1",
+  "fingerprint": "Lk71dLShH+PMTMKLmjAt9sGKRlpS0gynnpicSme5Dts="
 }