@cloudsnorkel/cdk-github-runners 0.11.5 → 0.12.0

package/.jsii

@@ -7,7 +7,7 @@
     ]
   },
   "dependencies": {
-    "aws-cdk-lib": "^2.77.0",
+    "aws-cdk-lib": "^2.110.0",
     "constructs": "^10.0.5"
   },
   "dependencyClosure": {
@@ -63,29 +63,29 @@
         }
       }
     },
-    "@aws-cdk/asset-node-proxy-agent-v5": {
+    "@aws-cdk/asset-node-proxy-agent-v6": {
       "targets": {
         "dotnet": {
-          "namespace": "Amazon.CDK.Asset.NodeProxyAgentV5",
-          "packageId": "Amazon.CDK.Asset.NodeProxyAgentV5"
+          "namespace": "Amazon.CDK.Asset.NodeProxyAgentV6",
+          "packageId": "Amazon.CDK.Asset.NodeProxyAgentV6"
         },
         "go": {
           "moduleName": "github.com/cdklabs/awscdk-asset-node-proxy-agent-go",
-          "packageName": "nodeproxyagentv5"
+          "packageName": "nodeproxyagentv6"
         },
         "java": {
           "maven": {
-            "artifactId": "cdk-asset-node-proxy-agent-v5",
+            "artifactId": "cdk-asset-node-proxy-agent-v6",
             "groupId": "software.amazon.awscdk"
           },
-          "package": "software.amazon.awscdk.cdk.asset.node.proxy.agent.v5"
+          "package": "software.amazon.awscdk.cdk.asset.node.proxy.agent.v6"
         },
         "js": {
-          "npm": "@aws-cdk/asset-node-proxy-agent-v5"
+          "npm": "@aws-cdk/asset-node-proxy-agent-v6"
         },
         "python": {
-          "distName": "aws-cdk.asset-node-proxy-agent-v5",
-          "module": "aws_cdk.asset_node_proxy_agent_v5"
+          "distName": "aws-cdk.asset-node-proxy-agent-v6",
+          "module": "aws_cdk.asset_node_proxy_agent_v6"
         }
       }
     },
@@ -442,6 +442,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_backupgateway": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.BackupGateway"
+            },
+            "java": {
+              "package": "services.backupgateway"
+            },
+            "python": {
+              "module": "aws_cdk.aws_backupgateway"
+            }
+          }
+        },
         "aws-cdk-lib.aws_batch": {
           "targets": {
             "dotnet": {
@@ -533,6 +546,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_cleanrooms": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.CleanRooms"
+            },
+            "java": {
+              "package": "services.cleanrooms"
+            },
+            "python": {
+              "module": "aws_cdk.aws_cleanrooms"
+            }
+          }
+        },
         "aws-cdk-lib.aws_cloud9": {
           "targets": {
             "dotnet": {
@@ -1262,6 +1288,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_entityresolution": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.EntityResolution"
+            },
+            "java": {
+              "package": "services.entityresolution"
+            },
+            "python": {
+              "module": "aws_cdk.aws_entityresolution"
+            }
+          }
+        },
         "aws-cdk-lib.aws_events": {
           "targets": {
             "dotnet": {
@@ -1509,6 +1548,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_healthimaging": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.HealthImaging"
+            },
+            "java": {
+              "package": "services.healthimaging"
+            },
+            "python": {
+              "module": "aws_cdk.aws_healthimaging"
+            }
+          }
+        },
         "aws-cdk-lib.aws_healthlake": {
           "targets": {
             "dotnet": {
@@ -2159,6 +2211,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_mediapackagev2": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.MediaPackageV2"
+            },
+            "java": {
+              "package": "services.mediapackagev2"
+            },
+            "python": {
+              "module": "aws_cdk.aws_mediapackagev2"
+            }
+          }
+        },
         "aws-cdk-lib.aws_mediastore": {
           "targets": {
             "dotnet": {
@@ -2367,6 +2432,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_osis": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.OSIS"
+            },
+            "java": {
+              "package": "services.osis"
+            },
+            "python": {
+              "module": "aws_cdk.aws_osis"
+            }
+          }
+        },
         "aws-cdk-lib.aws_panorama": {
           "targets": {
             "dotnet": {
@@ -2380,6 +2458,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_pcaconnectorad": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.PCAConnectorAD"
+            },
+            "java": {
+              "package": "services.pcaconnectorad"
+            },
+            "python": {
+              "module": "aws_cdk.aws_pcaconnectorad"
+            }
+          }
+        },
         "aws-cdk-lib.aws_personalize": {
           "targets": {
             "dotnet": {
@@ -2432,6 +2523,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_proton": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.Proton"
+            },
+            "java": {
+              "package": "services.proton"
+            },
+            "python": {
+              "module": "aws_cdk.aws_proton"
+            }
+          }
+        },
         "aws-cdk-lib.aws_qldb": {
           "targets": {
             "dotnet": {
@@ -2913,6 +3017,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_shield": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.Shield"
+            },
+            "java": {
+              "package": "services.shield"
+            },
+            "python": {
+              "module": "aws_cdk.aws_shield"
+            }
+          }
+        },
         "aws-cdk-lib.aws_signer": {
           "targets": {
             "dotnet": {
@@ -3121,6 +3238,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_verifiedpermissions": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.VerifiedPermissions"
+            },
+            "java": {
+              "package": "services.verifiedpermissions"
+            },
+            "python": {
+              "module": "aws_cdk.aws_verifiedpermissions"
+            }
+          }
+        },
         "aws-cdk-lib.aws_voiceid": {
           "targets": {
             "dotnet": {
@@ -3212,6 +3342,19 @@
             }
           }
         },
