@cloudsnorkel/cdk-github-runners 0.14.14 → 0.14.16

package/API.md

@@ -3539,7 +3539,7 @@ Any object.
 | --- | --- | --- |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunners.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunners.property.connections">connections</a></code> | <code>aws-cdk-lib.aws_ec2.Connections</code> | Manage the connections of all management functions. |
-| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunners.property.providers">providers</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>[]</code> | Configured runner providers. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunners.property.providers">providers</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a> \| <a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider">ICompositeProvider</a>[]</code> | Configured runner providers. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunners.property.secrets">secrets</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.Secrets">Secrets</a></code> | Secrets for GitHub communication including webhook secret and runner authentication. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunners.property.props">props</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps">GitHubRunnersProps</a></code> | *No description.* |
 
@@ -3576,10 +3576,10 @@ This cannot be used to manage connections of the runners. Use the `connections`
 ##### `providers`<sup>Required</sup> <a name="providers" id="@cloudsnorkel/cdk-github-runners.GitHubRunners.property.providers"></a>
 
 ```typescript
-public readonly providers: IRunnerProvider[];
+public readonly providers: (IRunnerProvider | ICompositeProvider)[];
 ```
 
-- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>[]
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a> | <a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider">ICompositeProvider</a>[]
 
 Configured runner providers.
 
@@ -5694,6 +5694,7 @@ const codeBuildRunnerProviderProps: CodeBuildRunnerProviderProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.defaultLabels">defaultLabels</a></code> | <code>boolean</code> | Add default labels based on OS and architecture of the runner. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | The number of days log events are kept in CloudWatch Logs. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.retryOptions">retryOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderRetryOptions">ProviderRetryOptions</a></code> | *No description.* |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.computeType">computeType</a></code> | <code>aws-cdk-lib.aws_codebuild.ComputeType</code> | The type of compute to use for this build. |
@@ -5710,6 +5711,21 @@ const codeBuildRunnerProviderProps: CodeBuildRunnerProviderProps = { ... }
 
 ---
 
+##### `defaultLabels`<sup>Optional</sup> <a name="defaultLabels" id="@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.defaultLabels"></a>
+
+```typescript
+public readonly defaultLabels: boolean;
+```
+
+- *Type:* boolean
+- *Default:* true
+
+Add default labels based on OS and architecture of the runner.
+
+This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`.
+
+---
+
 ##### `logRetention`<sup>Optional</sup> <a name="logRetention" id="@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.logRetention"></a>
 
 ```typescript
@@ -6128,6 +6144,7 @@ const ec2RunnerProviderProps: Ec2RunnerProviderProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.Ec2RunnerProviderProps.property.defaultLabels">defaultLabels</a></code> | <code>boolean</code> | Add default labels based on OS and architecture of the runner. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.Ec2RunnerProviderProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | The number of days log events are kept in CloudWatch Logs. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.Ec2RunnerProviderProps.property.retryOptions">retryOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderRetryOptions">ProviderRetryOptions</a></code> | *No description.* |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.Ec2RunnerProviderProps.property.amiBuilder">amiBuilder</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder">IRunnerImageBuilder</a></code> | *No description.* |
@@ -6147,6 +6164,21 @@ const ec2RunnerProviderProps: Ec2RunnerProviderProps = { ... }
 
 ---
 
+##### `defaultLabels`<sup>Optional</sup> <a name="defaultLabels" id="@cloudsnorkel/cdk-github-runners.Ec2RunnerProviderProps.property.defaultLabels"></a>
+
+```typescript
+public readonly defaultLabels: boolean;
+```
+
+- *Type:* boolean
+- *Default:* true
+
+Add default labels based on OS and architecture of the runner.
+
+This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`.
+
+---
+
 ##### `logRetention`<sup>Optional</sup> <a name="logRetention" id="@cloudsnorkel/cdk-github-runners.Ec2RunnerProviderProps.property.logRetention"></a>
 
 ```typescript
