@cloudsnorkel/cdk-github-runners 0.14.18 → 0.14.19

package/API.md

@@ -7217,8 +7217,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 +7244,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 +7258,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 +7278,7 @@ new GitHubRunners(
   'runners',
   {
     providers: [provider],
-    extraCertificates: 'path-to-my-extra-certs-folder',
+    extraCertificates: selfSignedCertificates,
   }
 );
 ```
@@ -7398,6 +7401,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 +7415,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 +7463,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 +7488,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 +8441,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 +8489,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 +9218,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 +10499,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).
 
 ---
 

package/README.md

@@ -447,9 +447,39 @@ const providerSelector = new Function(this, 'provider-selector', {
 
 ## Examples
 
-Beyond the code snippets above, the fullest example available is the [integration test](test/default.integ.ts).
+We provide comprehensive examples in the [`examples/`](examples/) folder to help you get started quickly:
 
-If you have more to share, please open a PR adding them to the `examples` folder.
+### Getting Started
+- **[Simple CodeBuild](examples/typescript/simple-codebuild/)** - Basic setup with just a CodeBuild provider (also available in [Python](examples/python/simple-codebuild/))
+
+### Provider Configuration
+- **[Composite Provider](examples/typescript/composite-provider/)** - Fallback and weighted distribution strategies (also available in [Python](examples/python/composite-provider/))
+- **[Provider Selector](examples/typescript/provider-selector/)** - Custom provider selection with Lambda function (also available in [Python](examples/python/provider-selector/))
+- **[EC2 Windows Provider](examples/typescript/ec2-windows-provider/)** - EC2 configuration for Windows runners (also available in [Python](examples/python/ec2-windows-provider/))
+
+### Compute & Performance
+- **[Compute Options](examples/typescript/compute-options/)** - Configure CPU, memory, and instance types for different providers (also available in [Python](examples/python/compute-options/))
+- **[Spot Instances](examples/typescript/spot-instances/)** - Use spot instances for cost savings across EC2, Fargate, and ECS (also available in [Python](examples/python/spot-instances/))
+- **[Storage Options](examples/typescript/storage-options/)** - Custom EBS storage options for EC2 runners (also available in [Python](examples/python/storage-options/))
+- **[ECS Scaling](examples/typescript/ecs-scaling/)** - Custom autoscaling group scaling policies for ECS providers (also available in [Python](examples/python/ecs-scaling/))
+
+### Security & Access
+- **[IAM Permissions](examples/typescript/iam-permissions/)** - Grant AWS IAM permissions to runners (also available in [Python](examples/python/iam-permissions/))
+- **[Network Access](examples/typescript/network-access/)** - Configure network access with VPCs and security groups (also available in [Python](examples/python/network-access/))
+- **[Access Control](examples/typescript/access-control/)** - Configure access control for webhook and setup functions (also available in [Python](examples/python/access-control/))
+
+### Customization
+- **[Add Software](examples/typescript/add-software/)** - Add custom software to runner images (also available in [Python](examples/python/add-software/))
+
+### Enterprise & Monitoring
+- **[GHES](examples/typescript/ghes/)** - Configure runners for GitHub Enterprise Server (also available in [Python](examples/python/ghes/))
+- **[Monitoring](examples/typescript/monitoring/)** - Set up CloudWatch alarms and SNS notifications (also available in [Python](examples/python/monitoring/))
+
+Each example is self-contained with its own dependencies and README. Start with the simple examples and work your way up to more advanced configurations.
+
+Another good and very full example is the [integration test](test/default.integ.ts).
+
+If you have more to share, please open a PR adding examples to the `examples` folder.
 
 ## Architecture
 

package/assets/providers/ami-root-device.lambda/index.js

@@ -106,6 +106,17 @@ async function handler(event, context) {
           await handleAmi(event, ssmValue);
           break;
         }
+        if (ami.startsWith("ssm:")) {
+          const ssmParam = ami.substring("ssm:".length);
+          console.log(`Checking SSM ${ssmParam}`);
+          const ssmValue = (await ssm.send(new import_client_ssm.GetParameterCommand({ Name: ssmParam }))).Parameter?.Value;
+          if (!ssmValue) {
+            await customResourceRespond(event, "FAILED", `${ami} has no value`, "ERROR", {});
+            break;
+          }
+          await handleAmi(event, ssmValue);
+          break;
+        }
         if (ami.startsWith("lt-")) {
           console.log(`Checking Launch Template ${ami}`);
           const lts = await ec2.send(new import_client_ec2.DescribeLaunchTemplateVersionsCommand({ LaunchTemplateId: ami, Versions: ["$Latest"] }));

package/lib/access.js

@@ -59,7 +59,7 @@ class LambdaAccess {
 }
 exports.LambdaAccess = LambdaAccess;
 _a = JSII_RTTI_SYMBOL_1;
-LambdaAccess[_a] = { fqn: "@cloudsnorkel/cdk-github-runners.LambdaAccess", version: "0.14.18" };
+LambdaAccess[_a] = { fqn: "@cloudsnorkel/cdk-github-runners.LambdaAccess", version: "0.14.19" };
 /**
  * @internal
  */

package/lib/image-builders/api.js

@@ -43,5 +43,5 @@ class RunnerImageBuilder extends common_1.RunnerImageBuilderBase {
 }
 exports.RunnerImageBuilder = RunnerImageBuilder;
 _a = JSII_RTTI_SYMBOL_1;
-RunnerImageBuilder[_a] = { fqn: "@cloudsnorkel/cdk-github-runners.RunnerImageBuilder", version: "0.14.18" };
+RunnerImageBuilder[_a] = { fqn: "@cloudsnorkel/cdk-github-runners.RunnerImageBuilder", version: "0.14.19" };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ltYWdlLWJ1aWxkZXJzL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7OztBQUFBLDZDQUEwQztBQUUxQywyREFBd0U7QUFDeEUsMkNBQTBEO0FBQzFELHFDQUFvSTtBQUNwSSw0Q0FBa0M7QUFFbEM7Ozs7OztHQU1HO0FBQ0gsTUFBc0Isa0JBQW1CLFNBQVEsK0JBQXNCO0lBQ3JFOztPQUVHO0lBQ0gsTUFBTSxDQUFDLEdBQUcsQ0FBQyxLQUFnQixFQUFFLEVBQVUsRUFBRSxLQUErQjtRQUN0RSxJQUFJLEtBQUssRUFBRSxVQUFVLElBQUksS0FBSyxDQUFDLGFBQWEsRUFBRSxDQUFDO1lBQzdDLHlCQUFXLENBQUMsRUFBRSxDQUFDLEtBQUssQ0FBQyxDQUFDLFVBQVUsQ0FBQyxrSEFBa0gsQ0FBQyxDQUFDO1FBQ3ZKLENBQUM7UUFFRCxJQUFJLEtBQUssRUFBRSxXQUFXLEtBQUssK0JBQXNCLENBQUMsVUFBVSxFQUFFLENBQUM7WUFDN0QsT0FBTyxJQUFJLHVDQUEyQixDQUFDLEtBQUssRUFBRSxFQUFFLEVBQUUsS0FBSyxDQUFDLENBQUM7UUFDM0QsQ0FBQzthQUFNLElBQUksS0FBSyxFQUFFLFdBQVcsS0FBSywrQkFBc0IsQ0FBQyxpQkFBaUIsRUFBRSxDQUFDO1lBQzNFLE9BQU8sSUFBSSxxREFBaUMsQ0FBQyxLQUFLLEVBQUUsRUFBRSxFQUFFLEtBQUssQ0FBQyxDQUFDO1FBQ2pFLENBQUM7UUFFRCxNQUFNLEVBQUUsR0FBRyxLQUFLLEVBQUUsRUFBRSxJQUFJLGNBQUUsQ0FBQyxZQUFZLENBQUM7UUFDeEMsSUFBSSxFQUFFLENBQUMsSUFBSSxDQUFDLGNBQUUsQ0FBQyxtQkFBbUIsQ0FBQyxFQUFFLENBQUM7WUFDcEMsT0FBTyxJQUFJLHVDQUEyQixDQUFDLEtBQUssRUFBRSxFQUFFLEVBQUUsS0FBSyxDQUFDLENBQUM7UUFDM0QsQ0FBQzthQUFNLElBQUksRUFBRSxDQUFDLEVBQUUsQ0FBQyxjQUFFLENBQUMsT0FBTyxDQUFDLEVBQUUsQ0FBQztZQUM3QixPQUFPLElBQUkscURBQWlDLENBQUMsS0FBSyxFQUFFLEVBQUUsRUFBRSxLQUFLLENBQUMsQ0FBQztRQUNqRSxDQUFDO2FBQU0sQ0FBQztZQUNOLE1BQU0sSUFBSSxLQUFLLENBQUMsMERBQTBELEVBQUUsQ0FBQyxJQUFJLEVBQUUsQ0FBQyxDQUFDO1FBQ3ZGLENBQUM7SUFDSCxDQUFDOztBQXZCSCxnREF3QkMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBBbm5vdGF0aW9ucyB9IGZyb20gJ2F3cy1jZGstbGliJztcbmltcG9ydCB7IENvbnN0cnVjdCB9IGZyb20gJ2NvbnN0cnVjdHMnO1xuaW1wb3J0IHsgQXdzSW1hZ2VCdWlsZGVyUnVubmVySW1hZ2VCdWlsZGVyIH0gZnJvbSAnLi9hd3MtaW1hZ2UtYnVpbGRlcic7XG5pbXBvcnQgeyBDb2RlQnVpbGRSdW5uZXJJbWFnZUJ1aWxkZXIgfSBmcm9tICcuL2NvZGVidWlsZCc7XG5pbXBvcnQgeyBJQ29uZmlndXJhYmxlUnVubmVySW1hZ2VCdWlsZGVyLCBSdW5uZXJJbWFnZUJ1aWxkZXJCYXNlLCBSdW5uZXJJbWFnZUJ1aWxkZXJQcm9wcywgUnVubmVySW1hZ2VCdWlsZGVyVHlwZSB9IGZyb20gJy4vY29tbW9uJztcbmltcG9ydCB7IE9zIH0gZnJvbSAnLi4vcHJvdmlkZXJzJztcblxuLyoqXG4gKiBHaXRIdWIgUnVubmVyIGltYWdlIGJ1aWxkZXIuIEJ1aWxkcyBhIERvY2tlciBpbWFnZSBvciBBTUkgd2l0aCBHaXRIdWIgUnVubmVyIGFuZCBvdGhlciByZXF1aXJlbWVudHMgaW5zdGFsbGVkLlxuICpcbiAqIEltYWdlcyBjYW4gYmUgY3VzdG9taXplZCBiZWZvcmUgcGFzc2VkIGludG8gdGhlIHByb3ZpZGVyIGJ5IGFkZGluZyBvciByZW1vdmluZyBjb21wb25lbnRzIHRvIGJlIGluc3RhbGxlZC5cbiAqXG4gKiBJbWFnZXMgYXJlIHJlYnVpbHQgZXZlcnkgd2VlayBieSBkZWZhdWx0IHRvIGVuc3VyZSB0aGF0IHRoZSBsYXRlc3Qgc2VjdXJpdHkgcGF0Y2hlcyBhcmUgYXBwbGllZC5cbiAqL1xuZXhwb3J0IGFic3RyYWN0IGNsYXNzIFJ1bm5lckltYWdlQnVpbGRlciBleHRlbmRzIFJ1bm5lckltYWdlQnVpbGRlckJhc2Uge1xuICAvKipcbiAgICogQ3JlYXRlIGEgbmV3IGltYWdlIGJ1aWxkZXIgYmFzZWQgb24gdGhlIHByb3ZpZGVkIHByb3BlcnRpZXMuIFRoZSBpbXBsZW1lbnRhdGlvbiB3aWxsIGRpZmZlciBiYXNlZCBvbiB0aGUgT1MsIGFyY2hpdGVjdHVyZSwgYW5kIHJlcXVlc3RlZCBidWlsZGVyIHR5cGUuXG4gICAqL1xuICBzdGF0aWMgbmV3KHNjb3BlOiBDb25zdHJ1Y3QsIGlkOiBzdHJpbmcsIHByb3BzPzogUnVubmVySW1hZ2VCdWlsZGVyUHJvcHMpOiBJQ29uZmlndXJhYmxlUnVubmVySW1hZ2VCdWlsZGVyIHtcbiAgICBpZiAocHJvcHM/LmNvbXBvbmVudHMgJiYgcHJvcHMucnVubmVyVmVyc2lvbikge1xuICAgICAgQW5ub3RhdGlvbnMub2Yoc2NvcGUpLmFkZFdhcm5pbmcoJ3J1bm5lclZlcnNpb24gaXMgaWdub3JlZCB3aGVuIGNvbXBvbmVudHMgYXJlIHNwZWNpZmllZC4gVGhlIHJ1bm5lciB2ZXJzaW9uIHdpbGwgYmUgZGV0ZXJtaW5lZCBieSB0aGUgY29tcG9uZW50cy4nKTtcbiAgICB9XG5cbiAgICBpZiAocHJvcHM/LmJ1aWxkZXJUeXBlID09PSBSdW5uZXJJbWFnZUJ1aWxkZXJUeXBlLkNPREVfQlVJTEQpIHtcbiAgICAgIHJldHVybiBuZXcgQ29kZUJ1aWxkUnVubmVySW1hZ2VCdWlsZGVyKHNjb3BlLCBpZCwgcHJvcHMpO1xuICAgIH0gZWxzZSBpZiAocHJvcHM/LmJ1aWxkZXJUeXBlID09PSBSdW5uZXJJbWFnZUJ1aWxkZXJUeXBlLkFXU19JTUFHRV9CVUlMREVSKSB7XG4gICAgICByZXR1cm4gbmV3IEF3c0ltYWdlQnVpbGRlclJ1bm5lckltYWdlQnVpbGRlcihzY29wZSwgaWQsIHByb3BzKTtcbiAgICB9XG5cbiAgICBjb25zdCBvcyA9IHByb3BzPy5vcyA/PyBPcy5MSU5VWF9VQlVOVFU7XG4gICAgaWYgKG9zLmlzSW4oT3MuX0FMTF9MSU5VWF9WRVJTSU9OUykpIHtcbiAgICAgIHJldHVybiBuZXcgQ29kZUJ1aWxkUnVubmVySW1hZ2VCdWlsZGVyKHNjb3BlLCBpZCwgcHJvcHMpO1xuICAgIH0gZWxzZSBpZiAob3MuaXMoT3MuV0lORE9XUykpIHtcbiAgICAgIHJldHVybiBuZXcgQXdzSW1hZ2VCdWlsZGVyUnVubmVySW1hZ2VCdWlsZGVyKHNjb3BlLCBpZCwgcHJvcHMpO1xuICAgIH0gZWxzZSB7XG4gICAgICB0aHJvdyBuZXcgRXJyb3IoYFVuYWJsZSB0byBmaW5kIHJ1bm5lciBpbWFnZSBidWlsZGVyIGltcGxlbWVudGF0aW9uIGZvciAke29zLm5hbWV9YCk7XG4gICAgfVxuICB9XG59XG4iXX0=