+        "aws-cdk-lib.aws_workspacesweb": {
+          "targets": {
+            "dotnet": {
+              "package": "Amazon.CDK.AWS.WorkSpacesWeb"
+            },
+            "java": {
+              "package": "services.workspacesweb"
+            },
+            "python": {
+              "module": "aws_cdk.aws_workspacesweb"
+            }
+          }
+        },
         "aws-cdk-lib.aws_xray": {
           "targets": {
             "dotnet": {
@@ -3437,7 +3580,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[![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## 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 cloudsnorkel.cdk_github_runners import GitHubRunners\n\n   GitHubRunners(self, \"runners\")\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 { GitHubRunners } from '@cloudsnorkel/cdk-github-runners';\n\n   new GitHubRunners(this, \"runners\");\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 com.cloudsnorkel.cdk.github.runners.GitHubRunners;\n\n   GitHubRunners.Builder.create(this, \"runners\").build();\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   import \"github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\"\n\n   NewGitHubRunners(this, jsii.String(\"runners\"))\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 CloudSnorkel;\n\n   new GitHubRunners(this, \"runners\");\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, linux, codebuild]` or similar\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 = CodeBuildRunnerProvider.imageBuilder(this, 'image builder', {\n   dockerfilePath: FargateRunner.LINUX_X64_DOCKERFILE_PATH,\n   runnerVersion: RunnerVersion.specific('2.291.0'),\n   rebuildInterval: Duration.days(14),\n});\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   vpc: vpc,\n   securityGroups: [runnerSg],\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   runnerVersion: RunnerVersion.specific('2.291.0'),\n   rebuildInterval: Duration.days(14),\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   vpc: vpc,\n   securityGroups: [runnerSg],\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## 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## Other Options\n\n1. [philips-labs/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-for-github-actions\n[3]: https://github.com/philips-labs/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"
+    "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[![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## 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 cloudsnorkel.cdk_github_runners import GitHubRunners\n\n   GitHubRunners(self, \"runners\")\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 { GitHubRunners } from '@cloudsnorkel/cdk-github-runners';\n\n   new GitHubRunners(this, \"runners\");\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 com.cloudsnorkel.cdk.github.runners.GitHubRunners;\n\n   GitHubRunners.Builder.create(this, \"runners\").build();\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   import \"github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\"\n\n   NewGitHubRunners(this, jsii.String(\"runners\"))\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 CloudSnorkel;\n\n   new GitHubRunners(this, \"runners\");\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, linux, codebuild]` or similar\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## 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## Other Options\n\n1. [philips-labs/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-for-github-actions\n[3]: https://github.com/philips-labs/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"
   },
   "repository": {
     "type": "git",
@@ -4392,7 +4535,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/image-builders/aws-image-builder/builder.ts",
-        "line": 33
+        "line": 31
       },
       "name": "AwsImageBuilderRunnerImageBuilderProps",
       "properties": [
@@ -4406,7 +4549,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 39
+            "line": 37
           },
           "name": "instanceType",
           "optional": true,
@@ -4473,7 +4616,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 288
+            "line": 289
           },
           "name": "addExtraCertificates",
           "parameters": [
@@ -4495,7 +4638,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 222
+            "line": 223
           },
           "name": "addFiles",
           "parameters": [
@@ -4526,7 +4669,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 274
+            "line": 275
           },
           "name": "addPolicyStatement",
           "parameters": [
@@ -4548,7 +4691,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 249
+            "line": 250
           },
           "name": "addPostBuildCommand",
           "parameters": [
@@ -4570,7 +4713,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 237
+            "line": 238
           },
           "name": "addPreBuildCommand",
           "parameters": [
@@ -4593,7 +4736,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 529
+            "line": 530
           },
           "name": "bindAmi",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder",
@@ -4610,7 +4753,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 298
+            "line": 299
           },
           "name": "bindDockerImage",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder",
@@ -4628,7 +4771,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 262
+            "line": 263
           },
           "name": "setBuildArg",
           "parameters": [
@@ -4662,7 +4805,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/codebuild-deprecated.ts",
-            "line": 523
+            "line": 524
           },
           "name": "connections",
           "type": {
@@ -4957,7 +5100,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/codebuild.ts",
-          "line": 220
+          "line": 226
         },
         "parameters": [
           {
@@ -4984,7 +5127,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/codebuild.ts",
-        "line": 426
+        "line": 432
       },
       "name": "CodeBuildRunner",
       "symbolId": "src/providers/codebuild:CodeBuildRunner"
@@ -5078,7 +5221,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/codebuild.ts",
-          "line": 220
+          "line": 226
         },
         "parameters": [
           {
@@ -5113,13 +5256,13 @@
       "methods": [
         {
           "docs": {
-            "remarks": "Included components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.docker()`\n * `RunnerImageComponent.githubRunner()`",
+            "remarks": "You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props.\n\nYou can add components to the image builder by calling `imageBuilder.addComponent()`.\n\nThe default OS is Ubuntu running on x64 architecture.\n\nIncluded components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.docker()`\n * `RunnerImageComponent.githubRunner()`",
             "stability": "experimental",
-            "summary": "Create new image builder that builds CodeBuild specific runner images using Ubuntu."
+            "summary": "Create new image builder that builds CodeBuild specific runner images."
           },
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 167
+            "line": 173
           },
           "name": "imageBuilder",
           "parameters": [
@@ -5145,7 +5288,7 @@
           ],
           "returns": {
             "type": {
-              "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageBuilder"
+              "fqn": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder"
             }
           },
           "static": true
@@ -5158,7 +5301,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 353
+            "line": 359
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -5187,7 +5330,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 394
+            "line": 400
           },
           "name": "grantStateMachine",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -5256,7 +5399,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 397
+            "line": 403
           },
           "name": "status",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -5323,7 +5466,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 418
+            "line": 424
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -5339,7 +5482,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 197
+            "line": 203
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -5356,7 +5499,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 202
+            "line": 208
           },
           "name": "image",
           "type": {
@@ -5371,7 +5514,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 192
+            "line": 198
           },
           "name": "labels",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -5393,7 +5536,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 209
+            "line": 215
           },
           "name": "logGroup",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -5409,7 +5552,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 187
