API reference

Constructs

GithubMicrovmRunners

A runner set: one deployment of GitHub Actions runners that run on AWS Lambda MicroVMs, with a fresh VM per job that is thrown away when the job ends.

The construct deploys a webhook handler for GitHub’s workflow_job deliveries, a queue those deliveries become launch and terminate intents on, a launcher that starts a VM and registers it with GitHub for each queued job, and a janitor that sweeps on a schedule for VMs and runners that outlived their job. Every runner class registered through addRunnerClass adds an image build of its own, and a runner set needs at least one class to synthesize.

Deploying it takes two props: how to authenticate to GitHub, and which GitHub scope the runners register into. The VMs themselves carry no AWS identity unless GithubMicrovmRunnersProps.vmExecutionRole gives them one.

Example

const runnerSet = new GithubMicrovmRunners(stack, 'Runners', {
  github: GithubAuth.app({
    appId: GithubAppId.fromSecret(
      Secret.fromSecretNameV2(stack, 'AppId', 'microvm-runner/dev/app-id'),
    ),
    privateKey: GithubAppKey.fromSecret(
      Secret.fromSecretNameV2(stack, 'AppKey', 'microvm-runner/dev/app-private-key'),
    ),
    webhookSecret: Secret.fromSecretNameV2(
      stack, 'WebhookSecret', 'microvm-runner/dev/webhook-secret',
    ),
  }),
  scope: RunnerScope.org('my-org'),
});

runnerSet.addRunnerClass('microvm', { size: MicrovmSize.GB4 });

Initializers

import { GithubMicrovmRunners } from 'cdk-github-microvm-runners'

