@cloudsnorkel/cdk-github-runners 0.14.18 → 0.14.20

package/API.md

@@ -797,7 +797,7 @@ Grant principal used to add permissions to the runner role.
 
 ##### ~~`image`~~<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.CodeBuildRunner.property.image"></a>
 
-- *Deprecated:* use {@link CodeBuildRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly image: RunnerImage;
@@ -1175,7 +1175,9 @@ Grant principal used to add permissions to the runner role.
 
 ---
 
-##### `image`<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProvider.property.image"></a>
+##### ~~`image`~~<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProvider.property.image"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly image: RunnerImage;
@@ -2318,6 +2320,7 @@ Included components:
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProvider.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProvider.property.capacityProvider">capacityProvider</a></code> | <code>aws-cdk-lib.aws_ecs.AsgCapacityProvider</code> | Capacity provider used to scale the cluster. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProvider.property.connections">connections</a></code> | <code>aws-cdk-lib.aws_ec2.Connections</code> | The network connections associated with this resource. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProvider.property.grantPrincipal">grantPrincipal</a></code> | <code>aws-cdk-lib.aws_iam.IPrincipal</code> | Grant principal used to add permissions to the runner role. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.EcsRunnerProvider.property.labels">labels</a></code> | <code>string[]</code> | Labels associated with this provider. |
@@ -2338,6 +2341,20 @@ The tree node.
 
 ---
 
+##### `capacityProvider`<sup>Required</sup> <a name="capacityProvider" id="@cloudsnorkel/cdk-github-runners.EcsRunnerProvider.property.capacityProvider"></a>
+
+```typescript
+public readonly capacityProvider: AsgCapacityProvider;
+```
+
+- *Type:* aws-cdk-lib.aws_ecs.AsgCapacityProvider
+
+Capacity provider used to scale the cluster.
+
+Use capacityProvider.autoScalingGroup to access the auto scaling group. This can help set up custom scaling policies.
+
+---
+
 ##### `connections`<sup>Required</sup> <a name="connections" id="@cloudsnorkel/cdk-github-runners.EcsRunnerProvider.property.connections"></a>
 
 ```typescript
@@ -2627,7 +2644,7 @@ The tree node.
 
 ##### ~~`assignPublicIp`~~<sup>Required</sup> <a name="assignPublicIp" id="@cloudsnorkel/cdk-github-runners.FargateRunner.property.assignPublicIp"></a>
 
-- *Deprecated:* use {@link FargateRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly assignPublicIp: boolean;
@@ -2669,7 +2686,7 @@ The network connections associated with this resource.
 
 ##### ~~`container`~~<sup>Required</sup> <a name="container" id="@cloudsnorkel/cdk-github-runners.FargateRunner.property.container"></a>
 
-- *Deprecated:* use {@link FargateRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly container: ContainerDefinition;
@@ -2697,7 +2714,7 @@ Grant principal used to add permissions to the runner role.
 
 ##### ~~`image`~~<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.FargateRunner.property.image"></a>
 
-- *Deprecated:* use {@link FargateRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly image: RunnerImage;
@@ -2757,7 +2774,7 @@ List of step functions errors that should be retried.
 
 ##### ~~`spot`~~<sup>Required</sup> <a name="spot" id="@cloudsnorkel/cdk-github-runners.FargateRunner.property.spot"></a>
 
-- *Deprecated:* use {@link FargateRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly spot: boolean;
@@ -2771,7 +2788,7 @@ Use spot pricing for Fargate tasks.
 
 ##### ~~`task`~~<sup>Required</sup> <a name="task" id="@cloudsnorkel/cdk-github-runners.FargateRunner.property.task"></a>
 
-- *Deprecated:* use {@link FargateRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly task: FargateTaskDefinition;
@@ -2785,7 +2802,7 @@ Fargate task hosting the runner.
 
 ##### ~~`subnetSelection`~~<sup>Optional</sup> <a name="subnetSelection" id="@cloudsnorkel/cdk-github-runners.FargateRunner.property.subnetSelection"></a>
 
-- *Deprecated:* use {@link FargateRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly subnetSelection: SubnetSelection;
@@ -2799,7 +2816,7 @@ Subnets used for hosting the runner task.
 
 ##### ~~`vpc`~~<sup>Optional</sup> <a name="vpc" id="@cloudsnorkel/cdk-github-runners.FargateRunner.property.vpc"></a>
 
-- *Deprecated:* use {@link FargateRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly vpc: IVpc;
@@ -3090,7 +3107,9 @@ The tree node.
 
 ---
 
-##### `assignPublicIp`<sup>Required</sup> <a name="assignPublicIp" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.assignPublicIp"></a>
+##### ~~`assignPublicIp`~~<sup>Required</sup> <a name="assignPublicIp" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.assignPublicIp"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly assignPublicIp: boolean;
@@ -3126,7 +3145,9 @@ The network connections associated with this resource.
 
 ---
 
-##### `container`<sup>Required</sup> <a name="container" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.container"></a>
+##### ~~`container`~~<sup>Required</sup> <a name="container" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.container"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly container: ContainerDefinition;
@@ -3150,7 +3171,9 @@ Grant principal used to add permissions to the runner role.
 
 ---
 
-##### `image`<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.image"></a>
+##### ~~`image`~~<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.image"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly image: RunnerImage;
@@ -3202,7 +3225,9 @@ List of step functions errors that should be retried.
 
 ---
 
-##### `spot`<sup>Required</sup> <a name="spot" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.spot"></a>
+##### ~~`spot`~~<sup>Required</sup> <a name="spot" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.spot"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly spot: boolean;
@@ -3214,7 +3239,9 @@ Use spot pricing for Fargate tasks.
 
 ---
 
-##### `task`<sup>Required</sup> <a name="task" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.task"></a>
+##### ~~`task`~~<sup>Required</sup> <a name="task" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.task"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly task: FargateTaskDefinition;
@@ -3226,7 +3253,9 @@ Fargate task hosting the runner.
 
 ---
 
-##### `subnetSelection`<sup>Optional</sup> <a name="subnetSelection" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.subnetSelection"></a>
+##### ~~`subnetSelection`~~<sup>Optional</sup> <a name="subnetSelection" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.subnetSelection"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly subnetSelection: SubnetSelection;
@@ -3238,7 +3267,9 @@ Subnets used for hosting the runner task.
 
 ---
 
-##### `vpc`<sup>Optional</sup> <a name="vpc" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.vpc"></a>
+##### ~~`vpc`~~<sup>Optional</sup> <a name="vpc" id="@cloudsnorkel/cdk-github-runners.FargateRunnerProvider.property.vpc"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly vpc: IVpc;
@@ -4162,7 +4193,7 @@ Grant principal used to add permissions to the runner role.
 
 ##### ~~`image`~~<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.LambdaRunner.property.image"></a>
 
-- *Deprecated:* use {@link LambdaRunnerProvider }
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly image: RunnerImage;
@@ -4530,7 +4561,9 @@ Grant principal used to add permissions to the runner role.
 
 ---
 
-##### `image`<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.LambdaRunnerProvider.property.image"></a>
+##### ~~`image`~~<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.LambdaRunnerProvider.property.image"></a>
+
+- *Deprecated:* This field is internal and should not be accessed directly.
 
 ```typescript
 public readonly image: RunnerImage;
@@ -5627,7 +5660,7 @@ const codeBuildRunnerImageBuilderProps: CodeBuildRunnerImageBuilderProps = { ...
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerImageBuilderProps.property.buildImage">buildImage</a></code> | <code>aws-cdk-lib.aws_codebuild.IBuildImage</code> | Build image to use in CodeBuild. |
-| <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerImageBuilderProps.property.computeType">computeType</a></code> | <code>aws-cdk-lib.aws_codebuild.ComputeType</code> | The type of compute to use for this build. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerImageBuilderProps.property.computeType">computeType</a></code> | <code>aws-cdk-lib.aws_codebuild.ComputeType</code> | The type of compute to use for this build. See the {@link ComputeType} enum for the possible values. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerImageBuilderProps.property.timeout">timeout</a></code> | <code>aws-cdk-lib.Duration</code> | The number of minutes after which AWS CodeBuild stops the build if it's not complete. |
 
 ---
@@ -5658,9 +5691,17 @@ public readonly computeType: ComputeType;
 - *Type:* aws-cdk-lib.aws_codebuild.ComputeType
 - *Default:* {@link ComputeType#SMALL }
 
-The type of compute to use for this build.
+The type of compute to use for this build. See the {@link ComputeType} enum for the possible values.
 
-See the {@link ComputeType} enum for the possible values.
+The compute type determines CPU, memory, and disk space:
+- SMALL: 2 vCPU, 3 GB RAM, 64 GB disk
+- MEDIUM: 4 vCPU, 7 GB RAM, 128 GB disk
+- LARGE: 8 vCPU, 15 GB RAM, 128 GB disk
+- X2_LARGE: 72 vCPU, 145 GB RAM, 256 GB disk (Linux) or 824 GB disk (Windows)
+
+Use a larger compute type when you need more disk space for building larger Docker images.
+
+For more details, see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html#environment.types
 
 ---
 
@@ -5697,7 +5738,7 @@ const codeBuildRunnerProviderProps: CodeBuildRunnerProviderProps = { ... }
 | <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. |
+| <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. See the {@link ComputeType} enum for the possible values. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.dockerInDocker">dockerInDocker</a></code> | <code>boolean</code> | Support building and running Docker images by enabling Docker-in-Docker (dind) and the required CodeBuild privileged mode. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.group">group</a></code> | <code>string</code> | GitHub Actions runner group name. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerProviderProps.property.imageBuilder">imageBuilder</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.IRunnerImageBuilder">IRunnerImageBuilder</a></code> | Runner image builder used to build Docker images containing GitHub Runner and all requirements. |
@@ -5764,9 +5805,17 @@ public readonly computeType: ComputeType;
 - *Type:* aws-cdk-lib.aws_codebuild.ComputeType
 - *Default:* {@link ComputeType#SMALL }
 
-The type of compute to use for this build.
+The type of compute to use for this build. See the {@link ComputeType} enum for the possible values.
 
-See the {@link ComputeType} enum for the possible values.
+The compute type determines CPU, memory, and disk space:
+- SMALL: 2 vCPU, 3 GB RAM, 64 GB disk
+- MEDIUM: 4 vCPU, 7 GB RAM, 128 GB disk
+- LARGE: 8 vCPU, 15 GB RAM, 128 GB disk
+- X2_LARGE: 72 vCPU, 145 GB RAM, 256 GB disk (Linux) or 824 GB disk (Windows)
+
+Use a larger compute type when you need more disk space for building larger Docker images.
+
+For more details, see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html#environment.types
 
 ---
 
@@ -7217,8 +7266,8 @@ const gitHubRunnersProps: GitHubRunnersProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
-| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.allowPublicSubnet">allowPublicSubnet</a></code> | <code>boolean</code> | Allow management functions to run in public subnets. |
-| <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.allowPublicSubnet">allowPublicSubnet</a></code> | <code>boolean</code> | Allow management functions to run in public subnets. Lambda Functions in a public subnet can NOT access the internet. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.extraCertificates">extraCertificates</a></code> | <code>string</code> | Path to a certificate file (.pem or .crt) or a directory containing certificate files (.pem or .crt) 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> \| <a href="#@cloudsnorkel/cdk-github-runners.ICompositeProvider">ICompositeProvider</a>[]</code> | List of runner providers to use. |
@@ -7244,9 +7293,9 @@ public readonly allowPublicSubnet: boolean;
 - *Type:* boolean
 - *Default:* false
 
-Allow management functions to run in public subnets.
+Allow management functions to run in public subnets. Lambda Functions in a public subnet can NOT access the internet.
 
-Lambda Functions in a public subnet can NOT access the internet.
+**Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting.
 
 ---
 
@@ -7258,13 +7307,16 @@ public readonly extraCertificates: string;
 
 - *Type:* string
 
-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.
+Path to a certificate file (.pem or .crt) or a directory containing certificate files (.pem or .crt) required to trust GitHub Enterprise Server. Use this when GitHub Enterprise Server certificates are self-signed.
 
-You may also want to use custom images for your runner providers that contain the same certificates. See {@link CodeBuildImageBuilder.addCertificates }.
+If a directory is provided, all .pem and .crt files in that directory will be used. The certificates will be concatenated into a single file for use by Node.js.
+
+You may also want to use custom images for your runner providers that contain the same certificates. See {@link RunnerImageComponent.extraCertificates }.
 
 ```typescript
+const selfSignedCertificates = 'certs/ghes.pem'; // or 'path-to-my-extra-certs-folder' for a directory
 const imageBuilder = CodeBuildRunnerProvider.imageBuilder(this, 'Image Builder with Certs');
-imageBuilder.addComponent(RunnerImageComponent.extraCertificates('path-to-my-extra-certs-folder/certs.pem', 'private-ca');
+imageBuilder.addComponent(RunnerImageComponent.extraCertificates(selfSignedCertificates, 'private-ca'));
 
 const provider = new CodeBuildRunnerProvider(this, 'CodeBuild', {
     imageBuilder: imageBuilder,
@@ -7275,7 +7327,7 @@ new GitHubRunners(
   'runners',
   {
     providers: [provider],
-    extraCertificates: 'path-to-my-extra-certs-folder',
+    extraCertificates: selfSignedCertificates,
   }
 );
 ```
@@ -7398,6 +7450,8 @@ Security group attached to all management functions.
 
 Use this with to provide access to GitHub Enterprise Server hosted inside a VPC.
 
+**Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting.
+
 ---
 
 ##### `securityGroups`<sup>Optional</sup> <a name="securityGroups" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.securityGroups"></a>
@@ -7410,7 +7464,11 @@ public readonly securityGroups: ISecurityGroup[];
 
 Security groups attached to all management functions.
 
-Use this with to provide access to GitHub Enterprise Server hosted inside a VPC.
+Use this to provide outbound access from management functions to GitHub Enterprise Server hosted inside a VPC.
+
+**Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting.
+
+**Note:** Defining inbound rules on this security group does nothing. This security group only controls outbound access FROM the management functions. To limit access TO the webhook or setup functions, use {@link webhookAccess} and {@link setupAccess} instead.
 
 ---
 
@@ -7454,6 +7512,8 @@ public readonly vpc: IVpc;
 
 VPC used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC.
 
+**Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting and will run outside the VPC.
+
 Make sure the selected VPC and subnets have access to the following with either NAT Gateway or VPC Endpoints:
 * GitHub Enterprise Server
 * Secrets Manager
@@ -7477,6 +7537,8 @@ VPC subnets used for all management functions.
 
 Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC.
 
+**Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting.
+
 ---
 
 ##### `webhookAccess`<sup>Optional</sup> <a name="webhookAccess" id="@cloudsnorkel/cdk-github-runners.GitHubRunnersProps.property.webhookAccess"></a>
@@ -8428,8 +8490,8 @@ const runnerImageBuilderProps: RunnerImageBuilderProps = { ... }
 | --- | --- | --- |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.architecture">architecture</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.Architecture">Architecture</a></code> | Image architecture. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.awsImageBuilderOptions">awsImageBuilderOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.AwsImageBuilderRunnerImageBuilderProps">AwsImageBuilderRunnerImageBuilderProps</a></code> | Options specific to AWS Image Builder. |
-| <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.baseAmi">baseAmi</a></code> | <code>string</code> | Base AMI from which runner AMIs will be built. |
-| <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.baseDockerImage">baseDockerImage</a></code> | <code>string</code> | Base image from which Docker runner images will be built. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.baseAmi">baseAmi</a></code> | <code>string \| <a href="#@cloudsnorkel/cdk-github-runners.BaseImage">BaseImage</a></code> | Base AMI from which runner AMIs will be built. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.baseDockerImage">baseDockerImage</a></code> | <code>string \| <a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage">BaseContainerImage</a></code> | Base image from which Docker runner images will be built. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.builderType">builderType</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderType">RunnerImageBuilderType</a></code> | *No description.* |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.codeBuildOptions">codeBuildOptions</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.CodeBuildRunnerImageBuilderProps">CodeBuildRunnerImageBuilderProps</a></code> | Options specific to CodeBuild image builder. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.components">components</a></code> | <code><a href="#@cloudsnorkel/cdk-github-runners.RunnerImageComponent">RunnerImageComponent</a>[]</code> | Components to install on the image. |
@@ -8476,29 +8538,47 @@ Only used when builderType is RunnerImageBuilderType.AWS_IMAGE_BUILDER.
 ##### `baseAmi`<sup>Optional</sup> <a name="baseAmi" id="@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.baseAmi"></a>
 
 ```typescript
-public readonly baseAmi: string;
+public readonly baseAmi: string | BaseImage;
 ```
 
-- *Type:* string
+- *Type:* string | <a href="#@cloudsnorkel/cdk-github-runners.BaseImage">BaseImage</a>
 - *Default:* latest Ubuntu 22.04 AMI for Os.LINUX_UBUNTU and Os.LINUX_UBUNTU_2204, Ubuntu 24.04 AMI for Os.LINUX_UBUNTU_2404, latest Amazon Linux 2 AMI for Os.LINUX_AMAZON_2, latest Windows Server 2022 AMI for Os.WINDOWS
 
 Base AMI from which runner AMIs will be built.
 
-This can be an actual AMI or an AWS Image Builder ARN that points to the latest AMI. For example `arn:aws:imagebuilder:us-east-1:aws:image/ubuntu-server-22-lts-x86/x.x.x` would always use the latest version of Ubuntu 22.04 in each build. If you want a specific version, you can replace `x.x.x` with that version.
+This can be:
+- A string (AMI ID, Image Builder ARN, SSM parameter reference, or Marketplace product ID) - deprecated, use BaseImage static factory methods instead
+- A BaseImage instance created using static factory methods:
+  - `BaseImage.fromAmiId('ami-12345')` - Use an AMI ID
+  - `BaseImage.fromString('arn:aws:imagebuilder:...')` - Use any string (ARN, AMI ID, etc.)
+  - `BaseImage.fromSsmParameter(parameter)` - Use an SSM parameter object
+  - `BaseImage.fromSsmParameterName('/aws/service/ami/...')` - Use an SSM parameter by name
+  - `BaseImage.fromMarketplaceProductId('product-id')` - Use a Marketplace product ID
+  - `BaseImage.fromImageBuilder(scope, 'ubuntu-server-22-lts-x86')` - Use an AWS-provided Image Builder image
+
+For example `BaseImage.fromImageBuilder(scope, 'ubuntu-server-22-lts-x86')` would always use the latest version of Ubuntu 22.04 in each build. If you want a specific version, you can pass the version as the third parameter.
 
 ---
 
 ##### `baseDockerImage`<sup>Optional</sup> <a name="baseDockerImage" id="@cloudsnorkel/cdk-github-runners.RunnerImageBuilderProps.property.baseDockerImage"></a>
 
 ```typescript
-public readonly baseDockerImage: string;
+public readonly baseDockerImage: string | BaseContainerImage;
 ```
 
-- *Type:* string
+- *Type:* string | <a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage">BaseContainerImage</a>
 - *Default:* public.ecr.aws/lts/ubuntu:22.04 for Os.LINUX_UBUNTU and Os.LINUX_UBUNTU_2204, public.ecr.aws/lts/ubuntu:24.04 for Os.LINUX_UBUNTU_2404, public.ecr.aws/amazonlinux/amazonlinux:2 for Os.LINUX_AMAZON_2, mcr.microsoft.com/windows/servercore:ltsc2019-amd64 for Os.WINDOWS
 
 Base image from which Docker runner images will be built.
 
+This can be:
+- A string (ECR/ECR public image URI, DockerHub image, or Image Builder ARN) - deprecated, use BaseContainerImage static factory methods instead
+- A BaseContainerImage instance created using static factory methods:
+  - `BaseContainerImage.fromDockerHub('ubuntu', '22.04')` - Use DockerHub
+  - `BaseContainerImage.fromEcr(repo, 'latest')` - Use ECR (automatically grants permissions with CodeBuild)
+  - `BaseContainerImage.fromEcrPublic('lts', 'ubuntu', '22.04')` - Use ECR Public
+  - `BaseContainerImage.fromString('public.ecr.aws/lts/ubuntu:22.04')` - Use any string
+
 When using private images from a different account or not on ECR, you may need to include additional setup commands with {@link dockerSetupCommands}.
 
 ---
@@ -9187,6 +9267,384 @@ X86_64.
 
 ---
 
+### BaseContainerImage <a name="BaseContainerImage" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage"></a>
+
+Represents a base container image that is used to start from in EC2 Image Builder container builds.
+
+This class is adapted from AWS CDK's BaseContainerImage class to support both string and object inputs.
+
+#### Initializers <a name="Initializers" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.Initializer"></a>
+
+```typescript
+import { BaseContainerImage } from '@cloudsnorkel/cdk-github-runners'
+
+new BaseContainerImage(image: string, ecrRepository?: IRepository)
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage.Initializer.parameter.image">image</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage.Initializer.parameter.ecrRepository">ecrRepository</a></code> | <code>aws-cdk-lib.aws_ecr.IRepository</code> | *No description.* |
+
+---
+
+##### `image`<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.Initializer.parameter.image"></a>
+
+- *Type:* string
+
+---
+
+##### `ecrRepository`<sup>Optional</sup> <a name="ecrRepository" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.Initializer.parameter.ecrRepository"></a>
+
+- *Type:* aws-cdk-lib.aws_ecr.IRepository
+
+---
+
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromDockerHub">fromDockerHub</a></code> | The DockerHub image to use as the base image in a container recipe. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcr">fromEcr</a></code> | The ECR container image to use as the base image in a container recipe. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcrPublic">fromEcrPublic</a></code> | The ECR public container image to use as the base image in a container recipe. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromString">fromString</a></code> | The string value of the base image to use in a container recipe. |
+
+---
+
+##### `fromDockerHub` <a name="fromDockerHub" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromDockerHub"></a>
+
+```typescript
+import { BaseContainerImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseContainerImage.fromDockerHub(repository: string, tag: string)
+```
+
+The DockerHub image to use as the base image in a container recipe.
+
+###### `repository`<sup>Required</sup> <a name="repository" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromDockerHub.parameter.repository"></a>
+
+- *Type:* string
+
+The DockerHub repository where the base image resides in.
+
+---
+
+###### `tag`<sup>Required</sup> <a name="tag" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromDockerHub.parameter.tag"></a>
+
+- *Type:* string
+
+The tag of the base image in the DockerHub repository.
+
+---
+
+##### `fromEcr` <a name="fromEcr" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcr"></a>
+
+```typescript
+import { BaseContainerImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseContainerImage.fromEcr(repository: IRepository, tag: string)
+```
+
+The ECR container image to use as the base image in a container recipe.
+
+###### `repository`<sup>Required</sup> <a name="repository" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcr.parameter.repository"></a>
+
+- *Type:* aws-cdk-lib.aws_ecr.IRepository
+
+The ECR repository where the base image resides in.
+
+---
+
+###### `tag`<sup>Required</sup> <a name="tag" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcr.parameter.tag"></a>
+
+- *Type:* string
+
+The tag of the base image in the ECR repository.
+
+---
+
+##### `fromEcrPublic` <a name="fromEcrPublic" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcrPublic"></a>
+
+```typescript
+import { BaseContainerImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseContainerImage.fromEcrPublic(registryAlias: string, repositoryName: string, tag: string)
+```
+
+The ECR public container image to use as the base image in a container recipe.
+
+###### `registryAlias`<sup>Required</sup> <a name="registryAlias" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcrPublic.parameter.registryAlias"></a>
+
+- *Type:* string
+
+The alias of the ECR public registry where the base image resides in.
+
+---
+
+###### `repositoryName`<sup>Required</sup> <a name="repositoryName" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcrPublic.parameter.repositoryName"></a>
+
+- *Type:* string
+
+The name of the ECR public repository, where the base image resides in.
+
+---
+
+###### `tag`<sup>Required</sup> <a name="tag" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromEcrPublic.parameter.tag"></a>
+
+- *Type:* string
+
+The tag of the base image in the ECR public repository.
+
+---
+
+##### `fromString` <a name="fromString" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromString"></a>
+
+```typescript
+import { BaseContainerImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseContainerImage.fromString(baseContainerImageString: string)
+```
+
+The string value of the base image to use in a container recipe.
+
+This can be an EC2 Image Builder image ARN,
+an ECR or ECR public image, or a container URI sourced from a third-party container registry such as DockerHub.
+
+###### `baseContainerImageString`<sup>Required</sup> <a name="baseContainerImageString" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.fromString.parameter.baseContainerImageString"></a>
+
+- *Type:* string
+
+The base image as a direct string value.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage.property.image">image</a></code> | <code>string</code> | The rendered base image to use. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseContainerImage.property.ecrRepository">ecrRepository</a></code> | <code>aws-cdk-lib.aws_ecr.IRepository</code> | The ECR repository if this image was created from an ECR repository. |
+
+---
+
+##### `image`<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.property.image"></a>
+
+```typescript
+public readonly image: string;
+```
+
+- *Type:* string
+
+The rendered base image to use.
+
+---
+
+##### `ecrRepository`<sup>Optional</sup> <a name="ecrRepository" id="@cloudsnorkel/cdk-github-runners.BaseContainerImage.property.ecrRepository"></a>
+
+```typescript
+public readonly ecrRepository: IRepository;
+```
+
+- *Type:* aws-cdk-lib.aws_ecr.IRepository
+
+The ECR repository if this image was created from an ECR repository.
+
+This allows automatic permission granting for CodeBuild.
+
+---
+
+
+### BaseImage <a name="BaseImage" id="@cloudsnorkel/cdk-github-runners.BaseImage"></a>
+
+Represents a base image that is used to start from in EC2 Image Builder image builds.
+
+This class is adapted from AWS CDK's BaseImage class to support both string and object inputs.
+
+#### Initializers <a name="Initializers" id="@cloudsnorkel/cdk-github-runners.BaseImage.Initializer"></a>
+
+```typescript
+import { BaseImage } from '@cloudsnorkel/cdk-github-runners'
+
+new BaseImage(image: string)
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseImage.Initializer.parameter.image">image</a></code> | <code>string</code> | *No description.* |
+
+---
+
+##### `image`<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.BaseImage.Initializer.parameter.image"></a>
+
+- *Type:* string
+
+---
+
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseImage.fromAmiId">fromAmiId</a></code> | The AMI ID to use as a base image in an image recipe. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseImage.fromImageBuilder">fromImageBuilder</a></code> | An AWS-provided EC2 Image Builder image to use as a base image in an image recipe. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseImage.fromMarketplaceProductId">fromMarketplaceProductId</a></code> | The marketplace product ID for an AMI product to use as the base image in an image recipe. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseImage.fromSsmParameter">fromSsmParameter</a></code> | The SSM parameter to use as the base image in an image recipe. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseImage.fromSsmParameterName">fromSsmParameterName</a></code> | The parameter name for the SSM parameter to use as the base image in an image recipe. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseImage.fromString">fromString</a></code> | The direct string value of the base image to use in an image recipe. |
+
+---
+
+##### `fromAmiId` <a name="fromAmiId" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromAmiId"></a>
+
+```typescript
+import { BaseImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseImage.fromAmiId(amiId: string)
+```
+
+The AMI ID to use as a base image in an image recipe.
+
+###### `amiId`<sup>Required</sup> <a name="amiId" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromAmiId.parameter.amiId"></a>
+
+- *Type:* string
+
+The AMI ID to use as the base image.
+
+---
+
+##### `fromImageBuilder` <a name="fromImageBuilder" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromImageBuilder"></a>
+
+```typescript
+import { BaseImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseImage.fromImageBuilder(scope: Construct, resourceName: string, version?: string)
+```
+
+An AWS-provided EC2 Image Builder image to use as a base image in an image recipe.
+
+This constructs an Image Builder ARN for AWS-provided images like `ubuntu-server-22-lts-x86/x.x.x`.
+
+###### `scope`<sup>Required</sup> <a name="scope" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromImageBuilder.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+The construct scope (used to determine the stack and region).
+
+---
+
+###### `resourceName`<sup>Required</sup> <a name="resourceName" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromImageBuilder.parameter.resourceName"></a>
+
+- *Type:* string
+
+The Image Builder resource name pattern (e.g., `ubuntu-server-22-lts-x86` or `ubuntu-server-22-lts-${arch}`).
+
+---
+
+###### `version`<sup>Optional</sup> <a name="version" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromImageBuilder.parameter.version"></a>
+
+- *Type:* string
+
+The version pattern (defaults to `x.x.x` to use the latest version).
+
+---
+
+##### `fromMarketplaceProductId` <a name="fromMarketplaceProductId" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromMarketplaceProductId"></a>
+
+```typescript
+import { BaseImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseImage.fromMarketplaceProductId(productId: string)
+```
+
+The marketplace product ID for an AMI product to use as the base image in an image recipe.
+
+###### `productId`<sup>Required</sup> <a name="productId" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromMarketplaceProductId.parameter.productId"></a>
+
+- *Type:* string
+
+The Marketplace AMI product ID to use as the base image.
+
+---
+
+##### `fromSsmParameter` <a name="fromSsmParameter" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromSsmParameter"></a>
+
+```typescript
+import { BaseImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseImage.fromSsmParameter(parameter: IParameter)
+```
+
+The SSM parameter to use as the base image in an image recipe.
+
+###### `parameter`<sup>Required</sup> <a name="parameter" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromSsmParameter.parameter.parameter"></a>
+
+- *Type:* aws-cdk-lib.aws_ssm.IParameter
+
+The SSM parameter to use as the base image.
+
+---
+
+##### `fromSsmParameterName` <a name="fromSsmParameterName" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromSsmParameterName"></a>
+
+```typescript
+import { BaseImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseImage.fromSsmParameterName(parameterName: string)
+```
+
+The parameter name for the SSM parameter to use as the base image in an image recipe.
+
+###### `parameterName`<sup>Required</sup> <a name="parameterName" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromSsmParameterName.parameter.parameterName"></a>
+
+- *Type:* string
+
+The name of the SSM parameter to use as the base image.
+
+---
+
+##### `fromString` <a name="fromString" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromString"></a>
+
+```typescript
+import { BaseImage } from '@cloudsnorkel/cdk-github-runners'
+
+BaseImage.fromString(baseImageString: string)
+```
+
+The direct string value of the base image to use in an image recipe.
+
+This can be an EC2 Image Builder image ARN,
+an SSM parameter, an AWS Marketplace product ID, or an AMI ID.
+
+###### `baseImageString`<sup>Required</sup> <a name="baseImageString" id="@cloudsnorkel/cdk-github-runners.BaseImage.fromString.parameter.baseImageString"></a>
+
+- *Type:* string
+
+The base image as a direct string value.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.BaseImage.property.image">image</a></code> | <code>string</code> | The rendered base image to use. |
+
+---
+
+##### `image`<sup>Required</sup> <a name="image" id="@cloudsnorkel/cdk-github-runners.BaseImage.property.image"></a>
+
+```typescript
+public readonly image: string;
+```
+
+- *Type:* string
+
+The rendered base image to use.
+
+---
+
+
 ### CompositeProvider <a name="CompositeProvider" id="@cloudsnorkel/cdk-github-runners.CompositeProvider"></a>
 
 A composite runner provider that implements fallback and distribution strategies.
@@ -10090,7 +10548,7 @@ This can be used to support GitHub Enterprise Server with self-signed certificat
 
 - *Type:* string
 
-path to certificate file in PEM format.
+path to certificate file in PEM format, or a directory containing certificate files (.pem or .crt).
 
 ---