+            "line": 193
           },
           "name": "project",
           "type": {
@@ -5424,7 +5567,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 211
+            "line": 217
           },
           "name": "retryableErrors",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -5713,7 +5856,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/deprecated/container.ts",
-            "line": 218
+            "line": 219
           },
           "name": "addComponent",
           "parameters": [
@@ -5733,7 +5876,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/deprecated/container.ts",
-            "line": 235
+            "line": 236
           },
           "name": "addExtraCertificates",
           "parameters": [
@@ -5756,7 +5899,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/deprecated/container.ts",
-            "line": 340
+            "line": 341
           },
           "name": "bindAmi",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder",
@@ -5773,7 +5916,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/deprecated/container.ts",
-            "line": 248
+            "line": 249
           },
           "name": "bindDockerImage",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder",
@@ -5944,7 +6087,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/deprecated/container.ts",
-            "line": 204
+            "line": 205
           },
           "name": "prependComponent",
           "parameters": [
@@ -6343,7 +6486,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/ec2.ts",
-          "line": 340
+          "line": 346
         },
         "parameters": [
           {
@@ -6370,7 +6513,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/ec2.ts",
-        "line": 553
+        "line": 559
       },
       "name": "Ec2Runner",
       "symbolId": "src/providers/ec2:Ec2Runner"
@@ -6390,7 +6533,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/ec2.ts",
-          "line": 340
+          "line": 346
         },
         "parameters": [
           {
@@ -6425,13 +6568,13 @@
       "methods": [
         {
           "docs": {
-            "remarks": "Included components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.docker()`\n * `RunnerImageComponent.githubRunner()`",
+            "remarks": "You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props.\n\nYou can add components to the image builder by calling `imageBuilder.addComponent()`.\n\nThe default OS is Ubuntu running on x64 architecture.\n\nIncluded components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.docker()`\n * `RunnerImageComponent.githubRunner()`",
             "stability": "experimental",
-            "summary": "Create new image builder that builds EC2 specific runner images using Ubuntu."
+            "summary": "Create new image builder that builds EC2 specific runner images."
           },
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 289
+            "line": 295
           },
           "name": "imageBuilder",
           "parameters": [
@@ -6457,7 +6600,7 @@
           ],
           "returns": {
             "type": {
-              "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageBuilder"
+              "fqn": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder"
             }
           },
           "static": true
@@ -6470,7 +6613,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 395
+            "line": 401
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6499,7 +6642,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 493
+            "line": 499
           },
           "name": "grantStateMachine",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6568,7 +6711,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 523
+            "line": 529
           },
           "name": "status",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6597,7 +6740,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 545
+            "line": 551
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -6613,7 +6756,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 315
+            "line": 321
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -6629,7 +6772,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 310
+            "line": 316
           },
           "name": "labels",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6651,7 +6794,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 322