@@ -6395,6 +6427,7 @@ const ecsRunnerProviderProps: EcsRunnerProviderProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProviderProps.property.defaultLabels">defaultLabels</a></code> | <code>boolean</code> | Add default labels based on OS and architecture of the runner. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProviderProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | The number of days log events are kept in CloudWatch Logs. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProviderProps.property.retryOptions">retryOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderRetryOptions">ProviderRetryOptions</a></code> | *No description.* |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProviderProps.property.assignPublicIp">assignPublicIp</a></code> | <code>boolean</code> | Assign public IP to the runner task. |
@@ -6422,6 +6455,21 @@ const ecsRunnerProviderProps: EcsRunnerProviderProps = { ... }
 
 ---
 
+##### `defaultLabels`<sup>Optional</sup> <a name="defaultLabels" id="@cloudsnorkel/cdk-github-runners.EcsRunnerProviderProps.property.defaultLabels"></a>
+
+```typescript
+public readonly defaultLabels: boolean;
+```
+
+- *Type:* boolean
+- *Default:* true
+
+Add default labels based on OS and architecture of the runner.
+
+This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`.
+
+---
+
 ##### `logRetention`<sup>Optional</sup> <a name="logRetention" id="@cloudsnorkel/cdk-github-runners.EcsRunnerProviderProps.property.logRetention"></a>
 
 ```typescript
@@ -6787,6 +6835,7 @@ const fargateRunnerProviderProps: FargateRunnerProviderProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.FargateRunnerProviderProps.property.defaultLabels">defaultLabels</a></code> | <code>boolean</code> | Add default labels based on OS and architecture of the runner. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.FargateRunnerProviderProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | The number of days log events are kept in CloudWatch Logs. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.FargateRunnerProviderProps.property.retryOptions">retryOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderRetryOptions">ProviderRetryOptions</a></code> | *No description.* |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.FargateRunnerProviderProps.property.assignPublicIp">assignPublicIp</a></code> | <code>boolean</code> | Assign public IP to the runner task. |
@@ -6806,6 +6855,21 @@ const fargateRunnerProviderProps: FargateRunnerProviderProps = { ... }
 
 ---
 
+##### `defaultLabels`<sup>Optional</sup> <a name="defaultLabels" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProviderProps.property.defaultLabels"></a>
+
+```typescript
+public readonly defaultLabels: boolean;
+```
+
+- *Type:* boolean
+- *Default:* true
+
+Add default labels based on OS and architecture of the runner.
+
+This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`.
+
+---
+
 ##### `logRetention`<sup>Optional</sup> <a name="logRetention" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProviderProps.property.logRetention"></a>
 
 ```typescript
@@ -7157,7 +7221,8 @@ const gitHubRunnersProps: GitHubRunnersProps = { ... }
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.extraCertificates">extraCertificates</a></code> | <code>string</code> | Path to a directory containing a file named certs.pem containing any additional certificates required to trust GitHub Enterprise Server. Use this when GitHub Enterprise Server certificates are self-signed. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.idleTimeout">idleTimeout</a></code> | <code>aws-cdk-lib.Duration</code> | Time to wait before stopping a runner that remains idle. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.logOptions">logOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.LogOptions">LogOptions</a></code> | Logging options for the state machine that manages the runners. |
-| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.providers">providers</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>[]</code> | List of runner providers to use. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.providers">providers</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a> \| <a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider">ICompositeProvider</a>[]</code> | List of runner providers to use. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.providerSelector">providerSelector</a></code> | <code>aws-cdk-lib.aws_lambda.IFunction</code> | Optional Lambda function to customize provider selection logic and label assignment. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.requireSelfHostedLabel">requireSelfHostedLabel</a></code> | <code>boolean</code> | Whether to require the `self-hosted` label. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.retryOptions">retryOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderRetryOptions">ProviderRetryOptions</a></code> | Options to retry operation in case of failure like missing capacity, or API quota issues. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.securityGroup">securityGroup</a></code> | <code>aws-cdk-lib.aws_ec2.ISecurityGroup</code> | Security group attached to all management functions. |
@@ -7248,10 +7313,10 @@ Logging options for the state machine that manages the runners.
 ##### `providers`<sup>Optional</sup> <a name="providers" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.providers"></a>
 
 ```typescript
-public readonly providers: IRunnerProvider[];
+public readonly providers: (IRunnerProvider | ICompositeProvider)[];
 ```
 
-- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>[]
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a> | <a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider">ICompositeProvider</a>[]
 - *Default:* CodeBuild, Lambda and Fargate runners with all the defaults (no VPC or default account VPC)
 
 List of runner providers to use.
@@ -7260,6 +7325,31 @@ At least one provider is required. Provider will be selected when its label matc
 
 ---
 
+##### `providerSelector`<sup>Optional</sup> <a name="providerSelector" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.providerSelector"></a>
+
+```typescript
+public readonly providerSelector: IFunction;
+```
+
+- *Type:* aws-cdk-lib.aws_lambda.IFunction
+
+Optional Lambda function to customize provider selection logic and label assignment.
+
+* The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput }
+* The function returns a selected provider and its labels as {@link ProviderSelectorResult }
+* You can decline to provision a runner by returning undefined as the provider selector result
+* You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.)
+* Labels don't have to match the labels originally configured for the provider, but see warnings below
+* This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total)
+
+**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.**
+
+**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.**
+
+**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.
+
+---
+
 ##### `requireSelfHostedLabel`<sup>Optional</sup> <a name="requireSelfHostedLabel" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.requireSelfHostedLabel"></a>
 
 ```typescript
@@ -7569,6 +7659,7 @@ const lambdaRunnerProviderProps: LambdaRunnerProviderProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaRunnerProviderProps.property.defaultLabels">defaultLabels</a></code> | <code>boolean</code> | Add default labels based on OS and architecture of the runner. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaRunnerProviderProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | The number of days log events are kept in CloudWatch Logs. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaRunnerProviderProps.property.retryOptions">retryOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderRetryOptions">ProviderRetryOptions</a></code> | *No description.* |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaRunnerProviderProps.property.ephemeralStorageSize">ephemeralStorageSize</a></code> | <code>aws-cdk-lib.Size</code> | The size of the function’s /tmp directory in MiB. |
@@ -7585,6 +7676,21 @@ const lambdaRunnerProviderProps: LambdaRunnerProviderProps = { ... }
 
 ---
 
+##### `defaultLabels`<sup>Optional</sup> <a name="defaultLabels" id="@cloudsnorkel/cdk-github-runners.LambdaRunnerProviderProps.property.defaultLabels"></a>
+
+```typescript
+public readonly defaultLabels: boolean;
+```
+
+- *Type:* boolean
+- *Default:* true
+
+Add default labels based on OS and architecture of the runner.
+
+This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`.
+
+---
+
 ##### `logRetention`<sup>Optional</sup> <a name="logRetention" id="@cloudsnorkel/cdk-github-runners.LambdaRunnerProviderProps.property.logRetention"></a>
 
 ```typescript
@@ -7942,6 +8048,138 @@ Which failures generate a retry depends on the specific provider.
 
 ---
 
+### ProviderSelectorInput <a name="ProviderSelectorInput" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorInput"></a>
+
+Input to the provider selector Lambda function.
+
+#### Initializer <a name="Initializer" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.Initializer"></a>
+
+```typescript
+import { ProviderSelectorInput } from '@cloudsnorkel/cdk-github-runners'
+
+const providerSelectorInput: ProviderSelectorInput = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.property.payload">payload</a></code> | <code>any</code> | Full GitHub webhook payload (workflow_job event structure with action="queued"). |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.property.providers">providers</a></code> | <code>{[ key: string ]: string[]}</code> | Map of available provider node paths to their configured labels. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.property.defaultLabels">defaultLabels</a></code> | <code>string[]</code> | Labels that would have been used by default (the selected provider's labels). |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.property.defaultProvider">defaultProvider</a></code> | <code>string</code> | Provider node path that would have been selected by default label matching. |
+
+---
+
+##### `payload`<sup>Required</sup> <a name="payload" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.property.payload"></a>
+
+```typescript
+public readonly payload: any;
+```
+
+- *Type:* any
+
+Full GitHub webhook payload (workflow_job event structure with action="queued").
+
+* Original labels requested by the workflow job can be found at `payload.workflow_job.labels`.
+* Repository path (e.g. CloudSnorkel/cdk-github-runners) is at `payload.repository.full_name`.
+* Commit hash is at `payload.workflow_job.head_sha`.
+
+> [https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=queued#workflow_job](https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=queued#workflow_job)
+
+---
+
+##### `providers`<sup>Required</sup> <a name="providers" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.property.providers"></a>
+
+```typescript
+public readonly providers: {[ key: string ]: string[]};
+```
+
+- *Type:* {[ key: string ]: string[]}
+
+Map of available provider node paths to their configured labels.
+
+Example: { "MyStack/Small": ["linux", "small"], "MyStack/Large": ["linux", "large"] }
+
+---
+
+##### `defaultLabels`<sup>Optional</sup> <a name="defaultLabels" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.property.defaultLabels"></a>
+
+```typescript
+public readonly defaultLabels: string[];
+```
+
+- *Type:* string[]
+
+Labels that would have been used by default (the selected provider's labels).
+
+May be undefined if no provider matched by default.
+
+---
+
+##### `defaultProvider`<sup>Optional</sup> <a name="defaultProvider" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorInput.property.defaultProvider"></a>
+
+```typescript
+public readonly defaultProvider: string;
+```
+
+- *Type:* string
+
+Provider node path that would have been selected by default label matching.
+
+Use this to easily return the default selection: `{ provider: input.defaultProvider, labels: input.defaultLabels }`
+May be undefined if no provider matched by default.
+
+---
+
+### ProviderSelectorResult <a name="ProviderSelectorResult" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorResult"></a>
+
+Result from the provider selector Lambda function.
+
+#### Initializer <a name="Initializer" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorResult.Initializer"></a>
+
+```typescript
+import { ProviderSelectorResult } from '@cloudsnorkel/cdk-github-runners'
+
+const providerSelectorResult: ProviderSelectorResult = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderSelectorResult.property.labels">labels</a></code> | <code>string[]</code> | Labels to use when registering the runner. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderSelectorResult.property.provider">provider</a></code> | <code>string</code> | Node path of the provider to use (e.g., "MyStack/MyProvider"). Must match one of the configured provider node paths from the input. If not provided, the job will be skipped (no runner created). |
+
+---
+
+##### `labels`<sup>Optional</sup> <a name="labels" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorResult.property.labels"></a>
+
+```typescript
+public readonly labels: string[];
+```
+
+- *Type:* string[]
+
+Labels to use when registering the runner.
+
+Must be returned when a provider is selected.
+Can be used to add, remove, or modify labels.
+
+---
+
+##### `provider`<sup>Optional</sup> <a name="provider" id="@cloudsnorkel/cdk-github-runners.ProviderSelectorResult.property.provider"></a>
+
+```typescript
+public readonly provider: string;
+```
+
+- *Type:* string
+
+Node path of the provider to use (e.g., "MyStack/MyProvider"). Must match one of the configured provider node paths from the input. If not provided, the job will be skipped (no runner created).
+
+---
+
 ### RunnerAmi <a name="RunnerAmi" id="@cloudsnorkel/cdk-github-runners.RunnerAmi"></a>
 
 Description of a AMI built by {@link RunnerImageBuilder }.
@@ -8543,11 +8781,27 @@ const runnerProviderProps: RunnerProviderProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerProviderProps.property.defaultLabels">defaultLabels</a></code> | <code>boolean</code> | Add default labels based on OS and architecture of the runner. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerProviderProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | The number of days log events are kept in CloudWatch Logs. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerProviderProps.property.retryOptions">retryOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.ProviderRetryOptions">ProviderRetryOptions</a></code> | *No description.* |
 
 ---
 
+##### `defaultLabels`<sup>Optional</sup> <a name="defaultLabels" id="@cloudsnorkel/cdk-github-runners.RunnerProviderProps.property.defaultLabels"></a>
+
+```typescript
+public readonly defaultLabels: boolean;
+```
+
+- *Type:* boolean
+- *Default:* true
+
+Add default labels based on OS and architecture of the runner.
+
+This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`.
+
+---
+
 ##### `logRetention`<sup>Optional</sup> <a name="logRetention" id="@cloudsnorkel/cdk-github-runners.RunnerProviderProps.property.logRetention"></a>
 
 ```typescript
@@ -8600,6 +8854,7 @@ const runnerRuntimeParameters: RunnerRuntimeParameters = { ... }
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters.property.githubDomainPath">githubDomainPath</a></code> | <code>string</code> | Path to GitHub domain. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters.property.labelsPath">labelsPath</a></code> | <code>string</code> | Path to comma-separated labels string to use for runner. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters.property.ownerPath">ownerPath</a></code> | <code>string</code> | Path to repository owner name. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters.property.registrationUrl">registrationUrl</a></code> | <code>string</code> | Repository or organization URL to register runner at. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters.property.repoPath">repoPath</a></code> | <code>string</code> | Path to repository name. |
@@ -8622,6 +8877,18 @@ Most of the time this will be github.com but for self-hosted GitHub instances, t
 
 ---
 
+##### `labelsPath`<sup>Required</sup> <a name="labelsPath" id="@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters.property.labelsPath"></a>
+
+```typescript
+public readonly labelsPath: string;
+```
+
+- *Type:* string
+
+Path to comma-separated labels string to use for runner.
+
+---
+
 ##### `ownerPath`<sup>Required</sup> <a name="ownerPath" id="@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters.property.ownerPath"></a>
 
 ```typescript
@@ -8756,6 +9023,54 @@ The EBS volume type.
 
 ---
 
+### WeightedRunnerProvider <a name="WeightedRunnerProvider" id="@cloudsnorkel/cdk-github-runners.WeightedRunnerProvider"></a>
+
+Configuration for weighted distribution of runners.
+
+#### Initializer <a name="Initializer" id="@cloudsnorkel/cdk-github-runners.WeightedRunnerProvider.Initializer"></a>
+
+```typescript
+import { WeightedRunnerProvider } from '@cloudsnorkel/cdk-github-runners'
+
+const weightedRunnerProvider: WeightedRunnerProvider = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.WeightedRunnerProvider.property.provider">provider</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a></code> | The runner provider to use. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.WeightedRunnerProvider.property.weight">weight</a></code> | <code>number</code> | Weight for this provider. |
+
+---
+
+##### `provider`<sup>Required</sup> <a name="provider" id="@cloudsnorkel/cdk-github-runners.WeightedRunnerProvider.property.provider"></a>
+
+```typescript
+public readonly provider: IRunnerProvider;
+```
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>
+
+The runner provider to use.
+
+---
+
+##### `weight`<sup>Required</sup> <a name="weight" id="@cloudsnorkel/cdk-github-runners.WeightedRunnerProvider.property.weight"></a>
+
+```typescript
+public readonly weight: number;
+```
+
+- *Type:* number
+
+Weight for this provider.
+
+Higher weights mean higher probability of selection.
+Must be a positive number.
+
+---
+
 ## Classes <a name="Classes" id="Classes"></a>
 
 ### Architecture <a name="Architecture" id="@cloudsnorkel/cdk-github-runners.Architecture"></a>
@@ -8872,6 +9187,120 @@ X86_64.
 
 ---
 
+### CompositeProvider <a name="CompositeProvider" id="@cloudsnorkel/cdk-github-runners.CompositeProvider"></a>
+
+A composite runner provider that implements fallback and distribution strategies.
+
+#### Initializers <a name="Initializers" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.Initializer"></a>
+
+```typescript
+import { CompositeProvider } from '@cloudsnorkel/cdk-github-runners'
+
+new CompositeProvider()
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+
+---
+
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.CompositeProvider.distribute">distribute</a></code> | Creates a weighted distribution runner provider that randomly selects a provider based on weights. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.CompositeProvider.fallback">fallback</a></code> | Creates a fallback runner provider that tries each provider in order until one succeeds. |
+
+---
+
+##### `distribute` <a name="distribute" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.distribute"></a>
+
+```typescript
+import { CompositeProvider } from '@cloudsnorkel/cdk-github-runners'
+
+CompositeProvider.distribute(scope: Construct, id: string, weightedProviders: WeightedRunnerProvider[])
+```
+
+Creates a weighted distribution runner provider that randomly selects a provider based on weights.
+
+For example, given providers A (weight 10), B (weight 20), C (weight 30):
+- Total weight = 60
+- Probability of selecting A = 10/60 = 16.67%
+- Probability of selecting B = 20/60 = 33.33%
+- Probability of selecting C = 30/60 = 50%
+
+You can use this to distribute load across multiple instance types or availability zones.
+
+###### `scope`<sup>Required</sup> <a name="scope" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.distribute.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+The scope in which to define this construct.
+
+---
+
+###### `id`<sup>Required</sup> <a name="id" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.distribute.parameter.id"></a>
+
+- *Type:* string
+
+The scoped construct ID.
+
+---
+
+###### `weightedProviders`<sup>Required</sup> <a name="weightedProviders" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.distribute.parameter.weightedProviders"></a>
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.WeightedRunnerProvider">WeightedRunnerProvider</a>[]
+
+List of weighted runner providers.
+
+---
+
+##### `fallback` <a name="fallback" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.fallback"></a>
+
+```typescript
+import { CompositeProvider } from '@cloudsnorkel/cdk-github-runners'
+
+CompositeProvider.fallback(scope: Construct, id: string, providers: IRunnerProvider[])
+```
+
+Creates a fallback runner provider that tries each provider in order until one succeeds.
+
+For example, given providers A, B, C:
+- Try A first
+- If A fails, try B
+- If B fails, try C
+
+You can use this to try spot instance first, and switch to on-demand instances if spot is unavailable.
+
+Or you can use this to try different instance types in order of preference.
+
+###### `scope`<sup>Required</sup> <a name="scope" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.fallback.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+The scope in which to define this construct.
+
+---
+
+###### `id`<sup>Required</sup> <a name="id" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.fallback.parameter.id"></a>
+
+- *Type:* string
+
+The scoped construct ID.
+
+---
+
+###### `providers`<sup>Required</sup> <a name="providers" id="@cloudsnorkel/cdk-github-runners.CompositeProvider.fallback.parameter.providers"></a>
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>[]
+
+List of runner providers to try in order.
+
+---
+
+
+
 ### LambdaAccess <a name="LambdaAccess" id="@cloudsnorkel/cdk-github-runners.LambdaAccess"></a>
 
 Access configuration options for Lambda functions like setup and webhook function. Use this to limit access to these functions.
@@ -10187,6 +10616,134 @@ WindowsComponents.githubRunner(scope: Construct, id: string, runnerVersion: Runn
 
 ## Protocols <a name="Protocols" id="Protocols"></a>
 
+### ICompositeProvider <a name="ICompositeProvider" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider"></a>
+
+- *Extends:* constructs.IConstruct
+
+- *Implemented By:* <a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider">ICompositeProvider</a>
+
+Interface for composite runner providers that interact with multiple sub-providers.
+
+Unlike IRunnerProvider, composite providers do not have connections, grant capabilities,
+log groups, or retryable errors as they delegate to their sub-providers.
+
+#### Methods <a name="Methods" id="Methods"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider.getStepFunctionTask">getStepFunctionTask</a></code> | Generate step function tasks that execute the runner. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider.grantStateMachine">grantStateMachine</a></code> | An optional method that modifies the role of the state machine after all the tasks have been generated. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider.status">status</a></code> | Return statuses of all sub-providers to be used in the main status function. |
+
+---
+
+##### `getStepFunctionTask` <a name="getStepFunctionTask" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.getStepFunctionTask"></a>
+
+```typescript
+public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable
+```
+
+Generate step function tasks that execute the runner.
+
+Called by GithubRunners and shouldn't be called manually.
+
+###### `parameters`<sup>Required</sup> <a name="parameters" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.getStepFunctionTask.parameter.parameters"></a>
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters">RunnerRuntimeParameters</a>
+
+specific build parameters.
+
+---
+
+##### `grantStateMachine` <a name="grantStateMachine" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.grantStateMachine"></a>
+
+```typescript
+public grantStateMachine(stateMachineRole: IGrantable): void
+```
+
+An optional method that modifies the role of the state machine after all the tasks have been generated.
+
+This can be used to add additional policy
+statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}.
+
+###### `stateMachineRole`<sup>Required</sup> <a name="stateMachineRole" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.grantStateMachine.parameter.stateMachineRole"></a>
+
+- *Type:* aws-cdk-lib.aws_iam.IGrantable
+
+role for the state machine that executes the task returned from {@link getStepFunctionTask}.
+
+---
+
+##### `status` <a name="status" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.status"></a>
+
+```typescript
+public status(statusFunctionRole: IGrantable): IRunnerProviderStatus[]
+```
+
+Return statuses of all sub-providers to be used in the main status function.
+
+Also gives the status function any needed permissions to query the Docker images or AMIs.
+
+###### `statusFunctionRole`<sup>Required</sup> <a name="statusFunctionRole" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.status.parameter.statusFunctionRole"></a>
+
+- *Type:* aws-cdk-lib.aws_iam.IGrantable
+
+grantable for the status function.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider.property.labels">labels</a></code> | <code>string[]</code> | GitHub Actions labels used for this provider. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider.property.providers">providers</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>[]</code> | All sub-providers contained in this composite provider. |
+
+---
+
+##### `node`<sup>Required</sup> <a name="node" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.property.node"></a>
+
+```typescript
+public readonly node: Node;
+```
+
+- *Type:* constructs.Node
+
+The tree node.
+
+---
+
+##### `labels`<sup>Required</sup> <a name="labels" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.property.labels"></a>
+
+```typescript
+public readonly labels: string[];
+```
+
+- *Type:* string[]
+
+GitHub Actions labels used for this provider.
+
+These labels are used to identify which provider should spawn a new on-demand runner. Every job sends a webhook with the labels it's looking for
+based on runs-on. We use match the labels from the webhook with the labels specified here. If all the labels specified here are present in the
+job's labels, this provider will be chosen and spawn a new runner.
+
+---
+
+##### `providers`<sup>Required</sup> <a name="providers" id="@cloudsnorkel/cdk-github-runners.ICompositeProvider.property.providers"></a>
+
+```typescript
+public readonly providers: IRunnerProvider[];
+```
+
+- *Type:* <a href="#@cloudsnorkel/cdk-github-runners.IRunnerProvider">IRunnerProvider</a>[]
+
+All sub-providers contained in this composite provider.
+
+This is used to extract providers for metric filters and other operations.
+
+---
+
 ### IConfigurableRunnerImageBuilder <a name="IConfigurableRunnerImageBuilder" id="@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder"></a>
 
 - *Extends:* <a href="#@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder">IRunnerImageBuilder</a>, aws-cdk-lib.aws_ec2.IConnectable, aws-cdk-lib.aws_iam.IGrantable
@@ -10596,6 +11153,7 @@ Interface for runner image status used by status.json.
 | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.labels">labels</a></code> | <code>string[]</code> | Labels associated with provider. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.type">type</a></code> | <code>string</code> | Runner provider type. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.ami">ami</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerAmiStatus">IRunnerAmiStatus</a></code> | Details about AMI used by this runner provider. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.constructPath">constructPath</a></code> | <code>string</code> | CDK construct node path for this provider. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.image">image</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerImageStatus">IRunnerImageStatus</a></code> | Details about Docker image used by this runner provider. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.logGroup">logGroup</a></code> | <code>string</code> | Log group for runners. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.roleArn">roleArn</a></code> | <code>string</code> | Role attached to runners. |
@@ -10640,6 +11198,18 @@ Details about AMI used by this runner provider.
 
 ---
 
+##### `constructPath`<sup>Optional</sup> <a name="constructPath" id="@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.constructPath"></a>
+
+```typescript
+public readonly constructPath: string;
+```
+
+- *Type:* string
+
+CDK construct node path for this provider.
+
+---
+
 ##### `image`<sup>Optional</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.IRunnerProviderStatus.property.image"></a>
 
 ```typescript