new GithubMicrovmRunners(scope: Construct, id: string, props: GithubMicrovmRunnersProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`GithubMicrovmRunnersProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: GithubMicrovmRunnersProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`addRunnerClass`	Register a runner class: the `runs-on` label a workflow targets, paired with the VM size, and optionally the image, that jobs carrying that label run on.
`runnerClass`	The registered `RunnerClass` carrying `label`.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

`mixins`^Required

Type: …constructs.IMixin[]

The mixins to apply.

`addRunnerClass`

public addRunnerClass(label: string, props: RunnerClassProps): RunnerClass

Register a runner class: the runs-on label a workflow targets, paired with the VM size, and optionally the image, that jobs carrying that label run on.

Each class builds its own image. A runner set needs at least one class, and one that reaches synth with none fails.

Classes can be registered at any point before synth. Everything that depends on the full set of them — which labels the webhook accepts, which image each label launches, and the janitor’s access to each class’s image — is resolved once, after the last call.

Setting warmPoolSize on a class keeps that many pre-booted VMs ready for it. The first class to do so creates the warm-pool handler and its schedule, which every later warm class then shares.

`label`^Required

Type: string

the runs-on label workflows use to target this class.

`props`^Required

Type: RunnerClassProps

the VM size, and optionally the image, warm pool size, and idle policy for this class.

`runnerClass`

public runnerClass(label: string): RunnerClass

The registered RunnerClass carrying label.

Throws when no class with that label has been registered.

`label`^Required

Type: string

the runs-on label the class was registered under.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { GithubMicrovmRunners } from 'cdk-github-microvm-runners'

GithubMicrovmRunners.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`deadLetterQueue`	`aws-cdk-lib.aws_sqs.IQueue`	Dead-letter queue holding job-queue messages that ran out of redrives.
`defaultImageArn`	`string`	The image a job whose labels match no registered runner class launches on: the class labelled `microvm` if one is registered, otherwise the first class registered.
`janitorFunction`	`aws-cdk-lib.aws_lambda.IFunction`	The janitor Lambda, which runs the scheduled sweep.
`jobQueue`	`aws-cdk-lib.aws_sqs.IQueue`	Queue carrying launch and terminate intents from the webhook handler to the launcher.
`launcherFunction`	`aws-cdk-lib.aws_lambda.IFunction`	The launcher Lambda, which reads the job queue and starts and terminates MicroVMs.
`metrics`	`GithubMicrovmRunnersMetrics`	This runner set’s CloudWatch metrics and the ready-made alarms over them.
`runnerClasses`	`RunnerClass[]`	Every runner class registered through `addRunnerClass`, in the order they were registered.
`runnerTable`	`aws-cdk-lib.aws_dynamodb.ITable`	DynamoDB table mapping each runner’s name to its MicroVM, and holding the janitor’s record of which VMs it already suspects.
`setupCommand`	`string`	The command that creates this runner set’s GitHub App and writes its three secrets.
`webhookFunction`	`aws-cdk-lib.aws_lambda.IFunction`	The webhook Lambda, which GitHub’s deliveries reach through `webhookUrl`.
`webhookUrl`	`string`	The webhook handler’s public Function URL, which is the payload URL to configure on the GitHub App or webhook.
`vmConsoleLogGroup`	`aws-cdk-lib.aws_logs.ILogGroup`	Where a VM’s runtime console goes when console capture is on: the group the construct created, or the one you supplied.
`vmExecutionRole`	`aws-cdk-lib.aws_iam.IRole`	The AWS identity launched MicroVMs run with, passed in as `GithubMicrovmRunnersProps.vmExecutionRole`, or `undefined` when the VMs carry no AWS identity. Console capture runs on this role and requires it. A runner set identifies its own VMs by the image they booted from, not by this role.
`warmPoolFunction`	`aws-cdk-lib.aws_lambda.IFunction`	The Lambda that refills the warm pool, or `undefined` when no registered runner class sets `RunnerClassProps.warmPoolSize`. It is created by the first class that does, so a runner set with no warm class deploys neither this function nor its schedule.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`deadLetterQueue`^Required

public readonly deadLetterQueue: IQueue;

Type: aws-cdk-lib.aws_sqs.IQueue

Dead-letter queue holding job-queue messages that ran out of redrives.

`defaultImageArn`^Required

public readonly defaultImageArn: string;

Type: string

The image a job whose labels match no registered runner class launches on: the class labelled microvm if one is registered, otherwise the first class registered.

Runner classes can be added right up until synth, so this is a token that resolves once the set of them is final.

`janitorFunction`^Required

public readonly janitorFunction: IFunction;

Type: aws-cdk-lib.aws_lambda.IFunction

The janitor Lambda, which runs the scheduled sweep.

`jobQueue`^Required

public readonly jobQueue: IQueue;

Type: aws-cdk-lib.aws_sqs.IQueue

Queue carrying launch and terminate intents from the webhook handler to the launcher.

`launcherFunction`^Required

public readonly launcherFunction: IFunction;

Type: aws-cdk-lib.aws_lambda.IFunction

The launcher Lambda, which reads the job queue and starts and terminates MicroVMs.

`metrics`^Required

public readonly metrics: GithubMicrovmRunnersMetrics;

Type: GithubMicrovmRunnersMetrics

This runner set’s CloudWatch metrics and the ready-made alarms over them.

`runnerClasses`^Required

public readonly runnerClasses: RunnerClass[];

Type: RunnerClass[]

Every runner class registered through addRunnerClass, in the order they were registered.

It is empty until the first class is added, and a runner set that reaches synth with none fails. Each call returns a copy, so changing the returned array does not change the runner set.

`runnerTable`^Required

public readonly runnerTable: ITable;

Type: aws-cdk-lib.aws_dynamodb.ITable

DynamoDB table mapping each runner’s name to its MicroVM, and holding the janitor’s record of which VMs it already suspects.

`setupCommand`^Required

public readonly setupCommand: string;

Type: string

The command that creates this runner set’s GitHub App and writes its three secrets.

It carries the scope, the stack name, and the region this runner set was built with, and is pinned to the version of this library that produced it, so the helper and the construct agree about secret names and stack outputs.

Surface it as a stack output and the deploy ends by printing the line to paste. On a stack built without an explicit env, the region is a token that reads as ${Token[AWS.Region.N]} here and resolves to the real region in the deployed output.

Example

new cdk.CfnOutput(stack, 'SetupCommand', { value: runners.setupCommand });

`webhookFunction`^Required

public readonly webhookFunction: IFunction;

Type: aws-cdk-lib.aws_lambda.IFunction

The webhook Lambda, which GitHub’s deliveries reach through webhookUrl.

`webhookUrl`^Required

public readonly webhookUrl: string;

Type: string

The webhook handler’s public Function URL, which is the payload URL to configure on the GitHub App or webhook.

`vmConsoleLogGroup`^Optional

public readonly vmConsoleLogGroup: ILogGroup;

Type: aws-cdk-lib.aws_logs.ILogGroup

Where a VM’s runtime console goes when console capture is on: the group the construct created, or the one you supplied.

undefined when console capture is off.

`vmExecutionRole`^Optional

public readonly vmExecutionRole: IRole;

Type: aws-cdk-lib.aws_iam.IRole

The AWS identity launched MicroVMs run with, passed in as GithubMicrovmRunnersProps.vmExecutionRole, or undefined when the VMs carry no AWS identity. Console capture runs on this role and requires it. A runner set identifies its own VMs by the image they booted from, not by this role.

`warmPoolFunction`^Optional

public readonly warmPoolFunction: IFunction;

Type: aws-cdk-lib.aws_lambda.IFunction

The Lambda that refills the warm pool, or undefined when no registered runner class sets RunnerClassProps.warmPoolSize. It is created by the first class that does, so a runner set with no warm class deploys neither this function nor its schedule.

ImagePipeline

The build behind one runner class’s MicroVM image.

addRunnerClass creates one for each class it registers and returns it as RunnerClass.imagePipeline, so this is a handle you read rather than a construct you instantiate.

It stages the class’s Dockerfile and build context as a CDK asset, declares the AWS::Lambda::MicrovmImage resource that CloudFormation builds from it, and creates the IAM role that build runs as. Reading it is how you reach the built image’s name and ARN, and the role the build runs as.

Example

const buildClass = runners.addRunnerClass('build', {
  size: MicrovmSize.GB4,
  image: RunnerImage.fromOptions({ systemPackages: ['jq'] }),
});

new cdk.CfnOutput(stack, 'BuildImageName', {
  value: buildClass.imagePipeline.imageName,
});

Initializers

import { ImagePipeline } from 'cdk-github-microvm-runners'

new ImagePipeline(scope: Construct, id: string, props: ImagePipelineProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`ImagePipelineProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: ImagePipelineProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: …constructs.IMixin[]

The mixins to apply.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { ImagePipeline } from 'cdk-github-microvm-runners'

ImagePipeline.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`buildRole`	`aws-cdk-lib.aws_iam.IRole`	IAM role the image build runs as, able to read the staged build context and pull any private container base image.
`imageArn`	`string`	ARN of the built MicroVM image.
`imageName`	`string`	Name of the built MicroVM image — the per-class `runnerSetId`, stable for the life of the runner class.
`imageResource`	`aws-cdk-lib.aws_lambda.CfnMicrovmImage`	The underlying `AWS::Lambda::MicrovmImage` resource.
`imageVersion`	`string`	The image’s latest active version, which advances every time the image is rebuilt in place.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`buildRole`^Required

public readonly buildRole: IRole;

Type: aws-cdk-lib.aws_iam.IRole

IAM role the image build runs as, able to read the staged build context and pull any private container base image.

`imageArn`^Required

public readonly imageArn: string;

Type: string

ARN of the built MicroVM image.

`imageName`^Required

public readonly imageName: string;

Type: string

Name of the built MicroVM image — the per-class runnerSetId, stable for the life of the runner class.

`imageResource`^Required

public readonly imageResource: CfnMicrovmImage;

Type: aws-cdk-lib.aws_lambda.CfnMicrovmImage

The underlying AWS::Lambda::MicrovmImage resource.

`imageVersion`^Required

public readonly imageVersion: string;

Type: string

The image’s latest active version, which advances every time the image is rebuilt in place.

Structs

GithubAppAuthProps

Props for GithubAuth.app.

Initializer

import { GithubAppAuthProps } from 'cdk-github-microvm-runners'

const githubAppAuthProps: GithubAppAuthProps = { ... }

Properties

Name	Type	Description
`appId`	`GithubAppId`	The GitHub App’s numeric ID, as a literal or a Secrets Manager reference.
`privateKey`	`GithubAppKey`	The App’s private key, backed by a secret or a KMS key.
`webhookSecret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	Secret holding the webhook secret used to validate inbound deliveries.

`appId`^Required

public readonly appId: GithubAppId;

Type: GithubAppId

The GitHub App’s numeric ID, as a literal or a Secrets Manager reference.

`privateKey`^Required

public readonly privateKey: GithubAppKey;

Type: GithubAppKey

The App’s private key, backed by a secret or a KMS key.

`webhookSecret`^Required

public readonly webhookSecret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

Secret holding the webhook secret used to validate inbound deliveries.

GithubMicrovmRunnersProps

Props for GithubMicrovmRunners.

Initializer

import { GithubMicrovmRunnersProps } from 'cdk-github-microvm-runners'

const githubMicrovmRunnersProps: GithubMicrovmRunnersProps = { ... }

Properties

Name	Type	Description
`github`	`GithubAuth`	How the runner set authenticates to GitHub, as an App or with a personal access token.
`scope`	`RunnerScope`	Which GitHub scope, an organization or a list of repositories, registered runners are visible to.
`additionalRegions`	`string[]`	Additional regions to accept as Lambda MicroVMs regions, beyond the ones this library already knows about.
`consoleLogs`	`ConsoleLogs`	Where a VM’s runtime console goes: everything it prints while it boots, runs the runner agent, and runs the job.
`deadLetterRetention`	`aws-cdk-lib.Duration`	How long the dead-letter queue retains a failed launch or terminate intent.
`emitMetrics`	`boolean`	Report this runner set’s CloudWatch custom metrics.
`encryptionKey`	`aws-cdk-lib.aws_kms.IKey`	Customer-managed KMS key for this runner set’s data at rest: the DynamoDB runner table, the SQS job queue and dead-letter queue, and any log group this construct creates.
`idleRunnerGraceSeconds`	`number`	How many seconds a registered runner may sit idle before the janitor’s two-strike sweep treats it as stuck.
`imageLogs`	`ImageLogs`	Where build-time image logs go: the Docker build layers and the ready-probe banner from each image build.
`janitorInterval`	`aws-cdk-lib.Duration`	How often the janitor sweep runs.
`keepImageVersions`	`number`	How many MicroVM image versions to keep per runner class.
`lambdaMemorySize`	`number`	Memory, in MiB, for the handler Lambdas: the webhook, the launcher, the janitor, and the warm pool.
`logRetention`	`aws-cdk-lib.aws_logs.RetentionDays`	Retention for the CloudWatch log groups this construct creates: the handler Lambda log groups and, when console capture is on, the VM console group.
`maxConcurrentVms`	`number`	Maximum number of MicroVMs this runner set runs at once.
`maxJobDuration`	`aws-cdk-lib.Duration`	How long a job may run before its MicroVM is terminated.
`maxReceiveCount`	`number`	How many times a launch intent is redriven before it dead-letters.
`network`	`RunnerNetwork`	How launched MicroVMs and image builds reach the network.
`permissionsBoundary`	`aws-cdk-lib.aws_iam.IManagedPolicy`	Permissions boundary applied to every IAM role this construct creates: the handler execution roles, the per-class image build roles, and the network-connector operator role.
`pointInTimeRecovery`	`boolean`	Turn on DynamoDB point-in-time recovery for the runner table.
`recoverStuckLaunches`	`boolean`	Re-launch jobs that are still waiting for a runner they never got.
`removalPolicy`	`aws-cdk-lib.RemovalPolicy`	Removal policy for this runner set’s stateful resources: the runner table and any log group the construct creates.
`vmExecutionRole`	`aws-cdk-lib.aws_iam.IRole`	An AWS identity for this runner set’s runner VMs.
`warmPoolInterval`	`aws-cdk-lib.Duration`	How often the warm-pool sweep refills pre-booted VMs.
`webhook`	`WebhookEndpoint`	How the webhook handler is exposed to GitHub.
`webhookReservedConcurrency`	`number`	Reserved concurrency for the webhook Lambda, which caps how many webhook deliveries the runner set processes at once.

`github`^Required

public readonly github: GithubAuth;

Type: GithubAuth

How the runner set authenticates to GitHub, as an App or with a personal access token.

This also carries the webhook secret.

`scope`^Required

public readonly scope: RunnerScope;

Type: RunnerScope

Which GitHub scope, an organization or a list of repositories, registered runners are visible to.

`additionalRegions`^Optional

public readonly additionalRegions: string[];

Type: string[]
Default: [] (only the regions this library knows about)

Additional regions to accept as Lambda MicroVMs regions, beyond the ones this library already knows about.

Deploying into a region on neither list fails at synth.

`consoleLogs`^Optional

public readonly consoleLogs: ConsoleLogs;

Type: ConsoleLogs
Default: undefined (no runtime console capture)

Where a VM’s runtime console goes: everything it prints while it boots, runs the runner agent, and runs the job.

ConsoleLogs.enabled() has the construct create the group and expose it as vmConsoleLogGroup, and ConsoleLogs.enabled(logGroup) uses one you control. The platform writes these logs with the VM’s own role, so this requires vmExecutionRole; see ConsoleLogs for what that role means for job code. Independent of imageLogs.

`deadLetterRetention`^Optional

public readonly deadLetterRetention: Duration;

Type: aws-cdk-lib.Duration
Default: Duration.days(4) (SQS default)

How long the dead-letter queue retains a failed launch or terminate intent.

SQS allows up to 14 days, which is also how long recoverStuckLaunches has to re-drive a message before SQS drops it.

`emitMetrics`^Optional

public readonly emitMetrics: boolean;

Type: boolean
Default: false (no metrics emitted)

Report this runner set’s CloudWatch custom metrics.

Those are the janitor’s per-sweep counters, the launcher’s per-launch outcomes and spin-up timings, and the warm pool’s fill numbers — everything GithubMicrovmRunnersMetrics names. With this off the handlers report none of them.

CloudWatch bills custom metrics per metric per month, and this runner set’s bill is not a fixed number: the launcher and warm-pool metrics carry a runner-class dimension, so each one becomes a separate billable metric per registered runner class.

The two alarms backed by these metrics, sweepErrorsAlarm and stuckLaunchesRecoveredAlarm, throw at synth unless this is on, since the metric they watch would never report. deadLetterQueueNotEmptyAlarm watches an SQS metric and works either way. The metric accessors on GithubMicrovmRunnersMetrics return a Metric regardless, so a dashboard can be built ahead of turning metrics on.

`encryptionKey`^Optional

public readonly encryptionKey: IKey;

Type: aws-cdk-lib.aws_kms.IKey
Default: undefined (AWS-managed keys)

Customer-managed KMS key for this runner set’s data at rest: the DynamoDB runner table, the SQS job queue and dead-letter queue, and any log group this construct creates.

Log groups you bring yourself, and the GitHub secrets you pass in, keep their own keys.

`idleRunnerGraceSeconds`^Optional

public readonly idleRunnerGraceSeconds: number;

Type: number
Default: 600

How many seconds a registered runner may sit idle before the janitor’s two-strike sweep treats it as stuck.

`imageLogs`^Optional

public readonly imageLogs: ImageLogs;

Type: ImageLogs
Default: undefined (no image logs)

Where build-time image logs go: the Docker build layers and the ready-probe banner from each image build.

ImageLogs.enabled() sends them to the platform’s own CloudWatch group, and ImageLogs.enabled(logGroup) to a group whose retention and KMS key you control. These are written by the image build role rather than by a VM, so they need no VM execution role. Independent of consoleLogs.

`janitorInterval`^Optional

public readonly janitorInterval: Duration;

Type: aws-cdk-lib.Duration
Default: Duration.minutes(5)

How often the janitor sweep runs.

`keepImageVersions`^Optional

public readonly keepImageVersions: number;

Type: number
Default: 5

How many MicroVM image versions to keep per runner class.

The janitor prunes inactive versions past this count.

`lambdaMemorySize`^Optional

public readonly lambdaMemorySize: number;

Type: number
Default: 128

Memory, in MiB, for the handler Lambdas: the webhook, the launcher, the janitor, and the warm pool.

The janitor’s sweep scans the runner table and reconciles every running VM, so it is the handler most sensitive to this on a busy runner set.

`logRetention`^Optional

public readonly logRetention: RetentionDays;

Type: aws-cdk-lib.aws_logs.RetentionDays
Default: logs.RetentionDays.TWO_WEEKS

Retention for the CloudWatch log groups this construct creates: the handler Lambda log groups and, when console capture is on, the VM console group.

`maxConcurrentVms`^Optional

public readonly maxConcurrentVms: number;

Type: number
Default: 10

Maximum number of MicroVMs this runner set runs at once.

`maxJobDuration`^Optional

public readonly maxJobDuration: Duration;

Type: aws-cdk-lib.Duration
Default: Duration.hours(6)

How long a job may run before its MicroVM is terminated.

The VM is killed five minutes after this value, not at it. The runner set asks the platform for maxJobDuration + 5 minutes, so that a job which reaches its own limit is stopped by the runner — which reports the timeout to GitHub and lets the VM come down cleanly — rather than by the platform removing the machine underneath it. Treat the five minutes as headroom for that shutdown rather than as extra running time.

`maxReceiveCount`^Optional

public readonly maxReceiveCount: number;

Type: number
Default: 20

How many times a launch intent is redriven before it dead-letters.

A runner set already at maxConcurrentVms redrives capacity-rejected launches through this same budget, so on a runner set that regularly runs at capacity this count is how long a queued job waits before its launch is dropped. See docs/service-quotas.md.

`network`^Optional

public readonly network: RunnerNetwork;

Type: RunnerNetwork
Default: RunnerNetwork.internetEgress()

How launched MicroVMs and image builds reach the network.

`permissionsBoundary`^Optional

public readonly permissionsBoundary: IManagedPolicy;

Type: aws-cdk-lib.aws_iam.IManagedPolicy
Default: undefined (no boundary)

Permissions boundary applied to every IAM role this construct creates: the handler execution roles, the per-class image build roles, and the network-connector operator role.

It is applied once at construct scope, so roles created later also carry it — the warm-pool handler’s role, and the build role of any runner class registered after construction.

`pointInTimeRecovery`^Optional

public readonly pointInTimeRecovery: boolean;

Type: boolean
Default: false

Turn on DynamoDB point-in-time recovery for the runner table.

`recoverStuckLaunches`^Optional

public readonly recoverStuckLaunches: boolean;

Type: boolean
Default: true

Re-launch jobs that are still waiting for a runner they never got.

This is the floor under an event-driven plane, and it is on by default.

GitHub announces a job once. If the launch that announcement triggered doesn’t end with the job being served, nothing else ever asks again, and the job waits for as long as the workflow allows with no error anywhere — the plane looks healthy because by its own bookkeeping it did its work. Each janitor sweep closes that hole from two directions: it re-drives dead-lettered launch messages back onto the job queue, and it re-launches claims whose VM is gone while the job is still queued. Both check with GitHub first, so a job that has since completed or been cancelled is discarded rather than booting a VM for work nobody is waiting on.

Turn it off only if you want a job that slips through to stay stuck. The cost of leaving it on is one extra GitHub read per sweep per candidate, bounded per sweep so it cannot exhaust the installation’s rate limit.

The janitor counts recoveries under the stuckLaunchesRecovered and stuckClaimsRelaunched metrics, which report when emitMetrics is on. A count that stays high means launches are failing for some ongoing reason and the recovery is masking it — alarm on it rather than ignoring it.

`removalPolicy`^Optional

public readonly removalPolicy: RemovalPolicy;

Type: aws-cdk-lib.RemovalPolicy
Default: RemovalPolicy.DESTROY

Removal policy for this runner set’s stateful resources: the runner table and any log group the construct creates.

The table holds correlation data for VMs that are currently running, all of which the janitor can rebuild from the MicroVM and GitHub APIs.

`vmExecutionRole`^Optional

public readonly vmExecutionRole: IRole;

Type: aws-cdk-lib.aws_iam.IRole
Default: undefined (the VMs carry no AWS identity)

An AWS identity for this runner set’s runner VMs.

By default the VMs carry no AWS identity at all: the runner agent talks outbound to GitHub, the just-in-time registration is pushed to the VM over a platform-authenticated channel, and a job that needs AWS assumes its own role through GitHub OIDC.

With a role attached, the MicroVM’s instance metadata service serves that role’s credentials to arbitrary job code, so every job running on this runner set can do whatever the role can do. consoleLogs requires a role, because the platform writes a VM’s console output using it.

`warmPoolInterval`^Optional

public readonly warmPoolInterval: Duration;

Type: aws-cdk-lib.Duration
Default: Duration.minutes(2)

How often the warm-pool sweep refills pre-booted VMs.

It applies only to runner classes that set RunnerClassProps.warmPoolSize, and the warm-pool handler and its schedule are only created once such a class is registered. A runner set with no warm class never runs this sweep, and never reads this value.

`webhook`^Optional

public readonly webhook: WebhookEndpoint;

Type: WebhookEndpoint
Default: WebhookEndpoint.functionUrl()

How the webhook handler is exposed to GitHub.

`webhookReservedConcurrency`^Optional

public readonly webhookReservedConcurrency: number;

Type: number
Default: undefined (no reservation; the webhook draws from the shared pool)

Reserved concurrency for the webhook Lambda, which caps how many webhook deliveries the runner set processes at once.

Reserved concurrency is carved out of the account’s shared pool of unreserved concurrency, so a runner set that sets it takes that capacity away from every other function in the account. Must be a positive integer when set, since 0 would disable the webhook entirely.

GithubPatAuthProps

Props for GithubAuth.pat.

Initializer

import { GithubPatAuthProps } from 'cdk-github-microvm-runners'

const githubPatAuthProps: GithubPatAuthProps = { ... }

Properties

Name	Type	Description
`token`	`aws-cdk-lib.aws_secretsmanager.ISecret`	Secret holding a GitHub personal access token.
`webhookSecret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	Secret holding the webhook secret used to validate inbound deliveries.

`token`^Required

public readonly token: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

Secret holding a GitHub personal access token.

`webhookSecret`^Required

public readonly webhookSecret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

Secret holding the webhook secret used to validate inbound deliveries.

ImageAsset

One extra file or directory baked into the image.

source is a path on the machine running cdk synth. The image pipeline reads it off disk when it stages the Docker build context, and the rendered Dockerfile copies it to target inside the image.

Initializer

import { ImageAsset } from 'cdk-github-microvm-runners'

const imageAsset: ImageAsset = { ... }

Properties

Name	Type	Description
`source`	`string`	Path (file or directory) on the build machine to copy into the image.
`target`	`string`	Absolute path inside the image to copy `source` to.

`source`^Required

public readonly source: string;

Type: string

Path (file or directory) on the build machine to copy into the image.

`target`^Required

public readonly target: string;

Type: string

Absolute path inside the image to copy source to.

ImagePipelineProps

Props for ImagePipeline.

Initializer

import { ImagePipelineProps } from 'cdk-github-microvm-runners'

const imagePipelineProps: ImagePipelineProps = { ... }

Properties

Name	Type	Description
`image`	`RunnerImage`	The runner image to build: `RunnerImage.fromOptions()` for a synthesized Dockerfile, `RunnerImage.fromInline(text)` for Dockerfile text, or `RunnerImage.fromDockerfile(dir)` for a Dockerfile and build context on disk.
`network`	`RunnerNetwork`	How the build and the VMs reach the network.
`runnerSetId`	`string`	Identifier for the runner set this image belongs to, used verbatim as the image’s name.
`size`	`MicrovmSize`	The size the built image runs at, which becomes its memory floor.
`baseImageVersion`	`string`	Version of the managed `al2023-1` base image to build from.
`imageLogs`	`ImageLogs`	Where the build’s logs go.
`readyTimeoutSeconds`	`number`	Seconds the service waits for the in-VM agent’s `/ready` hook before failing the image build.
`runTimeoutSeconds`	`number`	Seconds the service waits for the in-VM agent’s `/run` hook to accept a launch.

`image`^Required

public readonly image: RunnerImage;

Type: RunnerImage

The runner image to build: RunnerImage.fromOptions() for a synthesized Dockerfile, RunnerImage.fromInline(text) for Dockerfile text, or RunnerImage.fromDockerfile(dir) for a Dockerfile and build context on disk.

`network`^Required

public readonly network: RunnerNetwork;

Type: RunnerNetwork

How the build and the VMs reach the network.

`runnerSetId`^Required

public readonly runnerSetId: string;

Type: string

Identifier for the runner set this image belongs to, used verbatim as the image’s name.

It is deliberately stable: the name is the only property whose change forces CloudFormation to replace the image, so holding it still keeps every content change an in-place update that adds a version. A content change is still picked up — the build context is a content-hashed CDK asset, so it moves codeArtifact — and an unchanged one is still a no-op. Must match ^[a-zA-Z0-9-_]+$ and be 64 characters or fewer, the service’s name limit.

`size`^Required

public readonly size: MicrovmSize;

Type: MicrovmSize

The size the built image runs at, which becomes its memory floor.

`baseImageVersion`^Optional

public readonly baseImageVersion: string;

Type: string
Default: ‘0’

Version of the managed al2023-1 base image to build from.

`imageLogs`^Optional

public readonly imageLogs: ImageLogs;

Type: ImageLogs

Where the build’s logs go.

Left unset, the build emits no logs; ImageLogs.enabled() sends them to the platform’s group, and ImageLogs.enabled(logGroup) to a group you supply.

`readyTimeoutSeconds`^Optional

public readonly readyTimeoutSeconds: number;

Type: number
Default: 300

Seconds the service waits for the in-VM agent’s /ready hook before failing the image build.

`runTimeoutSeconds`^Optional

public readonly runTimeoutSeconds: number;

Type: number
Default: 60

Seconds the service waits for the in-VM agent’s /run hook to accept a launch.

Service maximum: 60.

MicrovmIdlePolicy

When the platform suspends and resumes a runner class’s cold-launched VMs.

This mirrors the MicroVM service’s own idlePolicy shape, expressed as Durations rather than raw seconds. Set it on a runner class through RunnerClassProps.idlePolicy.

Initializer

import { MicrovmIdlePolicy } from 'cdk-github-microvm-runners'

const microvmIdlePolicy: MicrovmIdlePolicy = { ... }

Properties

Name	Type	Description
`maxIdleDuration`	`aws-cdk-lib.Duration`	Idle time before the platform auto-suspends the VM.
`suspendedDuration`	`aws-cdk-lib.Duration`	How long a suspended VM is kept before the platform terminates it.
`autoResume`	`boolean`	Auto-resume the VM on activity.

`maxIdleDuration`^Required

public readonly maxIdleDuration: Duration;

Type: aws-cdk-lib.Duration

Idle time before the platform auto-suspends the VM.

`suspendedDuration`^Required

public readonly suspendedDuration: Duration;

Type: aws-cdk-lib.Duration

How long a suspended VM is kept before the platform terminates it.

Required. The MicroVM service rejects a launch whose idle policy omits this value, and it offers no value meaning “keep the suspended VM indefinitely”, so every idle policy names a duration.

`autoResume`^Optional

public readonly autoResume: boolean;

Type: boolean
Default: false

Auto-resume the VM on activity.

RunnerAlarmOptions

Tuning for the ready-made alarms on GithubMicrovmRunnersMetrics.

Initializer

import { RunnerAlarmOptions } from 'cdk-github-microvm-runners'

const runnerAlarmOptions: RunnerAlarmOptions = { ... }

Properties

Name	Type	Description
`evaluationPeriods`	`number`	Consecutive breaching periods before the alarm fires.
`period`	`aws-cdk-lib.Duration`	Aggregation period for the metric.
`threshold`	`number`	Value at or above which the alarm fires.

`evaluationPeriods`^Optional

public readonly evaluationPeriods: number;

Type: number
Default: 1 (3 for the stuck-launch alarm)

Consecutive breaching periods before the alarm fires.

`period`^Optional

public readonly period: Duration;

Type: aws-cdk-lib.Duration
Default: Duration.minutes(5)

Aggregation period for the metric.

`threshold`^Optional

public readonly threshold: number;

Type: number
Default: 1

Value at or above which the alarm fires.

RunnerClass

Handle returned by GithubMicrovmRunners.addRunnerClass.

Initializer

import { RunnerClass } from 'cdk-github-microvm-runners'

const runnerClass: RunnerClass = { ... }

Properties

Name	Type	Description
`imageArn`	`string`	ARN of this class’s built MicroVM image (a CloudFormation token at synth).
`imagePipeline`	`ImagePipeline`	The image pipeline that builds and publishes this class’s MicroVM image.
`label`	`string`	The `runs-on` label workflows target to run on this class.
`size`	`MicrovmSize`	The VM memory floor this class launches at.

`imageArn`^Required

public readonly imageArn: string;

Type: string

ARN of this class’s built MicroVM image (a CloudFormation token at synth).

`imagePipeline`^Required

public readonly imagePipeline: ImagePipeline;

Type: ImagePipeline

The image pipeline that builds and publishes this class’s MicroVM image.

`label`^Required

public readonly label: string;

Type: string

The runs-on label workflows target to run on this class.

`size`^Required

public readonly size: MicrovmSize;

Type: MicrovmSize

The VM memory floor this class launches at.

RunnerClassProps

Props for GithubMicrovmRunners.addRunnerClass.

Initializer

import { RunnerClassProps } from 'cdk-github-microvm-runners'

const runnerClassProps: RunnerClassProps = { ... }

Properties

Name	Type	Description
`size`	`MicrovmSize`	VM memory floor for this class.
`idlePolicy`	`MicrovmIdlePolicy`	Auto-suspend and auto-resume policy for this class’s cold-launched VMs.
`image`	`RunnerImage`	Image this class builds from.
`warmPoolSize`	`number`	How many pre-booted, suspended VMs to keep ready for this class.

`size`^Required

public readonly size: MicrovmSize;

Type: MicrovmSize

VM memory floor for this class.

`idlePolicy`^Optional

public readonly idlePolicy: MicrovmIdlePolicy;

Type: MicrovmIdlePolicy
Default: undefined (no idle policy; the platform never auto-suspends)

Auto-suspend and auto-resume policy for this class’s cold-launched VMs.

Mutually exclusive with warmPoolSize on the same class, since both drive the VM’s suspended state; setting both throws at addRunnerClass time.

`image`^Optional

public readonly image: RunnerImage;

Type: RunnerImage
Default: RunnerImage.fromOptions()

Image this class builds from.

`warmPoolSize`^Optional

public readonly warmPoolSize: number;

Type: number
Default: undefined (no warm pool; every job cold-launches)

How many pre-booted, suspended VMs to keep ready for this class.

A job that matches this class resumes one of them instead of cold-launching a new VM, and falls back to a cold launch when none is available. This is a count, not a flag: warmPoolSize: 3 keeps three VMs ready. The runner set refills the pool on the warmPoolInterval schedule.

RunnerImageOptions

Options for RunnerImage.fromOptions.

Initializer

import { RunnerImageOptions } from 'cdk-github-microvm-runners'

const runnerImageOptions: RunnerImageOptions = { ... }

Properties

Name	Type	Description
`additionalOsCapabilities`	`string[]`	Extra Linux capabilities granted to the MicroVM’s operating system.
`assets`	`ImageAsset[]`	Extra files and directories to copy into the image.
`environment`	`{[ key: string ]: string}`	Extra environment variables baked into the image.
`runnerVersion`	`RunnerVersion`	`actions/runner` release to install.
`setupCommands`	`string[]`	Extra `RUN` commands, executed in order after packages, assets, and environment variables are laid down.
`systemPackages`	`string[]`	Extra `dnf` packages to install alongside the fixed base set.
`toolchains`	`RunnerToolchain[]`	Language runtimes to bake into the hosted tool cache, so `actions/setup-*` finds them without downloading anything.

`additionalOsCapabilities`^Optional

public readonly additionalOsCapabilities: string[];

Type: string[]
Default: [‘ALL’]

Extra Linux capabilities granted to the MicroVM’s operating system.

`assets`^Optional

public readonly assets: ImageAsset[];

Type: ImageAsset[]

Extra files and directories to copy into the image.

`environment`^Optional

public readonly environment: {[ key: string ]: string};

Type: {[ key: string ]: string}

Extra environment variables baked into the image.

`runnerVersion`^Optional

public readonly runnerVersion: RunnerVersion;

Type: RunnerVersion
Default: RunnerVersion.latest()

actions/runner release to install.

`setupCommands`^Optional

public readonly setupCommands: string[];

Type: string[]

Extra RUN commands, executed in order after packages, assets, and environment variables are laid down.

`systemPackages`^Optional

public readonly systemPackages: string[];

Type: string[]

Extra dnf packages to install alongside the fixed base set.

`toolchains`^Optional

public readonly toolchains: RunnerToolchain[];

Type: RunnerToolchain[]
Default: []

Language runtimes to bake into the hosted tool cache, so actions/setup-* finds them without downloading anything.

An image with none of these is smaller; one toolchain entry is needed per version your workflows ask for.

RunnerNetworkVpcOptions

Options for RunnerNetwork.vpc.

Initializer

import { RunnerNetworkVpcOptions } from 'cdk-github-microvm-runners'

const runnerNetworkVpcOptions: RunnerNetworkVpcOptions = { ... }

Properties

Name	Type	Description
`securityGroups`	`aws-cdk-lib.aws_ec2.ISecurityGroup[]`	Security groups attached to the connector’s ENIs.
`subnets`	`aws-cdk-lib.aws_ec2.SubnetSelection`	Which of the VPC’s subnets the connector’s ENIs land in.

`securityGroups`^Optional

public readonly securityGroups: ISecurityGroup[];

Type: aws-cdk-lib.aws_ec2.ISecurityGroup[]
Default: a new security group is created on the VPC

Security groups attached to the connector’s ENIs.

`subnets`^Optional

public readonly subnets: SubnetSelection;

Type: aws-cdk-lib.aws_ec2.SubnetSelection
Default: the VPC’s private-with-egress subnets (CDK’s selectSubnets() default; falls back to isolated, then public, subnets if the VPC has none of the preceding kind)

Which of the VPC’s subnets the connector’s ENIs land in.

Classes

ConsoleLogs

Runtime console capture for a runner set: everything a VM prints while it boots, runs the runner agent, and runs the job.

Off unless you add it.

Console capture needs a VM execution role. The platform writes these logs with the VM’s own role, and the construct never creates a VM identity on your behalf, so a runner set that turns console capture on without vmExecutionRole fails at synth. The two console-write actions on the group are granted by you as well, since the construct does not add policy to a role it did not create:

runners.vmConsoleLogGroup!.grant(
  role, 'logs:CreateLogStream', 'logs:PutLogEvents',
);

A MicroVM’s instance metadata service serves the execution role’s credentials to arbitrary job code, so whatever that role can do, every job running on this runner set can do. Console capture on its own needs nothing beyond the two log-write actions above. Job code can also write whatever it likes into the console group, so the contents are as trustworthy as the jobs that produced them.

ImageLogs covers the build-time counterpart and needs no role. The two are independent and can both be on.

Example

new GithubMicrovmRunners(stack, 'Runners', {
  github,
  scope,
  vmExecutionRole: role,
  consoleLogs: ConsoleLogs.enabled(),
});

Static Functions

Name	Description
`enabled`	Capture the runtime console.

`enabled`

import { ConsoleLogs } from 'cdk-github-microvm-runners'

ConsoleLogs.enabled(logGroup?: ILogGroup)

Capture the runtime console.

With no argument the construct creates a log group and exposes it as runners.vmConsoleLogGroup. Pass an ILogGroup to use one whose retention and KMS key you control. Either way the runner set needs vmExecutionRole, and that role needs the two console-write actions on the group.

Example

const consoleCapture = ConsoleLogs.enabled(myConsoleLogGroup);

`logGroup`^Optional

Type: aws-cdk-lib.aws_logs.ILogGroup

destination group.

Omitted, the construct creates one with the runner set’s logRetention (two weeks by default).

Properties

Name	Type	Description
`logGroup`	`aws-cdk-lib.aws_logs.ILogGroup`	The group console output goes to, when one was passed to `ConsoleLogs.enabled()`. `undefined` means the construct creates one.

`logGroup`^Optional

public readonly logGroup: ILogGroup;

Type: aws-cdk-lib.aws_logs.ILogGroup

The group console output goes to, when one was passed to ConsoleLogs.enabled(). undefined means the construct creates one.

GithubAppId

Where a GitHub App’s numeric ID comes from: a literal known at synth time, or a Secrets Manager secret read at runtime.

The secret form makes setup single-pass. A GitHub App can only be created once the runner set’s webhook URL exists, so an App ID that has to be known at synth means deploying twice. Referencing the ID by secret, the way the private key and webhook secret already are, lets you deploy, then create the App and write its ID into the secret, with no redeploy.

Build one with the static factories below; the constructor is private.

Example

const appId = GithubAppId.fromSecret(
  Secret.fromSecretNameV2(stack, 'AppId', 'microvm-runner/dev/app-id'),
);

Static Functions

Name	Description
`fromSecret`	The App ID is read at runtime from a Secrets Manager secret whose value is the numeric ID.
`fromValue`	The App ID is a literal string known at synth time.

`fromSecret`

import { GithubAppId } from 'cdk-github-microvm-runners'

GithubAppId.fromSecret(secret: ISecret)

The App ID is read at runtime from a Secrets Manager secret whose value is the numeric ID.

The secret need not exist at deploy time.

Example

const appId = GithubAppId.fromSecret(
  Secret.fromSecretNameV2(stack, 'AppId', 'microvm-runner/dev/app-id'),
);

`secret`^Required

Type: aws-cdk-lib.aws_secretsmanager.ISecret

`fromValue`

import { GithubAppId } from 'cdk-github-microvm-runners'

GithubAppId.fromValue(value: string)

The App ID is a literal string known at synth time.

Example

const appId = GithubAppId.fromValue('123456');

`value`^Required

Type: string

Properties

Name	Type	Description
`secret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	The secret holding the ID, for an ID built with `fromSecret()`.
`value`	`string`	The literal ID, for an ID built with `fromValue()`.

`secret`^Optional

public readonly secret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

The secret holding the ID, for an ID built with fromSecret().

`value`^Optional

public readonly value: string;

Type: string

The literal ID, for an ID built with fromValue().

GithubAppKey

Where a GitHub App’s private key lives: a Secrets Manager secret holding the PEM, or a KMS key that signs the App’s JWTs directly.

Build one with the static factories below; the constructor is private.

Example

const privateKey = GithubAppKey.fromSecret(
  Secret.fromSecretNameV2(stack, 'AppKey', 'microvm-runner/dev/app-private-key'),
);

Static Functions

Name	Description
`fromKmsKey`	The App’s private key lives in KMS and is used via `kms:Sign`.
`fromSecret`	The App’s private key is stored as a PEM in Secrets Manager.

`fromKmsKey`

import { GithubAppKey } from 'cdk-github-microvm-runners'

GithubAppKey.fromKmsKey(key: IKey)

The App’s private key lives in KMS and is used via kms:Sign.

Example

import { Key } from 'aws-cdk-lib/aws-kms';

const privateKey = GithubAppKey.fromKmsKey(
  Key.fromKeyArn(
    stack,
    'AppKey',
    'arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
  ),
);

`key`^Required

Type: aws-cdk-lib.aws_kms.IKey

`fromSecret`

import { GithubAppKey } from 'cdk-github-microvm-runners'

GithubAppKey.fromSecret(secret: ISecret)

The App’s private key is stored as a PEM in Secrets Manager.

Example

const privateKey = GithubAppKey.fromSecret(
  Secret.fromSecretNameV2(stack, 'AppKey', 'microvm-runner/dev/app-private-key'),
);

`secret`^Required

Type: aws-cdk-lib.aws_secretsmanager.ISecret

Properties

Name	Type	Description
`kmsKey`	`aws-cdk-lib.aws_kms.IKey`	The signing key, for a key built with `fromKmsKey()`.
`secret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	The secret holding the PEM, for a key built with `fromSecret()`.

`kmsKey`^Optional

public readonly kmsKey: IKey;

Type: aws-cdk-lib.aws_kms.IKey

The signing key, for a key built with fromKmsKey().

`secret`^Optional

public readonly secret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

The secret holding the PEM, for a key built with fromSecret().

GithubAuth

How a runner set authenticates to GitHub: as a GitHub App, whose private key is backed by a secret or a KMS key, or with a personal access token.

Either form also carries the webhook secret that inbound GitHub deliveries are validated against.

Build one with the static factories below; the constructor is private.

Example

const auth = GithubAuth.app({
  appId: GithubAppId.fromSecret(
    Secret.fromSecretNameV2(stack, 'AppId', 'microvm-runner/dev/app-id'),
  ),
  privateKey: GithubAppKey.fromSecret(
    Secret.fromSecretNameV2(stack, 'AppKey', 'microvm-runner/dev/app-private-key'),
  ),
  webhookSecret: Secret.fromSecretNameV2(
    stack, 'WebhookSecret', 'microvm-runner/dev/webhook-secret',
  ),
});

Methods

Name	Description
`bindEnv`	Serialize to the environment variables the runner set’s handlers read: `GH_AUTH_KIND`, `GH_APP_ID` or `GH_APP_ID_SECRET_ARN`, `GH_KEY_SECRET_ARN` or `GH_KEY_KMS_ARN`, `GH_PAT_SECRET_ARN`, and `GH_WEBHOOK_SECRET_ARN`.
`grantRead`	Grant `grantee` read access to whichever credentials this auth carries: the App’s secret-backed key and/or `kms:Sign` on its KMS key, plus its secret-backed App ID when one is used, or the PAT secret — plus, in every case, read access to the webhook secret.
`grantReadWebhookSecret`	Grant `grantee` read access to the webhook secret, and nothing else.

`bindEnv`

public bindEnv(): {[ key: string ]: string}

Serialize to the environment variables the runner set’s handlers read: GH_AUTH_KIND, GH_APP_ID or GH_APP_ID_SECRET_ARN, GH_KEY_SECRET_ARN or GH_KEY_KMS_ARN, GH_PAT_SECRET_ARN, and GH_WEBHOOK_SECRET_ARN.

Entries that do not apply are left out.

`grantRead`

public grantRead(grantee: IGrantable): void

Grant grantee read access to whichever credentials this auth carries: the App’s secret-backed key and/or kms:Sign on its KMS key, plus its secret-backed App ID when one is used, or the PAT secret — plus, in every case, read access to the webhook secret.

This is the full set, for a handler that has to act as the App. A handler that only verifies signatures wants {@link grantReadWebhookSecret}.

`grantee`^Required

Type: aws-cdk-lib.aws_iam.IGrantable

`grantReadWebhookSecret`

public grantReadWebhookSecret(grantee: IGrantable): void

Grant grantee read access to the webhook secret, and nothing else.

This is all a handler needs to verify the HMAC signature GitHub sends with every delivery. It is deliberately separate from {@link grantRead}, which also hands over the credentials that can act AS the App — minting installation tokens, registering runners. A component that only checks signatures and enqueues has no use for those, and the webhook handler is the one component reachable from the public internet.

Example

github.grantReadWebhookSecret(role);

`grantee`^Required

Type: aws-cdk-lib.aws_iam.IGrantable

Static Functions

Name	Description
`app`	Authenticate as a GitHub App.
`pat`	Authenticate with a personal access token.

`app`

import { GithubAuth } from 'cdk-github-microvm-runners'

GithubAuth.app(props: GithubAppAuthProps)

Authenticate as a GitHub App.

Example

const auth = GithubAuth.app({
  appId: GithubAppId.fromSecret(
    Secret.fromSecretNameV2(stack, 'AppId', 'microvm-runner/dev/app-id'),
  ),
  privateKey: GithubAppKey.fromSecret(
    Secret.fromSecretNameV2(stack, 'AppKey', 'microvm-runner/dev/app-private-key'),
  ),
  webhookSecret: Secret.fromSecretNameV2(
    stack, 'WebhookSecret', 'microvm-runner/dev/webhook-secret',
  ),
});

`props`^Required

Type: GithubAppAuthProps

`pat`

import { GithubAuth } from 'cdk-github-microvm-runners'

GithubAuth.pat(props: GithubPatAuthProps)

Authenticate with a personal access token.

Example

const auth = GithubAuth.pat({
  token: Secret.fromSecretNameV2(stack, 'Pat', 'microvm-runner/dev/token'),
  webhookSecret: Secret.fromSecretNameV2(
    stack, 'WebhookSecret', 'microvm-runner/dev/webhook-secret',
  ),
});

`props`^Required

Type: GithubPatAuthProps

Properties

Name	Type	Description
`kind`	`GithubAuthKind`	Whether this is App or personal-access-token authentication.
`webhookSecret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	Secret holding the webhook secret inbound deliveries are validated against.
`appId`	`GithubAppId`	The App’s ID, for App authentication.
`privateKey`	`GithubAppKey`	The App’s private key, for App authentication.
`token`	`aws-cdk-lib.aws_secretsmanager.ISecret`	The personal access token secret, for token authentication.

`kind`^Required

public readonly kind: GithubAuthKind;

Type: GithubAuthKind

Whether this is App or personal-access-token authentication.

`webhookSecret`^Required

public readonly webhookSecret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

Secret holding the webhook secret inbound deliveries are validated against.

`appId`^Optional

public readonly appId: GithubAppId;

Type: GithubAppId

The App’s ID, for App authentication.

`privateKey`^Optional

public readonly privateKey: GithubAppKey;

Type: GithubAppKey

The App’s private key, for App authentication.

`token`^Optional

public readonly token: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

The personal access token secret, for token authentication.

GithubMicrovmRunnersMetrics

The CloudWatch metrics a runner set reports, and ready-made alarms over them. A GithubMicrovmRunners exposes its own as runners.metrics.

The metrics live in the MicrovmRunners namespace, tagged with the runner set’s id. The janitor reports one set of counters per sweep, the launcher one per launch, and the warm pool one per refill sweep. Launcher and warm-pool metrics are also tagged with the runner class the launch belongs to, which is why those accessors take a runner-class label. Every method here names one of those metrics, or the dead-letter queue’s own SQS metric; the class carries no data of its own.

Everything except deadLetterQueueDepth reports only when GithubMicrovmRunnersProps.emitMetrics is on. The accessors return a Metric either way, so a dashboard can be built ahead of turning metrics on. The two alarms over those metrics throw at synth instead, rather than synthesizing an alarm that could never fire.

Example

new cw.Alarm(stack, 'SweepErrors', {
  metric: runners.metrics.errors(),
  threshold: 1,
  evaluationPeriods: 1,
});

Initializers

import { GithubMicrovmRunnersMetrics } from 'cdk-github-microvm-runners'

new GithubMicrovmRunnersMetrics(runnerSetId: string, deadLetterQueue: IQueue, emitMetrics?: boolean)

Name	Type	Description
`runnerSetId`	`string`	No description.
`deadLetterQueue`	`aws-cdk-lib.aws_sqs.IQueue`	No description.
`emitMetrics`	`boolean`	Whether the runner set reports the metrics this class names, which is `GithubMicrovmRunnersProps.emitMetrics`. Every accessor except `deadLetterQueueDepth` depends on it, though they all return a `Metric` either way; only the two alarms over those metrics refuse to synthesize.

`runnerSetId`^Required

Type: string

`deadLetterQueue`^Required

Type: aws-cdk-lib.aws_sqs.IQueue

`emitMetrics`^Optional

Type: boolean

Whether the runner set reports the metrics this class names, which is GithubMicrovmRunnersProps.emitMetrics. Every accessor except deadLetterQueueDepth depends on it, though they all return a Metric either way; only the two alarms over those metrics refuse to synthesize.

Methods

Name	Description
`cancelledBeforeLaunch`	Launches skipped because the job had already stopped waiting for a runner by the time the launch was processed — cancelled, or its run deleted.
`capacityRejected`	Launches the MicroVM service rejected for capacity.
`coldBoot`	Launches served by booting a new VM, because no warm VM was available or the class keeps no warm pool.
`coldSpinUpMs`	Milliseconds to spin up a cold launch: starting the VM, waiting for it to boot, and pushing the runner’s registration.
`deadLetterQueueDepth`	Messages sitting in the dead-letter queue: a launch or terminate intent SQS gave up redriving.
`deadLetterQueueNotEmptyAlarm`	Alarm when the dead-letter queue is not empty, meaning SQS gave up redriving a launch or terminate intent.
`errors`	Janitor sweep count: failures on individual VMs, rows, or image versions during a sweep.
`imageVersionsPruned`	Janitor sweep count: inactive MicroVM image versions pruned past `keepImageVersions`.
`lifetimeKills`	Janitor sweep count: VMs terminated for having run longer than `maxJobDuration` plus the platform’s own grace.
`orphansReaped`	Janitor sweep count: running VMs that belong to this runner set but have no row in the runner table, reaped once a second sweep has seen the same VM unaccounted for.
`poolCurrent`	Warm VMs suspended and available for this class as of the last warm-pool sweep.
`poolLaunched`	Warm VMs the last warm-pool sweep launched to reach `warmPoolSize`.
`poolLaunchFailed`	Warm-VM launches a warm-pool sweep attempted and failed.
`poolTarget`	This class’s `warmPoolSize`, as the last warm-pool sweep read it.
`stuckClaimsRelaunched`	Janitor sweep count: launches that were claimed but never served, re-launched from the orphaned claim.
`stuckLaunchesRecovered`	Janitor sweep count: dead-lettered launches re-driven onto the job queue, which is 0 unless `recoverStuckLaunches` is on.
`stuckLaunchesRecoveredAlarm`	Alarm on stuck-launch recoveries, the dead-lettered launches the janitor re-drove, which only happens with `recoverStuckLaunches` on.
`stuckRunnersReaped`	Janitor sweep count: runners that registered with GitHub and then sat idle past `idleRunnerGraceSeconds`, reaped once a second sweep has seen them the same way.
`suspectsCleared`	Janitor sweep count: VMs an earlier sweep had marked as suspect, cleared because this sweep found them accounted for or working again.
`sweepErrorsAlarm`	Alarm on janitor sweep errors, the per-item failures a sweep isolates and continues past.
`tableRowsCleaned`	Janitor sweep count: runner table rows deleted, either because the VM they name is confirmed gone or because a real row superseded an orphaned one.
`warmHit`	Launches served from the warm pool: a pre-booted VM claimed and resumed rather than a new one launched.
`warmSpinUpMs`	Milliseconds to spin up a warm launch: claiming the VM, resuming it, and pushing the runner’s registration.
`warmThrottled`	Warm-pool claims that were throttled and fell back to booting a new VM.

`cancelledBeforeLaunch`

public cancelledBeforeLaunch(runnerClassLabel: string): Metric

Launches skipped because the job had already stopped waiting for a runner by the time the launch was processed — cancelled, or its run deleted.

No VM is booted for these, so a rising count is work avoided rather than work lost. It tracks how often jobs are cancelled while still queued, which is routine on a repository using concurrency groups: every re-push cancels the run it superseded. A count that dwarfs ColdBoot suggests the workflows feeding this runner set are cancelled more often than they finish, which is usually a question about their triggers rather than about the runner set.

Example

new cw.Alarm(stack, 'MostlyCancelled', {
  metric: runners.metrics.cancelledBeforeLaunch('microvm'),
  threshold: 50,
  evaluationPeriods: 3,
});

`runnerClassLabel`^Required

Type: string

`capacityRejected`

public capacityRejected(runnerClassLabel: string): Metric

Launches the MicroVM service rejected for capacity.

This is the runner set’s quota signal: a value that stays above zero means jobs are queueing behind a MicroVM quota, or behind maxConcurrentVms, rather than running, and each rejected launch spends one of its maxReceiveCount redrives on the way to the dead-letter queue. See docs/service-quotas.md.

`runnerClassLabel`^Required

Type: string

`coldBoot`

public coldBoot(runnerClassLabel: string): Metric

Launches served by booting a new VM, because no warm VM was available or the class keeps no warm pool.

`runnerClassLabel`^Required

Type: string

`coldSpinUpMs`

public coldSpinUpMs(runnerClassLabel: string): Metric

Milliseconds to spin up a cold launch: starting the VM, waiting for it to boot, and pushing the runner’s registration.

Reported as an average rather than a sum.

`runnerClassLabel`^Required

Type: string

`deadLetterQueueDepth`

public deadLetterQueueDepth(): Metric

Messages sitting in the dead-letter queue: a launch or terminate intent SQS gave up redriving.

`deadLetterQueueNotEmptyAlarm`

public deadLetterQueueNotEmptyAlarm(scope: Construct, options?: RunnerAlarmOptions): Alarm

Alarm when the dead-letter queue is not empty, meaning SQS gave up redriving a launch or terminate intent.

A runner set that is keeping up holds this at 0, so any sustained depth means jobs are being dropped, unless recoverStuckLaunches is draining them. It fires on one message over a single 5-minute period; pass RunnerAlarmOptions to change that, and alarm.addAlarmAction() to route it.

This is the one alarm here that works without GithubMicrovmRunnersProps.emitMetrics, because it watches the dead-letter queue’s own SQS metric rather than one the handlers report.

`scope`^Required

Type: constructs.Construct

`options`^Optional

Type: RunnerAlarmOptions

`errors`

public errors(): Metric

Janitor sweep count: failures on individual VMs, rows, or image versions during a sweep.

The sweep isolates each one and still completes.

`imageVersionsPruned`

public imageVersionsPruned(): Metric

Janitor sweep count: inactive MicroVM image versions pruned past keepImageVersions.

`lifetimeKills`

public lifetimeKills(): Metric

Janitor sweep count: VMs terminated for having run longer than maxJobDuration plus the platform’s own grace.

`orphansReaped`

public orphansReaped(): Metric

Janitor sweep count: running VMs that belong to this runner set but have no row in the runner table, reaped once a second sweep has seen the same VM unaccounted for.

`poolCurrent`

public poolCurrent(runnerClassLabel: string): Metric

Warm VMs suspended and available for this class as of the last warm-pool sweep.

`runnerClassLabel`^Required

Type: string

`poolLaunched`

public poolLaunched(runnerClassLabel: string): Metric

Warm VMs the last warm-pool sweep launched to reach warmPoolSize.

`runnerClassLabel`^Required

Type: string

`poolLaunchFailed`

public poolLaunchFailed(runnerClassLabel: string): Metric

Warm-VM launches a warm-pool sweep attempted and failed.

A value that stays above zero means the pool is not reaching warmPoolSize, so jobs keep booting new VMs instead of resuming warm ones.

`runnerClassLabel`^Required

Type: string

`poolTarget`

public poolTarget(runnerClassLabel: string): Metric

This class’s warmPoolSize, as the last warm-pool sweep read it.

`runnerClassLabel`^Required

Type: string

`stuckClaimsRelaunched`

public stuckClaimsRelaunched(): Metric

Janitor sweep count: launches that were claimed but never served, re-launched from the orphaned claim.

This is 0 unless recoverStuckLaunches is on.

`stuckLaunchesRecovered`

public stuckLaunchesRecovered(): Metric

Janitor sweep count: dead-lettered launches re-driven onto the job queue, which is 0 unless recoverStuckLaunches is on.

A value that stays high means launches are failing for some reason other than a GitHub outage.

`stuckLaunchesRecoveredAlarm`

public stuckLaunchesRecoveredAlarm(scope: Construct, options?: RunnerAlarmOptions): Alarm

Alarm on stuck-launch recoveries, the dead-lettered launches the janitor re-drove, which only happens with recoverStuckLaunches on.

Recoveries that keep coming mean launches are failing for some reason other than a GitHub outage. It fires on one recovery in each of three consecutive 5-minute periods, which rides out a real outage; pass RunnerAlarmOptions to change that.

Requires GithubMicrovmRunnersProps.emitMetrics, and throws at synth without it.

`scope`^Required

Type: constructs.Construct

`options`^Optional

Type: RunnerAlarmOptions

`stuckRunnersReaped`

public stuckRunnersReaped(): Metric

Janitor sweep count: runners that registered with GitHub and then sat idle past idleRunnerGraceSeconds, reaped once a second sweep has seen them the same way.

`suspectsCleared`

public suspectsCleared(): Metric

Janitor sweep count: VMs an earlier sweep had marked as suspect, cleared because this sweep found them accounted for or working again.

`sweepErrorsAlarm`

public sweepErrorsAlarm(scope: Construct, options?: RunnerAlarmOptions): Alarm

Alarm on janitor sweep errors, the per-item failures a sweep isolates and continues past.

A value that stays above zero means the runner set is failing to reconcile — VMs left running, runners left unreaped — even though each sweep completes. It fires on one error in each of three consecutive 5-minute periods; pass RunnerAlarmOptions to change that.

The three periods are the point. A single sweep error is usually a transient fault the next sweep sails past — a GitHub API call that lost its connection, a throttled describe — and the sweep is convergent, so the work is retried five minutes later either way. Alarming on one such blip pages an operator for something already fixed by the time they read it. A genuine reconciliation failure (expired credentials, a broken table, a revoked App installation) fails every sweep, so it still announces itself within fifteen minutes.

Requires GithubMicrovmRunnersProps.emitMetrics, and throws at synth without it.

`scope`^Required

Type: constructs.Construct

`options`^Optional

Type: RunnerAlarmOptions

`tableRowsCleaned`

public tableRowsCleaned(): Metric

Janitor sweep count: runner table rows deleted, either because the VM they name is confirmed gone or because a real row superseded an orphaned one.

`warmHit`

public warmHit(runnerClassLabel: string): Metric

Launches served from the warm pool: a pre-booted VM claimed and resumed rather than a new one launched.

`runnerClassLabel`^Required

Type: string

`warmSpinUpMs`

public warmSpinUpMs(runnerClassLabel: string): Metric

Milliseconds to spin up a warm launch: claiming the VM, resuming it, and pushing the runner’s registration.

Reported as an average rather than a sum.

`runnerClassLabel`^Required

Type: string

`warmThrottled`

public warmThrottled(runnerClassLabel: string): Metric

Warm-pool claims that were throttled and fell back to booting a new VM.

The same launch can also count under ColdBoot or CapacityRejected.

`runnerClassLabel`^Required

Type: string

ImageLogs

Build-time image logs for a runner set: the Docker build layers and the ready-probe banner an image emits while it is built.

Off unless you add it.

These logs are written while the image builds, by the image build role rather than by a VM, so image logging needs no VM execution role and puts no credentials on a runner. ConsoleLogs covers the runtime counterpart, which does need a role. The two are independent and can both be on.

Example

new GithubMicrovmRunners(stack, 'Runners', {
  github,
  scope,
  imageLogs: ImageLogs.enabled(),
});

Static Functions

Name	Description
`enabled`	Send image-build logs to CloudWatch.

`enabled`

import { ImageLogs } from 'cdk-github-microvm-runners'

ImageLogs.enabled(logGroup?: ILogGroup)

Send image-build logs to CloudWatch.

With no argument they go to the platform’s own group (/aws/lambda-microvms/…). Pass an ILogGroup to send them to a group whose retention and KMS key you control.

Example

const buildLogs = ImageLogs.enabled(myBuildLogGroup);

`logGroup`^Optional

Type: aws-cdk-lib.aws_logs.ILogGroup

destination group.

Omitted, the platform’s own group.

Properties

Name	Type	Description
`logGroup`	`aws-cdk-lib.aws_logs.ILogGroup`	The group build logs go to, when one was passed to `ImageLogs.enabled()`. `undefined` means the platform’s own group.

`logGroup`^Optional

public readonly logGroup: ILogGroup;

Type: aws-cdk-lib.aws_logs.ILogGroup

The group build logs go to, when one was passed to ImageLogs.enabled(). undefined means the platform’s own group.

MicrovmSize

The memory a MicroVM runs with.

Each runner class picks one preset, and that preset becomes the memory floor of the image the class builds. Pick from the static presets below; the constructor is private.

A preset is a floor, not an allocation. It is the minimum the image is built with, and the platform provisions above it — measured at roughly four times the request, so a class on GB1 has been observed booting with about 4 GB and 2 vCPU, and one on GB4 with about 16 GB and 8 vCPU. Two things follow: a workload usually fits a smaller preset than its memory figure suggests, and the account’s memory quota is charged the measured allocation rather than the floor. The service quotas guide carries the arithmetic.

vCPU and disk follow from the preset and are not separately settable — the image resource takes a memory floor and nothing else.

Example

runners.addRunnerClass('microvm-8gb', { size: MicrovmSize.GB8 });

Properties

Name	Type	Description
`memoryGb`	`number`	Memory floor in GB.
`memoryMib`	`number`	Memory in MiB, the unit the MicroVM image’s `minimumMemoryInMiB` takes.

`memoryGb`^Required

public readonly memoryGb: number;

Type: number

Memory floor in GB.

`memoryMib`^Required

public readonly memoryMib: number;

Type: number

Memory in MiB, the unit the MicroVM image’s minimumMemoryInMiB takes.

Constants

Name	Type	Description
`GB0_5`	`MicrovmSize`	Memory floor of 0.5 GB.
`GB1`	`MicrovmSize`	Memory floor of 1 GB.
`GB2`	`MicrovmSize`	Memory floor of 2 GB.
`GB4`	`MicrovmSize`	Memory floor of 4 GB.
`GB8`	`MicrovmSize`	Memory floor of 8 GB.

`GB0_5`^Required

public readonly GB0_5: MicrovmSize;

Type: MicrovmSize

Memory floor of 0.5 GB.

`GB1`^Required

public readonly GB1: MicrovmSize;

Type: MicrovmSize

Memory floor of 1 GB.

`GB2`^Required

public readonly GB2: MicrovmSize;

Type: MicrovmSize

Memory floor of 2 GB.

`GB4`^Required

public readonly GB4: MicrovmSize;

Type: MicrovmSize

Memory floor of 4 GB.

`GB8`^Required

public readonly GB8: MicrovmSize;

Type: MicrovmSize

Memory floor of 8 GB.

RunnerImage

The image a runner class’s VMs boot from: one this library synthesizes, or one you author yourself.

Build one with the static factories below; the constructor is private.

Example

runners.addRunnerClass('build', {
  size: MicrovmSize.GB4,
  image: RunnerImage.fromOptions({
    systemPackages: ['jq', 'ripgrep'],
  }),
});

Static Functions

Name	Description
`fromDockerfile`	Use your own Dockerfile, and the build context around it, from the directory `dir`.
`fromInline`	Use your own Dockerfile, supplied as text.
`fromOptions`	Synthesize a Dockerfile from `opts` — extra packages, setup commands, assets, environment variables, toolchains, and the `actions/runner` release to install.

`fromDockerfile`

import { RunnerImage } from 'cdk-github-microvm-runners'

RunnerImage.fromDockerfile(dir: string)

Use your own Dockerfile, and the build context around it, from the directory dir.

The whole directory is staged as the Docker build context, so a Dockerfile that needs to COPY files of its own belongs here rather than in RunnerImage.fromInline.

The contentHash recorded on the returned instance is derived from the path string. The directory’s actual contents are read and hashed later, when the image pipeline stages them as a CDK asset.

A relative dir is resolved against the process working directory, which is wherever cdk was invoked. Anchor it to the file that declares the runner class instead by passing path.join(__dirname, 'runner-image').

Example

const customImage = RunnerImage.fromDockerfile('runner-image');

`dir`^Required

Type: string

`fromInline`

import { RunnerImage } from 'cdk-github-microvm-runners'

RunnerImage.fromInline(dockerfile: string)

Use your own Dockerfile, supplied as text.

The text is staged verbatim as the build context’s Dockerfile, alongside the microvm-runner/ directory the image pipeline injects and nothing else. A Dockerfile that needs to COPY files of its own belongs with RunnerImage.fromDockerfile, which stages a whole directory.

The text must COPY microvm-runner/agent.mjs and start the staged entrypoint, because that agent is what serves the MicroVM lifecycle hooks the platform calls. This is checked here, and a Dockerfile that does not copy the agent throws.

The contentHash recorded on the returned instance is a sha256 over the supplied text.

Example

const inlineImage = RunnerImage.fromInline(`
FROM public.ecr.aws/lambda/microvms:al2023-minimal

RUN dnf install -y git jq

COPY microvm-runner/agent.mjs /opt/microvm-runner/agent.mjs
COPY microvm-runner/entrypoint.sh /opt/microvm-runner/entrypoint.sh
ENTRYPOINT ["/opt/microvm-runner/entrypoint.sh"]
`);

`dockerfile`^Required

Type: string

`fromOptions`

import { RunnerImage } from 'cdk-github-microvm-runners'

RunnerImage.fromOptions(opts?: RunnerImageOptions)

Synthesize a Dockerfile from opts — extra packages, setup commands, assets, environment variables, toolchains, and the actions/runner release to install.

The image’s contentHash is computed here, over the rendered Dockerfile text and the list of assets it copies.

Example

const buildImage = RunnerImage.fromOptions({
  systemPackages: ['jq', 'ripgrep'],
  setupCommands: ['npm install -g pnpm@10'],
  environment: { LANG: 'C.UTF-8' },
  toolchains: [RunnerToolchain.python('3.12.7')],
});

`opts`^Optional

Type: RunnerImageOptions

Properties

Name	Type	Description
`additionalOsCapabilities`	`string[]`	Extra Linux capabilities granted to the MicroVM’s operating system.
`contentHash`	`string`	sha256 content hash, part of the built image’s name.
`assets`	`ImageAsset[]`	The `{source, target}` pairs from `RunnerImageOptions.assets`. Set for `fromOptions()`, whose rendered Dockerfile copies each one into the image. `undefined` for `fromDockerfile()`, which stages your whole directory instead, and for `fromInline()`, whose build context holds the Dockerfile and the injected agent and nothing else.
`dockerfile`	`string`	Dockerfile text: rendered for `fromOptions()`, supplied by you for `fromInline()`.
`dockerfileDir`	`string`	The directory holding your own Dockerfile and build context.

`additionalOsCapabilities`^Required

public readonly additionalOsCapabilities: string[];

Type: string[]

Extra Linux capabilities granted to the MicroVM’s operating system.

fromOptions() takes this from RunnerImageOptions; fromDockerfile() and fromInline() always carry ['ALL'].

`contentHash`^Required

public readonly contentHash: string;

Type: string

sha256 content hash, part of the built image’s name.

For fromOptions() it covers the rendered Dockerfile and the options that produced it; for fromInline(), the supplied Dockerfile text; for fromDockerfile(), the directory path.

`assets`^Optional

public readonly assets: ImageAsset[];

Type: ImageAsset[]

The {source, target} pairs from RunnerImageOptions.assets. Set for fromOptions(), whose rendered Dockerfile copies each one into the image. undefined for fromDockerfile(), which stages your whole directory instead, and for fromInline(), whose build context holds the Dockerfile and the injected agent and nothing else.

`dockerfile`^Optional

public readonly dockerfile: string;

Type: string

Dockerfile text: rendered for fromOptions(), supplied by you for fromInline().

undefined for fromDockerfile(), whose Dockerfile lives on disk under dockerfileDir.

`dockerfileDir`^Optional

public readonly dockerfileDir: string;

Type: string

The directory holding your own Dockerfile and build context.

Set for fromDockerfile(), undefined for fromOptions() and fromInline(), which both carry their Dockerfile as dockerfile text.

RunnerNetwork

How a runner set’s MicroVMs reach the network: direct internet egress, Lambda VPC runtime connectors you already have, or a connector the construct builds from a CDK VPC.

Build one with the static factories below; the constructor is private.

Example

new GithubMicrovmRunners(stack, 'Runners', {
  github,
  scope,
  network: RunnerNetwork.vpc(vpc),
});

Static Functions

Name	Description
`internetEgress`	Runners egress directly to the internet (no VPC connector).
`vpc`	Runners egress through a network connector the construct builds from the given CDK VPC, along with the security group and the ENI-management operator role that connector needs.
`vpcConnector`	Runners are attached to the given Lambda runtime connector ARNs.

`internetEgress`

import { RunnerNetwork } from 'cdk-github-microvm-runners'

RunnerNetwork.internetEgress()

Runners egress directly to the internet (no VPC connector).

Example

const network = RunnerNetwork.internetEgress();

`vpc`

import { RunnerNetwork } from 'cdk-github-microvm-runners'

RunnerNetwork.vpc(vpc: IVpc, opts?: RunnerNetworkVpcOptions)

Runners egress through a network connector the construct builds from the given CDK VPC, along with the security group and the ENI-management operator role that connector needs.

You supply the VPC; no connector ARN is required. connectorArns is empty on the returned instance, and the construct fills in the connector’s real ARN at synth.

Example

const network = RunnerNetwork.vpc(vpc, {
  subnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
  securityGroups: [mySecurityGroup],
});

`vpc`^Required

Type: aws-cdk-lib.aws_ec2.IVpc

`opts`^Optional

Type: RunnerNetworkVpcOptions

`vpcConnector`

import { RunnerNetwork } from 'cdk-github-microvm-runners'

RunnerNetwork.vpcConnector(connectorArns: string[])

Runners are attached to the given Lambda runtime connector ARNs.

Example

const network = RunnerNetwork.vpcConnector([
  'arn:aws:lambda:us-east-1:111122223333:network-connector:my-connector',
]);

`connectorArns`^Required

Type: string[]

Properties

Name	Type	Description
`connectorArns`	`string[]`	Runtime connector ARNs.
`kind`	`RunnerNetworkKind`	Which networking mode this instance carries.
`securityGroups`	`aws-cdk-lib.aws_ec2.ISecurityGroup[]`	Security groups for the built connector, set only for a `vpc()` network.
`sourceVpc`	`aws-cdk-lib.aws_ec2.IVpc`	The VPC to build a connector from, set only for a `vpc()` network.
`subnets`	`aws-cdk-lib.aws_ec2.SubnetSelection`	Subnet selection for the built connector, set only for a `vpc()` network.

`connectorArns`^Required

public readonly connectorArns: string[];

Type: string[]

Runtime connector ARNs.

Empty for direct internet egress, and empty for a vpc() network until the construct builds its connector at synth.

`kind`^Required

public readonly kind: RunnerNetworkKind;

Type: RunnerNetworkKind

Which networking mode this instance carries.

`securityGroups`^Optional

public readonly securityGroups: ISecurityGroup[];

Type: aws-cdk-lib.aws_ec2.ISecurityGroup[]

Security groups for the built connector, set only for a vpc() network.

`sourceVpc`^Optional

public readonly sourceVpc: IVpc;

Type: aws-cdk-lib.aws_ec2.IVpc

The VPC to build a connector from, set only for a vpc() network.

`subnets`^Optional

public readonly subnets: SubnetSelection;

Type: aws-cdk-lib.aws_ec2.SubnetSelection

Subnet selection for the built connector, set only for a vpc() network.

RunnerScope

Which GitHub scope registered runners are visible to: an entire organization, or an explicit list of owner/repo repositories.

Build one with the static factories below; the constructor is private.

Example

const orgScope = RunnerScope.org('my-org');

Methods

Name	Description
`toJson`	Serialize this scope to the JSON form the runner set’s handlers read at runtime.

`toJson`

public toJson(): string

Serialize this scope to the JSON form the runner set’s handlers read at runtime.

Static Functions

Name	Description
`org`	Runners are registered at the organization level.
`repos`	Runners are registered against an explicit list of `owner/repo` repos.

`org`

import { RunnerScope } from 'cdk-github-microvm-runners'

RunnerScope.org(org: string)

Runners are registered at the organization level.

Example

const orgScope = RunnerScope.org('my-org');

`org`^Required

Type: string

`repos`

import { RunnerScope } from 'cdk-github-microvm-runners'

RunnerScope.repos(repos: string[])

Runners are registered against an explicit list of owner/repo repos.

Example

const repoScope = RunnerScope.repos(['my-org/api', 'my-org/web']);

`repos`^Required

Type: string[]

Properties

Name	Type	Description
`kind`	`RunnerScopeKind`	Whether this scope is an organization or a list of repositories.
`organization`	`string`	The organization, for a scope built with `RunnerScope.org()`.
`repositories`	`string[]`	The `owner/repo` list, for a scope built with `RunnerScope.repos()`.

`kind`^Required

public readonly kind: RunnerScopeKind;

Type: RunnerScopeKind

Whether this scope is an organization or a list of repositories.

`organization`^Optional

public readonly organization: string;

Type: string

The organization, for a scope built with RunnerScope.org().

`repositories`^Optional

public readonly repositories: string[];

Type: string[]

The owner/repo list, for a scope built with RunnerScope.repos().

RunnerToolchain

A language runtime baked into the runner image’s hosted tool cache at /opt/hostedtoolcache, where actions/setup-python and actions/setup-node find it without downloading anything.

Those actions otherwise fetch OS-specific prebuilt runtimes, which are not published for the AL2023 image these runners use.

Several versions can be baked in at once, and a workflow asking for python-version: "3.12" matches a baked 3.12.7.

Build one with the static factories below; the constructor is private.

Example

const testImage = RunnerImage.fromOptions({
  toolchains: [
    RunnerToolchain.python('3.12.7'),
    RunnerToolchain.node('22.11.0'),
  ],
});

Static Functions

Name	Description
`node`	Node.js, from the official arm64 tarball. Full semver, e.g. `'22.11.0'`.
`python`	CPython, built from source.

`node`

import { RunnerToolchain } from 'cdk-github-microvm-runners'

RunnerToolchain.node(version: string)

Node.js, from the official arm64 tarball. Full semver, e.g. '22.11.0'.

Example

const node = RunnerToolchain.node('22.11.0');

`version`^Required

Type: string

`python`

import { RunnerToolchain } from 'cdk-github-microvm-runners'

RunnerToolchain.python(version: string)

CPython, built from source.

version is a full semver, e.g. '3.12.7'.

Example

const python = RunnerToolchain.python('3.12.7');

`version`^Required

Type: string

Properties

Name	Type	Description
`kind`	`ToolchainKind`	Which runtime this is.
`version`	`string`	The full semver release baked in, e.g. `'3.12.7'`.

`kind`^Required

public readonly kind: ToolchainKind;

Type: ToolchainKind

Which runtime this is.

`version`^Required

public readonly version: string;

Type: string

The full semver release baked in, e.g. '3.12.7'.

RunnerVersion

Which actions/runner release to install on the MicroVM image.

Build one with the static factories below; the constructor is private.

Example

const pinnedImage = RunnerImage.fromOptions({
  runnerVersion: RunnerVersion.of('2.328.0'),
});

Static Functions

Name	Description
`latest`	Use the `actions/runner` release this library currently pins (`DEFAULT_RUNNER_VERSION`).
`of`	Pin an explicit `actions/runner` release, e.g. `"2.319.1"`.

`latest`

import { RunnerVersion } from 'cdk-github-microvm-runners'

RunnerVersion.latest()

Use the actions/runner release this library currently pins (DEFAULT_RUNNER_VERSION).

No version is carried on the instance; the image build fills the pinned value in at synth.

Example

const runnerVersion = RunnerVersion.latest();

`of`

import { RunnerVersion } from 'cdk-github-microvm-runners'

RunnerVersion.of(version: string)

Pin an explicit actions/runner release, e.g. "2.319.1".

Example

const pinnedRunner = RunnerVersion.of('2.328.0');

`version`^Required

Type: string

Properties

Name	Type	Description
`version`	`string`	The pinned release, for a version built with `RunnerVersion.of()`. `undefined` for `RunnerVersion.latest()`.

`version`^Optional

public readonly version: string;

Type: string

The pinned release, for a version built with RunnerVersion.of(). undefined for RunnerVersion.latest().

WebhookEndpoint

How the webhook handler is exposed to GitHub’s workflow_job deliveries.

The one form today is a Lambda Function URL. It is created with authType: NONE; the auth boundary is the HMAC-SHA256 signature GitHub sends with every delivery, which the handler verifies against the webhook secret before it does anything else.

Example

new GithubMicrovmRunners(stack, 'Runners', {
  github,
  scope,
  webhook: WebhookEndpoint.functionUrl(),
});

Static Functions

Name	Description
`functionUrl`	Expose the webhook handler on a Lambda Function URL.

`functionUrl`

import { WebhookEndpoint } from 'cdk-github-microvm-runners'

WebhookEndpoint.functionUrl()

Expose the webhook handler on a Lambda Function URL.

Example

const webhook = WebhookEndpoint.functionUrl();

Properties

Name	Type	Description
`kind`	`WebhookEndpointKind`	Which form of endpoint this instance represents.

`kind`^Required

public readonly kind: WebhookEndpointKind;

Type: WebhookEndpointKind

Which form of endpoint this instance represents.

Enums

GithubAuthKind

Which credential flow a GithubAuth represents.

Members

Name	Description
`APP`	A GitHub App.
`PAT`	A personal access token.

`APP`

A GitHub App.

`PAT`

A personal access token.

RunnerNetworkKind

Which networking mode a RunnerNetwork carries.

Members

Name	Description
`INTERNET`	Direct internet egress, with no Lambda VPC runtime connector.
`CONNECTORS`	Runners attached to caller-supplied Lambda runtime connector ARNs.
`VPC`	Runners attached to a connector the construct builds from a CDK VPC.

`INTERNET`

Direct internet egress, with no Lambda VPC runtime connector.

`CONNECTORS`

Runners attached to caller-supplied Lambda runtime connector ARNs.

`VPC`

Runners attached to a connector the construct builds from a CDK VPC.

RunnerScopeKind

Which GitHub scope a RunnerScope represents.

Members

Name	Description
`ORG`	Runners are registered at the organization level.
`REPOS`	Runners are registered against an explicit list of repositories.

`ORG`

Runners are registered at the organization level.

`REPOS`

Runners are registered against an explicit list of repositories.

ToolchainKind

How a toolchain is installed into the image’s hosted tool cache.

Members

Name	Description
`PYTHON`	CPython, built from source (`configure --prefix … --enable-shared`) on AL2023.
`NODE`	Node.js, unpacked from the official nodejs.org linux-arm64 tarball.

`PYTHON`

CPython, built from source (configure --prefix … --enable-shared) on AL2023.

`NODE`

Node.js, unpacked from the official nodejs.org linux-arm64 tarball.

WebhookEndpointKind

Which form of endpoint a WebhookEndpoint represents.

Members

Name	Description
`FUNCTION_URL`	A Lambda Function URL.

`FUNCTION_URL`

A Lambda Function URL.

API reference

Constructs

GithubMicrovmRunners

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

with

mixinsRequired

addRunnerClass

labelRequired

propsRequired

runnerClass

labelRequired

Static Functions

isConstruct

xRequired

Properties

nodeRequired

deadLetterQueueRequired

defaultImageArnRequired

janitorFunctionRequired

jobQueueRequired

launcherFunctionRequired

metricsRequired

runnerClassesRequired

runnerTableRequired

setupCommandRequired

webhookFunctionRequired

webhookUrlRequired

vmConsoleLogGroupOptional

vmExecutionRoleOptional

warmPoolFunctionOptional

ImagePipeline

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

with

mixinsRequired

Static Functions

isConstruct

xRequired

Properties

nodeRequired

buildRoleRequired

imageArnRequired

imageNameRequired

imageResourceRequired

imageVersionRequired

Structs

GithubAppAuthProps

Initializer

Properties

appIdRequired

privateKeyRequired

webhookSecretRequired

GithubMicrovmRunnersProps

Initializer

Properties

githubRequired

scopeRequired

additionalRegionsOptional

consoleLogsOptional

deadLetterRetentionOptional

emitMetricsOptional

encryptionKeyOptional

idleRunnerGraceSecondsOptional

imageLogsOptional

janitorIntervalOptional

keepImageVersionsOptional

lambdaMemorySizeOptional

logRetentionOptional

maxConcurrentVmsOptional

maxJobDurationOptional

maxReceiveCountOptional

`scope`^Required

`id`^Required

`props`^Required

`toString`

`with`

`mixins`^Required

`addRunnerClass`

`label`^Required

`props`^Required

`runnerClass`

`label`^Required

`isConstruct`

`x`^Required

`node`^Required

`deadLetterQueue`^Required

`defaultImageArn`^Required

`janitorFunction`^Required

`jobQueue`^Required

`launcherFunction`^Required

`metrics`^Required

`runnerClasses`^Required

`runnerTable`^Required

`setupCommand`^Required

`webhookFunction`^Required

`webhookUrl`^Required

`vmConsoleLogGroup`^Optional

`vmExecutionRole`^Optional

`warmPoolFunction`^Optional

`scope`^Required

`id`^Required

`props`^Required

`toString`

`with`

`mixins`^Required

`isConstruct`

`x`^Required

`node`^Required

`buildRole`^Required

`imageArn`^Required

`imageName`^Required

`imageResource`^Required

`imageVersion`^Required

`appId`^Required

`privateKey`^Required

`webhookSecret`^Required

`github`^Required

`scope`^Required

`additionalRegions`^Optional

`consoleLogs`^Optional

`deadLetterRetention`^Optional

`emitMetrics`^Optional

`encryptionKey`^Optional

`idleRunnerGraceSeconds`^Optional

`imageLogs`^Optional

`janitorInterval`^Optional

`keepImageVersions`^Optional

`lambdaMemorySize`^Optional

`logRetention`^Optional

`maxConcurrentVms`^Optional

`maxJobDuration`^Optional

`maxReceiveCount`^Optional

`network`^Optional

`permissionsBoundary`^Optional

`pointInTimeRecovery`^Optional

`recoverStuckLaunches`^Optional

`removalPolicy`^Optional

`vmExecutionRole`^Optional

`warmPoolInterval`^Optional

`webhook`^Optional

`webhookReservedConcurrency`^Optional

`token`^Required

`webhookSecret`^Required

`source`^Required

`target`^Required

`image`^Required

`network`^Required

`runnerSetId`^Required

`size`^Required

`baseImageVersion`^Optional

`imageLogs`^Optional