+            "line": 328
           },
           "name": "logGroup",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6667,7 +6810,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ec2.ts",
-            "line": 324
+            "line": 330
           },
           "name": "retryableErrors",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6951,7 +7094,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/ecs.ts",
-          "line": 321
+          "line": 327
         },
         "parameters": [
           {
@@ -6986,13 +7129,13 @@
       "methods": [
         {
           "docs": {
-            "remarks": "Included components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.docker()`\n * `RunnerImageComponent.githubRunner()`",
+            "remarks": "You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props.\n\nYou can add components to the image builder by calling `imageBuilder.addComponent()`.\n\nThe default OS is Ubuntu running on x64 architecture.\n\nIncluded components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.docker()`\n * `RunnerImageComponent.githubRunner()`",
             "stability": "experimental",
-            "summary": "Create new image builder that builds ECS specific runner images using Ubuntu."
+            "summary": "Create new image builder that builds ECS specific runner images."
           },
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 225
+            "line": 231
           },
           "name": "imageBuilder",
           "parameters": [
@@ -7018,7 +7161,7 @@
           ],
           "returns": {
             "type": {
-              "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageBuilder"
+              "fqn": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder"
             }
           },
           "static": true
@@ -7031,7 +7174,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 534
+            "line": 540
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7060,7 +7203,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 586
+            "line": 592
           },
           "name": "grantStateMachine",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7129,7 +7272,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 589
+            "line": 595
           },
           "name": "status",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7158,7 +7301,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 290
+            "line": 296
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -7174,7 +7317,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 285
+            "line": 291
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -7190,7 +7333,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 265
+            "line": 271
           },
           "name": "labels",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7212,7 +7355,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 302
+            "line": 308
           },
           "name": "logGroup",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7228,7 +7371,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/ecs.ts",
-            "line": 314
+            "line": 320
           },
           "name": "retryableErrors",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7622,7 +7765,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/fargate.ts",
-          "line": 364
+          "line": 370
         },
         "parameters": [
           {
@@ -7649,7 +7792,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/fargate.ts",
-        "line": 532
+        "line": 538
       },
       "name": "FargateRunner",
       "symbolId": "src/providers/fargate:FargateRunner"
@@ -7669,7 +7812,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/fargate.ts",
-          "line": 364
+          "line": 370
         },
         "parameters": [
           {
@@ -7704,13 +7847,13 @@
       "methods": [
         {
           "docs": {
-            "remarks": "Included components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.githubRunner()`",
+            "remarks": "You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props.\n\nYou can add components to the image builder by calling `imageBuilder.addComponent()`.\n\nThe default OS is Ubuntu running on x64 architecture.\n\nIncluded components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.githubRunner()`",
             "stability": "experimental",
-            "summary": "Create new image builder that builds Fargate specific runner images using Ubuntu."
+            "summary": "Create new image builder that builds Fargate specific runner images."
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 278
+            "line": 284
           },
           "name": "imageBuilder",
           "parameters": [
@@ -7736,7 +7879,7 @@
           ],
           "returns": {
             "type": {
-              "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageBuilder"
+              "fqn": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder"
             }
           },
           "static": true
@@ -7749,7 +7892,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 451
+            "line": 457
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7778,7 +7921,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 507
+            "line": 513
           },
           "name": "grantStateMachine",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7847,7 +7990,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 510
+            "line": 516
           },
           "name": "status",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7914,7 +8057,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 327
+            "line": 333
           },
           "name": "assignPublicIp",
           "type": {
@@ -7929,7 +8072,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 297
+            "line": 303
           },
           "name": "cluster",
           "type": {
@@ -7944,7 +8087,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 337
+            "line": 343
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -7960,7 +8103,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 307
+            "line": 313
           },
           "name": "container",
           "type": {
@@ -7975,7 +8118,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 332
+            "line": 338
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -7992,7 +8135,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 347
+            "line": 353
           },
           "name": "image",
           "type": {
@@ -8007,7 +8150,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 312
+            "line": 318
           },
           "name": "labels",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -8029,7 +8172,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 354
+            "line": 360
           },
           "name": "logGroup",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -8045,7 +8188,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 356
+            "line": 362
           },
           "name": "retryableErrors",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -8066,7 +8209,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 342
+            "line": 348
           },
           "name": "spot",
           "type": {
@@ -8081,7 +8224,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 302
+            "line": 308
           },
           "name": "task",
           "type": {
@@ -8096,7 +8239,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 322
+            "line": 328
           },
           "name": "subnetSelection",
           "optional": true,
@@ -8112,7 +8255,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 317
+            "line": 323
           },
           "name": "vpc",
           "optional": true,
@@ -8412,7 +8555,7 @@
         },
         "locationInModule": {
           "filename": "src/runner.ts",
-          "line": 260
+          "line": 269
         },
         "parameters": [
           {
@@ -8442,7 +8585,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 234
+        "line": 243
       },
       "methods": [
         {
@@ -8453,7 +8596,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 771
+            "line": 781
           },
           "name": "createLogsInsightsQueries"
         },
@@ -8465,7 +8608,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 751
+            "line": 761
           },
           "name": "failedImageBuildsTopic",
           "returns": {
@@ -8482,7 +8625,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 733
+            "line": 743
           },
           "name": "metricFailed",
           "parameters": [
@@ -8508,7 +8651,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 678
+            "line": 688
           },
           "name": "metricJobCompleted",
           "parameters": [
@@ -8534,7 +8677,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 724
+            "line": 734
           },
           "name": "metricSucceeded",
           "parameters": [
@@ -8560,7 +8703,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 740
+            "line": 750
           },
           "name": "metricTime",
           "parameters": [
@@ -8590,7 +8733,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 250
+            "line": 259
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -8606,7 +8749,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 238
+            "line": 247
           },
           "name": "providers",
           "type": {
@@ -8626,7 +8769,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 243
+            "line": 252
           },
           "name": "secrets",
           "type": {
@@ -8640,7 +8783,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 260
+            "line": 269
           },
           "name": "props",
           "optional": true,
@@ -8677,7 +8820,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 70
+            "line": 79
           },
           "name": "allowPublicSubnet",
           "optional": true,
@@ -8695,7 +8838,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 107
+            "line": 116
           },
           "name": "extraCertificates",
           "optional": true,
@@ -8714,7 +8857,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 114
+            "line": 123
           },
           "name": "idleTimeout",
           "optional": true,
@@ -8732,7 +8875,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 121
+            "line": 130
           },
           "name": "logOptions",
           "optional": true,
@@ -8764,6 +8907,25 @@
             }
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "true",
+            "remarks": "If `true`, the runner will only start if the workflow job explicitly requests the `self-hosted` label.\n\nBe careful when setting this to `false`. Avoid setting up providers with generic label requirements like `linux` as they may match workflows that are not meant to run on self-hosted runners.",
+            "stability": "experimental",
+            "summary": "Whether to require the `self-hosted` label."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/runner.ts",
+            "line": 53
+          },
+          "name": "requireSelfHostedLabel",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -8775,7 +8937,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 158
+            "line": 167
           },
           "name": "retryOptions",
           "optional": true,
@@ -8794,7 +8956,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 77
+            "line": 86
           },
           "name": "securityGroup",
           "optional": true,
@@ -8812,7 +8974,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 82
+            "line": 91
           },
           "name": "securityGroups",
           "optional": true,
@@ -8836,7 +8998,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 128
+            "line": 137
           },
           "name": "setupAccess",
           "optional": true,
@@ -8855,7 +9017,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 147
+            "line": 156
           },
           "name": "statusAccess",
           "optional": true,
@@ -8873,7 +9035,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 58
+            "line": 67
           },
           "name": "vpc",
           "optional": true,
@@ -8891,7 +9053,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 63
+            "line": 72
           },
           "name": "vpcSubnets",
           "optional": true,
@@ -8910,7 +9072,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 140
+            "line": 149
           },
           "name": "webhookAccess",
           "optional": true,
@@ -8921,6 +9083,77 @@
       ],
       "symbolId": "src/runner:GitHubRunnersProps"
     },
+    "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder": {
+      "assembly": "@cloudsnorkel/cdk-github-runners",
+      "docs": {
+        "remarks": "The image can be configured by adding or removing components. The image builder can be configured by adding grants or allowing connections.\n\nAn image can be a Docker image or AMI.",
+        "stability": "experimental",
+        "summary": "Interface for constructs that build an image that can be used in {@link IRunnerProvider }."
+      },
+      "fqn": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder",
+      "interfaces": [
+        "@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder",
+        "aws-cdk-lib.aws_ec2.IConnectable",
+        "aws-cdk-lib.aws_iam.IGrantable"
+      ],
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/image-builders/common.ts",
+        "line": 286
+      },
+      "methods": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "The component will be added to the end of the list of components.",
+            "stability": "experimental",
+            "summary": "Add a component to the image builder."
+          },
+          "locationInModule": {
+            "filename": "src/image-builders/common.ts",
+            "line": 292
+          },
+          "name": "addComponent",
+          "parameters": [
+            {
+              "docs": {
+                "summary": "component to add."
+              },
+              "name": "component",
+              "type": {
+                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageComponent"
+              }
+            }
+          ]
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Removal is done by component name. Multiple components with the same name will all be removed.",
+            "stability": "experimental",
+            "summary": "Remove a component from the image builder."
+          },
+          "locationInModule": {
+            "filename": "src/image-builders/common.ts",
+            "line": 299
+          },
+          "name": "removeComponent",
+          "parameters": [
+            {
+              "docs": {
+                "summary": "component to remove."
+              },
+              "name": "component",
+              "type": {
+                "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageComponent"
+              }
+            }
+          ]
+        }
+      ],
+      "name": "IConfigurableRunnerImageBuilder",
+      "symbolId": "src/image-builders/common:IConfigurableRunnerImageBuilder"
+    },
     "@cloudsnorkel/cdk-github-runners.IRunnerAmiStatus": {
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "docs": {
@@ -9431,7 +9664,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/image-builders/aws-image-builder/builder.ts",
-        "line": 45
+        "line": 43
       },
       "name": "ImageBuilderAsset",
       "properties": [
@@ -9444,7 +9677,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 54
+            "line": 52
           },
           "name": "asset",
           "type": {
@@ -9460,7 +9693,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 49
+            "line": 47
           },
           "name": "path",
           "type": {
@@ -9486,7 +9719,7 @@
         },
         "locationInModule": {
           "filename": "src/image-builders/aws-image-builder/builder.ts",
-          "line": 128
+          "line": 126
         },
         "parameters": [
           {
@@ -9512,9 +9745,45 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/image-builders/aws-image-builder/builder.ts",
-        "line": 115
+        "line": 113
       },
       "methods": [
+        {
+          "docs": {
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "src/image-builders/aws-image-builder/common.ts",
+            "line": 15
+          },
+          "name": "generateVersion",
+          "parameters": [
+            {
+              "name": "type",
+              "type": {
+                "primitive": "string"
+              }
+            },
+            {
+              "name": "name",
+              "type": {
+                "primitive": "string"
+              }
+            },
+            {
+              "name": "data",
+              "type": {
+                "primitive": "any"
+              }
+            }
+          ],
+          "protected": true,
+          "returns": {
+            "type": {
+              "primitive": "string"
+            }
+          }
+        },
         {
           "docs": {
             "stability": "deprecated",
@@ -9522,7 +9791,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 230
+            "line": 228
           },
           "name": "grantAssetsRead",
           "parameters": [
@@ -9540,7 +9809,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 236
+            "line": 234
           },
           "name": "prefixCommandsWithErrorHandling",
           "parameters": [
@@ -9572,42 +9841,6 @@
               }
             }
           }
-        },
-        {
-          "docs": {
-            "stability": "deprecated"
-          },
-          "locationInModule": {
-            "filename": "src/image-builders/aws-image-builder/common.ts",
-            "line": 15
-          },
-          "name": "version",
-          "parameters": [
-            {
-              "name": "type",
-              "type": {
-                "primitive": "string"
-              }
-            },
-            {
-              "name": "name",
-              "type": {
-                "primitive": "string"
-              }
-            },
-            {
-              "name": "data",
-              "type": {
-                "primitive": "any"
-              }
-            }
-          ],
-          "protected": true,
-          "returns": {
-            "type": {
-              "primitive": "string"
-            }
-          }
         }
       ],
       "name": "ImageBuilderComponent",
@@ -9620,7 +9853,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 119
+            "line": 117
           },
           "name": "arn",
           "type": {
@@ -9635,7 +9868,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 124
+            "line": 122
           },
           "name": "platform",
           "type": {
@@ -9656,7 +9889,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/image-builders/aws-image-builder/builder.ts",
-        "line": 60
+        "line": 58
       },
       "name": "ImageBuilderComponentProperties",
       "properties": [
@@ -9670,7 +9903,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 81
+            "line": 79
           },
           "name": "commands",
           "type": {
@@ -9691,7 +9924,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 74
+            "line": 72
           },
           "name": "description",
           "type": {
@@ -9707,7 +9940,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 69
+            "line": 67
           },
           "name": "displayName",
           "type": {
@@ -9724,7 +9957,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 64
+            "line": 62
           },
           "name": "platform",
           "type": {
@@ -9740,7 +9973,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 86
+            "line": 84
           },
           "name": "assets",
           "optional": true,
@@ -9763,7 +9996,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/aws-image-builder/builder.ts",
-            "line": 93
+            "line": 91
           },
           "name": "reboot",
           "optional": true,
@@ -9936,7 +10169,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/lambda.ts",
-          "line": 229
+          "line": 235
         },
         "parameters": [
           {
@@ -9963,7 +10196,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/lambda.ts",
-        "line": 462
+        "line": 468
       },
       "name": "LambdaRunner",
       "symbolId": "src/providers/lambda:LambdaRunner"
@@ -9983,7 +10216,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/lambda.ts",
-          "line": 229
+          "line": 235
         },
         "parameters": [
           {
@@ -10018,13 +10251,13 @@
       "methods": [
         {
           "docs": {
-            "remarks": "Included components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.githubRunner()`\n * `RunnerImageComponent.lambdaEntrypoint()`\n\n Base Docker image: `public.ecr.aws/lambda/nodejs:16-x86_64` or `public.ecr.aws/lambda/nodejs:16-arm64`",
+            "remarks": "You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props.\n\nYou can add components to the image builder by calling `imageBuilder.addComponent()`.\n\nThe default OS is Amazon Linux 2 running on x64 architecture.\n\nIncluded components:\n * `RunnerImageComponent.requiredPackages()`\n * `RunnerImageComponent.runnerUser()`\n * `RunnerImageComponent.git()`\n * `RunnerImageComponent.githubCli()`\n * `RunnerImageComponent.awsCli()`\n * `RunnerImageComponent.githubRunner()`\n * `RunnerImageComponent.lambdaEntrypoint()`\n\n Base Docker image: `public.ecr.aws/lambda/nodejs:16-x86_64` or `public.ecr.aws/lambda/nodejs:16-arm64`",
             "stability": "experimental",
-            "summary": "Create new image builder that builds Lambda specific runner images using Amazon Linux 2."
+            "summary": "Create new image builder that builds Lambda specific runner images."
           },
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 163
+            "line": 169
           },
           "name": "imageBuilder",
           "parameters": [
@@ -10050,7 +10283,7 @@
           ],
           "returns": {
             "type": {
-              "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageBuilder"
+              "fqn": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder"
             }
           },
           "static": true
@@ -10063,7 +10296,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 317
+            "line": 323
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -10092,7 +10325,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 379
+            "line": 385
           },
           "name": "grantStateMachine",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -10161,7 +10394,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 382
+            "line": 388
           },
           "name": "status",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -10228,7 +10461,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 306
+            "line": 312
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -10244,7 +10477,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 194
+            "line": 200
           },
           "name": "function",
           "type": {
@@ -10259,7 +10492,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 204
+            "line": 210
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -10276,7 +10509,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 209
+            "line": 215
           },
           "name": "image",
           "type": {
@@ -10291,7 +10524,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 199
+            "line": 205
           },
           "name": "labels",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -10313,7 +10546,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 216
+            "line": 222
           },
           "name": "logGroup",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -10329,7 +10562,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 218
+            "line": 224
           },
           "name": "retryableErrors",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -10890,7 +11123,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 164
+        "line": 173
       },
       "name": "LogOptions",
       "properties": [
@@ -10904,7 +11137,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 175
+            "line": 184
           },
           "name": "includeExecutionData",
           "optional": true,
@@ -10922,7 +11155,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 182
+            "line": 191
           },
           "name": "level",
           "optional": true,
@@ -10939,7 +11172,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 168
+            "line": 177
           },
           "name": "logGroupName",
           "optional": true,
@@ -10958,7 +11191,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 191
+            "line": 200
           },
           "name": "logRetention",
           "optional": true,
@@ -11506,7 +11739,7 @@
         },
         "locationInModule": {
           "filename": "src/image-builders/common.ts",
-          "line": 287
+          "line": 308
         },
         "parameters": [
           {
@@ -11532,9 +11765,7 @@
         "protected": true
       },
       "interfaces": [
-        "aws-cdk-lib.aws_ec2.IConnectable",
-        "aws-cdk-lib.aws_iam.IGrantable",
-        "@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder"
+        "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder"
       ],
       "kind": "class",
       "locationInModule": {
@@ -11576,7 +11807,7 @@
           ],
           "returns": {
             "type": {
-              "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageBuilder"
+              "fqn": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder"
             }
           },
           "static": true
@@ -11589,14 +11820,12 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/common.ts",
-            "line": 307
+            "line": 323
           },
           "name": "addComponent",
+          "overrides": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder",
           "parameters": [
             {
-              "docs": {
-                "summary": "component to add."
-              },
               "name": "component",
               "type": {
                 "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageComponent"
@@ -11613,7 +11842,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/common.ts",
-            "line": 297
+            "line": 318
           },
           "name": "bindAmi",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder",
@@ -11632,7 +11861,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/common.ts",
-            "line": 295
+            "line": 316
           },
           "name": "bindDockerImage",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder",
@@ -11650,14 +11879,12 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/common.ts",
-            "line": 316
+            "line": 327
           },
           "name": "removeComponent",
+          "overrides": "@cloudsnorkel/cdk-github-runners.IConfigurableRunnerImageBuilder",
           "parameters": [
             {
-              "docs": {
-                "summary": "component to remove."
-              },
               "name": "component",
               "type": {
                 "fqn": "@cloudsnorkel/cdk-github-runners.RunnerImageComponent"
@@ -11677,7 +11904,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/common.ts",
-            "line": 299
+            "line": 320
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -11694,7 +11921,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/image-builders/common.ts",
-            "line": 300
+            "line": 321
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -11708,7 +11935,7 @@
           },
           "locationInModule": {
             "filename": "src/image-builders/common.ts",
-            "line": 285
+            "line": 306
           },
           "name": "components",
           "protected": true,
@@ -12452,7 +12679,7 @@
         {
           "abstract": true,
           "docs": {
-            "remarks": "Used to identify component in image build logs, and for {@link RunnerImageBuilder.removeComponent }",
+            "remarks": "Used to identify component in image build logs, and for {@link IConfigurableRunnerImageBuilder.removeComponent }",
             "stability": "experimental",
             "summary": "Component name."
           },
@@ -12555,7 +12782,7 @@
           "docs": {
             "remarks": "Name must only contain alphanumeric characters and dashes.",
             "stability": "experimental",
-            "summary": "Component name used for (1) image build logging and (2) identifier for {@link ImageRunnerBuilder.removeComponent }."
+            "summary": "Component name used for (1) image build logging and (2) identifier for {@link IConfigurableRunnerImageBuilder.removeComponent }."
           },
           "immutable": true,
           "locationInModule": {
@@ -13359,6 +13586,6 @@
       "symbolId": "src/image-builders/aws-image-builder/deprecated/windows-components:WindowsComponents"
     }
   },
-  "version": "0.11.5",
-  "fingerprint": "xvADLqE6lSSIwGoQiUhMIzmSH7uiKJnt0XAMeLdp1OE="
+  "version": "0.12.0",
+  "fingerprint": "AbRJQzeZ4BxSiUye4iKkm/ovoIAoXNQ5jbyM6AttHNs="
 }