# API Reference ## Constructs ### AlwaysOnWarmRunner Warm runners that run 24/7. Fills at midnight UTC and each runner stays alive for 24 hours. Runners will be provisioned using the specified provider and registered in the specified repository or organization. Registration level must match the one selected during setup. > [https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md **Limitations** - Jobs will still trigger provisioning of on-demand runners, even if a warm runner ends up being used. - You may briefly see more than `count` runners when changing config or at rotation. - To remove: set `count` to 0, deploy, wait for warm runners to stop, then remove and deploy again. If you don't follow this procedure, warm runners may linger until they expire. - Provider failures or timeouts (like Lambda provider timing out after 15 minutes) will result in a gap in coverage until the retry succeeds. Current retry mechanism has built-in back-off rate and can be tweaked using `retryOptions`. This will be improved in the future. ```typescript new AlwaysOnWarmRunner(stack, 'AlwaysOnLinux', { runners, provider: myProvider, count: 3, owner: 'my-org', repo: 'my-repo', }); ```](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md **Limitations** - Jobs will still trigger provisioning of on-demand runners, even if a warm runner ends up being used. - You may briefly see more than `count` runners when changing config or at rotation. - To remove: set `count` to 0, deploy, wait for warm runners to stop, then remove and deploy again. If you don't follow this procedure, warm runners may linger until they expire. - Provider failures or timeouts (like Lambda provider timing out after 15 minutes) will result in a gap in coverage until the retry succeeds. Current retry mechanism has built-in back-off rate and can be tweaked using `retryOptions`. This will be improved in the future. ```typescript new AlwaysOnWarmRunner(stack, 'AlwaysOnLinux', { runners, provider: myProvider, count: 3, owner: 'my-org', repo: 'my-repo', }); ```) #### Initializers ```typescript import { AlwaysOnWarmRunner } from '@cloudsnorkel/cdk-github-runners' new AlwaysOnWarmRunner(scope: Construct, id: string, props: AlwaysOnWarmRunnerProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | AlwaysOnWarmRunnerProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Required - *Type:* AlwaysOnWarmRunnerProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### `isConstruct` ```typescript import { AlwaysOnWarmRunner } from '@cloudsnorkel/cdk-github-runners' AlwaysOnWarmRunner.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. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ### CodeBuildRunnerProvider - *Implements:* IRunnerProvider, constructs.IConstruct GitHub Actions runner provider using CodeBuild to execute jobs. Creates a project that gets started for each job. This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners. #### Initializers ```typescript import { CodeBuildRunnerProvider } from '@cloudsnorkel/cdk-github-runners' new CodeBuildRunnerProvider(scope: Construct, id: string, props?: CodeBuildRunnerProviderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | CodeBuildRunnerProviderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* CodeBuildRunnerProviderProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | | imageBuilder | Create new image builder that builds CodeBuild specific runner images. | --- ##### `isConstruct` ```typescript import { CodeBuildRunnerProvider } from '@cloudsnorkel/cdk-github-runners' CodeBuildRunnerProvider.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. --- ##### `imageBuilder` ```typescript import { CodeBuildRunnerProvider } from '@cloudsnorkel/cdk-github-runners' CodeBuildRunnerProvider.imageBuilder(scope: Construct, id: string, props?: RunnerImageBuilderProps) ``` Create new image builder that builds CodeBuild specific runner images. You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props. You can add components to the image builder by calling `imageBuilder.addComponent()`. The default OS is Ubuntu running on x64 architecture. Included components: * `RunnerImageComponent.requiredPackages()` * `RunnerImageComponent.runnerUser()` * `RunnerImageComponent.git()` * `RunnerImageComponent.githubCli()` * `RunnerImageComponent.awsCli()` * `RunnerImageComponent.docker()` * `RunnerImageComponent.githubRunner()` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `props`^Optional - *Type:* RunnerImageBuilderProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | connections | aws-cdk-lib.aws_ec2.Connections | The network connections associated with this resource. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | Grant principal used to add permissions to the runner role. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | | project | aws-cdk-lib.aws_codebuild.Project | CodeBuild project hosting the runner. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### `grantPrincipal`^Required ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### `labels`^Required ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### `logGroup`^Required ```typescript public readonly logGroup: ILogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.ILogGroup Log group where provided runners will save their logs. Note that this is not the job log, but the runner itself. It will not contain output from the GitHub Action but only metadata on its execution. --- ##### `project`^Required ```typescript public readonly project: Project; ``` - *Type:* aws-cdk-lib.aws_codebuild.Project CodeBuild project hosting the runner. --- ### Ec2RunnerProvider - *Implements:* IRunnerProvider, constructs.IConstruct GitHub Actions runner provider using EC2 to execute jobs. This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners. #### Initializers ```typescript import { Ec2RunnerProvider } from '@cloudsnorkel/cdk-github-runners' new Ec2RunnerProvider(scope: Construct, id: string, props?: Ec2RunnerProviderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | Ec2RunnerProviderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* Ec2RunnerProviderProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | | imageBuilder | Create new image builder that builds EC2 specific runner images. | --- ##### `isConstruct` ```typescript import { Ec2RunnerProvider } from '@cloudsnorkel/cdk-github-runners' Ec2RunnerProvider.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. --- ##### `imageBuilder` ```typescript import { Ec2RunnerProvider } from '@cloudsnorkel/cdk-github-runners' Ec2RunnerProvider.imageBuilder(scope: Construct, id: string, props?: RunnerImageBuilderProps) ``` Create new image builder that builds EC2 specific runner images. You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props. You can add components to the image builder by calling `imageBuilder.addComponent()`. The default OS is Ubuntu running on x64 architecture. Included components: * `RunnerImageComponent.requiredPackages()` * `RunnerImageComponent.cloudWatchAgent()` * `RunnerImageComponent.runnerUser()` * `RunnerImageComponent.git()` * `RunnerImageComponent.githubCli()` * `RunnerImageComponent.awsCli()` * `RunnerImageComponent.docker()` * `RunnerImageComponent.githubRunner()` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `props`^Optional - *Type:* RunnerImageBuilderProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | connections | aws-cdk-lib.aws_ec2.Connections | The network connections associated with this resource. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | Grant principal used to add permissions to the runner role. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### `grantPrincipal`^Required ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### `labels`^Required ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### `logGroup`^Required ```typescript public readonly logGroup: ILogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.ILogGroup Log group where provided runners will save their logs. Note that this is not the job log, but the runner itself. It will not contain output from the GitHub Action but only metadata on its execution. --- ### EcsRunnerProvider - *Implements:* IRunnerProvider GitHub Actions runner provider using ECS on EC2 to execute jobs. ECS can be useful when you want more control of the infrastructure running the GitHub Actions Docker containers. You can control the autoscaling group to scale down to zero during the night and scale up during work hours. This way you can still save money, but have to wait less for infrastructure to spin up. Jobs share instances, and by default run in privileged containers on Linux that can take over the instance. All jobs that can run on the same cluster should be equally trusted. See https://github.com/CloudSnorkel/cdk-github-runners#job-isolation This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners. #### Initializers ```typescript import { EcsRunnerProvider } from '@cloudsnorkel/cdk-github-runners' new EcsRunnerProvider(scope: Construct, id: string, props?: EcsRunnerProviderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | EcsRunnerProviderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* EcsRunnerProviderProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | | imageBuilder | Create new image builder that builds ECS specific runner images. | --- ##### `isConstruct` ```typescript import { EcsRunnerProvider } from '@cloudsnorkel/cdk-github-runners' EcsRunnerProvider.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. --- ##### `imageBuilder` ```typescript import { EcsRunnerProvider } from '@cloudsnorkel/cdk-github-runners' EcsRunnerProvider.imageBuilder(scope: Construct, id: string, props?: RunnerImageBuilderProps) ``` Create new image builder that builds ECS specific runner images. You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props. You can add components to the image builder by calling `imageBuilder.addComponent()`. The default OS is Ubuntu running on x64 architecture. Included components: * `RunnerImageComponent.requiredPackages()` * `RunnerImageComponent.runnerUser()` * `RunnerImageComponent.git()` * `RunnerImageComponent.githubCli()` * `RunnerImageComponent.awsCli()` * `RunnerImageComponent.docker()` * `RunnerImageComponent.githubRunner()` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `props`^Optional - *Type:* RunnerImageBuilderProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | capacityProvider | aws-cdk-lib.aws_ecs.AsgCapacityProvider | Capacity provider used to scale the cluster. | | connections | aws-cdk-lib.aws_ec2.Connections | The network connections associated with this resource. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | Grant principal used to add permissions to the runner role. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `capacityProvider`^Required ```typescript public readonly capacityProvider: AsgCapacityProvider; ``` - *Type:* aws-cdk-lib.aws_ecs.AsgCapacityProvider Capacity provider used to scale the cluster. Use capacityProvider.autoScalingGroup to access the auto scaling group. This can help set up custom scaling policies. --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### `grantPrincipal`^Required ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### `labels`^Required ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### `logGroup`^Required ```typescript public readonly logGroup: ILogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.ILogGroup Log group where provided runners will save their logs. Note that this is not the job log, but the runner itself. It will not contain output from the GitHub Action but only metadata on its execution. --- ### FargateRunnerProvider - *Implements:* IRunnerProvider GitHub Actions runner provider using Fargate to execute jobs. Creates a task definition with a single container that gets started for each job. This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners. #### Initializers ```typescript import { FargateRunnerProvider } from '@cloudsnorkel/cdk-github-runners' new FargateRunnerProvider(scope: Construct, id: string, props?: FargateRunnerProviderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | FargateRunnerProviderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* FargateRunnerProviderProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | | imageBuilder | Create new image builder that builds Fargate specific runner images. | --- ##### `isConstruct` ```typescript import { FargateRunnerProvider } from '@cloudsnorkel/cdk-github-runners' FargateRunnerProvider.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. --- ##### `imageBuilder` ```typescript import { FargateRunnerProvider } from '@cloudsnorkel/cdk-github-runners' FargateRunnerProvider.imageBuilder(scope: Construct, id: string, props?: RunnerImageBuilderProps) ``` Create new image builder that builds Fargate specific runner images. You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props. You can add components to the image builder by calling `imageBuilder.addComponent()`. The default OS is Ubuntu running on x64 architecture. Included components: * `RunnerImageComponent.requiredPackages()` * `RunnerImageComponent.runnerUser()` * `RunnerImageComponent.git()` * `RunnerImageComponent.githubCli()` * `RunnerImageComponent.awsCli()` * `RunnerImageComponent.githubRunner()` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `props`^Optional - *Type:* RunnerImageBuilderProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | cluster | aws-cdk-lib.aws_ecs.Cluster | Cluster hosting the task hosting the runner. | | connections | aws-cdk-lib.aws_ec2.Connections | The network connections associated with this resource. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | Grant principal used to add permissions to the runner role. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `cluster`^Required ```typescript public readonly cluster: Cluster; ``` - *Type:* aws-cdk-lib.aws_ecs.Cluster Cluster hosting the task hosting the runner. --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### `grantPrincipal`^Required ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### `labels`^Required ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### `logGroup`^Required ```typescript public readonly logGroup: ILogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.ILogGroup Log group where provided runners will save their logs. Note that this is not the job log, but the runner itself. It will not contain output from the GitHub Action but only metadata on its execution. --- ### GitHubRunners - *Implements:* aws-cdk-lib.aws_ec2.IConnectable Create all the required infrastructure to provide self-hosted GitHub runners. It creates a webhook, secrets, and a step function to orchestrate all runs. Secrets are not automatically filled. See README.md for instructions on how to setup GitHub integration. By default, this will create a runner provider of each available type with the defaults. This is good enough for the initial setup stage when you just want to get GitHub integration working. ```typescript new GitHubRunners(this, 'runners'); ``` Usually you'd want to configure the runner providers so the runners can run in a certain VPC or have certain permissions. ```typescript const vpc = ec2.Vpc.fromLookup(this, 'vpc', { vpcId: 'vpc-1234567' }); const runnerSg = new ec2.SecurityGroup(this, 'runner security group', { vpc: vpc }); const dbSg = ec2.SecurityGroup.fromSecurityGroupId(this, 'database security group', 'sg-1234567'); const bucket = new s3.Bucket(this, 'runner bucket'); // create a custom CodeBuild provider const myProvider = new CodeBuildRunnerProvider( this, 'codebuild runner', { labels: ['my-codebuild'], vpc: vpc, securityGroups: [runnerSg], }, ); // grant some permissions to the provider bucket.grantReadWrite(myProvider); dbSg.connections.allowFrom(runnerSg, ec2.Port.tcp(3306), 'allow runners to connect to MySQL database'); // create the runner infrastructure new GitHubRunners( this, 'runners', { providers: [myProvider], } ); ``` #### Initializers ```typescript import { GitHubRunners } from '@cloudsnorkel/cdk-github-runners' new GitHubRunners(scope: Construct, id: string, props?: GitHubRunnersProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | GitHubRunnersProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* GitHubRunnersProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | | createDashboard | Creates a CloudWatch dashboard with the metrics you need to know if your runners are healthy. | | createLogsInsightsQueries | Creates CloudWatch Logs Insights saved queries that can be used to debug issues with the runners. | | failedImageBuildsTopic | Creates a topic for notifications when a runner image build fails. | | metricFailed | Metric for failed runner executions. | | metricJobCompleted | Metric for the number of GitHub Actions jobs completed. | | metricJobsMatchingMultipleProviders | Metric for the number of jobs whose labels matched more than one provider. | | metricLambdaErrors | Metric for the number of failed invocations of the management Lambda functions. | | metricStolenRunners | Metric for the number of runners that were stolen by a job that shouldn't have been assigned to them. | | metricStoppedRunners | Metric for the number of runners we stopped on purpose before they got a job. | | metricSucceeded | Metric for successful executions. | | metricTime | Metric for the interval, in milliseconds, between the time the execution starts and the time it closes. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- ##### `createDashboard` ```typescript public createDashboard(name?: string): Dashboard ``` Creates a CloudWatch dashboard with the metrics you need to know if your runners are healthy. It's split into sections, each with a short explanation of what its numbers mean and which ones to watch: * **Jobs**: are jobs running and passing, and which runner is failing them? * **Runners**: do runners start, how long do they take (and therefore cost), and why do they fail to start? * **Runner assignment**: are runners taken by jobs they weren't started for, do jobs match more than one provider, and why were runners stopped before getting a job? * **Management functions (orchestration)**: is GitHub reaching the webhook, and is any of our code failing? **WARNING:** this method calls {@link metricJobCompleted}, {@link metricStolenRunners}, {@link metricStoppedRunners} and {@link metricJobsMatchingMultipleProviders} which create metric filters. These resources may incur cost. This dashboard is very basic. Pull requests and issues are welcome to improve it. ###### `name`^Optional - *Type:* string Name of the dashboard. Defaults to "GitHub-Runners". --- ##### `createLogsInsightsQueries` ```typescript public createLogsInsightsQueries(prefix?: string): void ``` Creates CloudWatch Logs Insights saved queries that can be used to debug issues with the runners. * "Webhook errors" helps diagnose configuration issues with GitHub integration * "Ignored webhook" helps understand why runners aren't started * "Ignored jobs based on labels" helps debug label matching issues * "Webhook started runners" helps understand which runners were started * "Jobs matching multiple providers" lists jobs that need more labels so they match only one provider * "Warm runner status" and "Warm runner errors" (when warm runners are configured) ###### `prefix`^Optional - *Type:* string Prefix for the query definitions. Defaults to "GitHub Runners". --- ##### `failedImageBuildsTopic` ```typescript public failedImageBuildsTopic(scope?: Construct): Topic ``` Creates a topic for notifications when a runner image build fails. Runner images are rebuilt every week by default. This provides the latest GitHub Runner version and software updates. If you want to be sure you are using the latest runner version, you can use this topic to be notified when a build fails. Email subscribers get a short summary with the failure reason and a link to the logs. Other subscribers get the original JSON notification from CodeBuild or EC2 Image Builder. When the image builder is defined in a separate stack (e.g. in a split-stacks setup), pass that stack or construct as the optional scope so the topic and failure-notification aspects are created in the same stack as the image builder. Otherwise the aspects may not find the image builder resources. ###### `scope`^Optional - *Type:* constructs.Construct Optional scope (e.g. the image builder stack) where the topic and aspects will be created. Defaults to this construct. --- ##### `metricFailed` ```typescript public metricFailed(props?: MetricOptions): Metric ``` Metric for failed runner executions. A failed runner usually means the runner failed to start and so a job was never executed. It doesn't necessarily mean the job was executed and failed. For that, see {@link metricJobCompleted}. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricJobCompleted` ```typescript public metricJobCompleted(props?: MetricOptions): Metric ``` Metric for the number of GitHub Actions jobs completed. It has `ProviderLabels` and `Status` dimensions. The status can be one of "Succeeded", "SucceededWithIssues", "Failed", "Canceled", "Skipped", or "Abandoned". **WARNING:** this method creates a metric filter for each provider. Each metric has a status dimension with six possible values. These resources may incur cost. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricJobsMatchingMultipleProviders` ```typescript public metricJobsMatchingMultipleProviders(props?: MetricOptions): Metric ``` Metric for the number of jobs whose labels matched more than one provider. We start a runner from the first matching provider, but GitHub may give such a job a runner from any of them, including one started for another job. Stolen runner detection starts another runner for the job left behind, but the job itself may run on a provider you didn't expect. Anything over zero means some workflows ask for too few labels. Add labels to those jobs so they match only one provider. Use the "Jobs matching multiple providers" CloudWatch Logs Insights query created by {@link createLogsInsightsQueries} to find them. Jobs routed by a provider selector are not counted, as the selector picks the provider. **WARNING:** this method creates a metric filter. This resource may incur cost. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricLambdaErrors` ```typescript public metricLambdaErrors(props?: MathExpressionOptions): MathExpression ``` Metric for the number of failed invocations of the management Lambda functions. These are the functions that handle webhooks, retrieve runner tokens, stop idle runners, replace stolen runners, etc. Anything over zero means jobs may not have gotten a runner. You should use this metric to trigger an alarm. Only unhandled errors are counted here, as reported by Lambda itself. Errors that are handled and logged, like a webhook with a bad signature, are not failed invocations. Use the "Webhook errors" and "Orchestration errors" queries created by {@link createLogsInsightsQueries} to find those. Management functions created after this method is called are not included. Call it last if you use warm runners. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MathExpressionOptions --- ##### `metricStolenRunners` ```typescript public metricStolenRunners(props?: MetricOptions): Metric ``` Metric for the number of runners that were stolen by a job that shouldn't have been assigned to them. A high number here means your runners are shared with jobs you didn't mean to serve. Use the "Stolen runners" CloudWatch Logs Insights query created by {@link createLogsInsightsQueries} to see which repositories and jobs are taking them. This metric has two dimensions: 1. `Replaced` which is "true" or "false" indicating whether the stolen runner was replaced. A runner may not be replaced if it was stolen too many times in a row. The current limit is 3. When this is false, there is probably a bug in our detection or something misconfigured. 2. `Provider` is the provider construct path of the runner that was stolen. You can check your code to see which labels it has that may cause it to be stolen. The logs insights queries can provide even more information about the stolen runners. **WARNING:** this method creates a metric filter. This resource may incur cost. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricStoppedRunners` ```typescript public metricStoppedRunners(props?: MetricOptions): Metric ``` Metric for the number of runners we stopped on purpose before they got a job. These step function executions end up as aborted and not failed, so they don't show up in {@link metricFailed}. This metric has one dimension, `Reason`, which is the error the step function was stopped with: * `IdleRunner`: the runner was idle for longer than its idle timeout and was reaped. This is usually a runner whose job was taken by another runner, or a job that was canceled before it started. * `StaleWarmRunner`: a warm runner was replaced because its configuration changed. * `WarmRunnerExpired`: a warm runner reached the end of its duration. * `WarmRunnerBadDeadline`: a warm runner had an invalid deadline and was stopped. **WARNING:** this method creates a metric filter. This resource may incur cost. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricSucceeded` ```typescript public metricSucceeded(props?: MetricOptions): Metric ``` Metric for successful executions. A successful execution doesn't always mean a runner was started. It can be successful even without any label matches. A successful runner doesn't mean the job it executed was successful. For that, see {@link metricJobCompleted}. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- ##### `metricTime` ```typescript public metricTime(props?: MetricOptions): Metric ``` Metric for the interval, in milliseconds, between the time the execution starts and the time it closes. This time may be longer than the time the runner took. ###### `props`^Optional - *Type:* aws-cdk-lib.aws_cloudwatch.MetricOptions --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### `isConstruct` ```typescript import { GitHubRunners } from '@cloudsnorkel/cdk-github-runners' GitHubRunners.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. | | connections | aws-cdk-lib.aws_ec2.Connections | Manage the connections of all management functions. | | providers | IRunnerProvider \| ICompositeProvider[] | Configured runner providers. | | secrets | Secrets | Secrets for GitHub communication including webhook secret and runner authentication. | | props | GitHubRunnersProps | *No description.* | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections Manage the connections of all management functions. Use this to enable connections to your GitHub Enterprise Server in a VPC. This cannot be used to manage connections of the runners. Use the `connections` property of each runner provider to manage runner connections. --- ##### `providers`^Required ```typescript public readonly providers: (IRunnerProvider | ICompositeProvider)[]; ``` - *Type:* IRunnerProvider | ICompositeProvider[] Configured runner providers. --- ##### `secrets`^Required ```typescript public readonly secrets: Secrets; ``` - *Type:* Secrets Secrets for GitHub communication including webhook secret and runner authentication. --- ##### `props`^Optional ```typescript public readonly props: GitHubRunnersProps; ``` - *Type:* GitHubRunnersProps --- ### LambdaRunnerProvider - *Implements:* IRunnerProvider GitHub Actions runner provider using Lambda to execute jobs. Creates a Docker-based function that gets executed for each job. Execution environments can be reused between jobs. All jobs that can run on the same function should be equally trusted. See https://github.com/CloudSnorkel/cdk-github-runners#job-isolation This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners. #### Initializers ```typescript import { LambdaRunnerProvider } from '@cloudsnorkel/cdk-github-runners' new LambdaRunnerProvider(scope: Construct, id: string, props?: LambdaRunnerProviderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | LambdaRunnerProviderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* LambdaRunnerProviderProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | | imageBuilder | Create new image builder that builds Lambda specific runner images. | --- ##### `isConstruct` ```typescript import { LambdaRunnerProvider } from '@cloudsnorkel/cdk-github-runners' LambdaRunnerProvider.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. --- ##### `imageBuilder` ```typescript import { LambdaRunnerProvider } from '@cloudsnorkel/cdk-github-runners' LambdaRunnerProvider.imageBuilder(scope: Construct, id: string, props?: RunnerImageBuilderProps) ``` Create new image builder that builds Lambda specific runner images. You can customize the OS, architecture, VPC, subnet, security groups, etc. by passing in props. You can add components to the image builder by calling `imageBuilder.addComponent()`. The default OS is Amazon Linux 2023 running on x64 architecture. Included components: * `RunnerImageComponent.requiredPackages()` * `RunnerImageComponent.runnerUser()` * `RunnerImageComponent.git()` * `RunnerImageComponent.githubCli()` * `RunnerImageComponent.awsCli()` * `RunnerImageComponent.githubRunner()` * `RunnerImageComponent.lambdaEntrypoint()` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `props`^Optional - *Type:* RunnerImageBuilderProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | connections | aws-cdk-lib.aws_ec2.Connections | The network connections associated with this resource. | | function | aws-cdk-lib.aws_lambda.Function | The function hosting the GitHub runner. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | Grant principal used to add permissions to the runner role. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### `function`^Required ```typescript public readonly function: Function; ``` - *Type:* aws-cdk-lib.aws_lambda.Function The function hosting the GitHub runner. --- ##### `grantPrincipal`^Required ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### `labels`^Required ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### `logGroup`^Required ```typescript public readonly logGroup: ILogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.ILogGroup Log group where provided runners will save their logs. Note that this is not the job log, but the runner itself. It will not contain output from the GitHub Action but only metadata on its execution. --- ### RunnerImageBuilder - *Implements:* IConfigurableRunnerImageBuilder GitHub Runner image builder. Builds a Docker image or AMI with GitHub Runner and other requirements installed. Images can be customized before passed into the provider by adding or removing components to be installed. Images are rebuilt every week by default to ensure that the latest security patches are applied. #### Initializers ```typescript import { RunnerImageBuilder } from '@cloudsnorkel/cdk-github-runners' new RunnerImageBuilder(scope: Construct, id: string, props?: RunnerImageBuilderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | RunnerImageBuilderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* RunnerImageBuilderProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | | addComponent | Add a component to the image builder. | | bindAmi | Build and return an AMI with GitHub Runner installed in it. | | bindDockerImage | Build and return a Docker image with GitHub Runner installed in it. | | removeComponent | Remove a component from the image builder. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- ##### `addComponent` ```typescript public addComponent(component: RunnerImageComponent): void ``` Add a component to the image builder. The component will be added to the end of the list of components. ###### `component`^Required - *Type:* RunnerImageComponent --- ##### `bindAmi` ```typescript public bindAmi(): RunnerAmi ``` Build and return an AMI with GitHub Runner installed in it. Anything that ends up with a launch template pointing to an AMI that runs GitHub self-hosted runners can be used. A simple implementation could even point to an existing AMI and nothing else. The AMI can be further updated over time manually or using a schedule as long as it is always written to the same launch template. ##### `bindDockerImage` ```typescript public bindDockerImage(): RunnerImage ``` Build and return a Docker image with GitHub Runner installed in it. Anything that ends up with an ECR repository containing a Docker image that runs GitHub self-hosted runners can be used. A simple implementation could even point to an existing image and nothing else. It's important that the specified image tag be available at the time the repository is available. Providers usually assume the image is ready and will fail if it's not. The image can be further updated over time manually or using a schedule as long as it is always written to the same tag. ##### `removeComponent` ```typescript public removeComponent(component: RunnerImageComponent): void ``` Remove a component from the image builder. Removal is done by component name. Multiple components with the same name will all be removed. ###### `component`^Required - *Type:* RunnerImageComponent --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | | new | Create a new image builder based on the provided properties. | --- ##### `isConstruct` ```typescript import { RunnerImageBuilder } from '@cloudsnorkel/cdk-github-runners' RunnerImageBuilder.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. --- ##### `new` ```typescript import { RunnerImageBuilder } from '@cloudsnorkel/cdk-github-runners' RunnerImageBuilder.new(scope: Construct, id: string, props?: RunnerImageBuilderProps) ``` Create a new image builder based on the provided properties. The implementation will differ based on the OS, architecture, and requested builder type. ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `props`^Optional - *Type:* RunnerImageBuilderProps --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | connections | aws-cdk-lib.aws_ec2.Connections | The network connections associated with this resource. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | The principal to grant permissions to. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### `grantPrincipal`^Required ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to. --- ### ScheduledWarmRunner Warm runners active during a time window specified by start time (`schedule`) and duration (`duration`). Runners will be provisioned using the specified provider and registered in the specified repository or organization. Registration level must match the one selected during setup. > [https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md **Limitations** - **No deployment-fill**: Unlike `AlwaysOnWarmRunner`, scheduled warm runners do not get an initial fill on deploy. The first fill happens at the next schedule occurrence. If you deploy at 1pm for a 2pm schedule, runners will not appear until 2pm. - Jobs will still trigger provisioning of on-demand runners, even if a warm runner ends up being used. - You may briefly see more than `count` runners when changing config or at rotation. - To remove: set `count` to 0, deploy, wait for warm runners to stop, then remove and deploy again. If you don't follow this procedure, warm runners may linger until they expire. - Provider failures or timeouts (like Lambda provider timing out after 15 minutes) will result in a gap in coverage until the retry succeeds. Current retry mechanism has built-in back-off rate and can be tweaked using `retryOptions`. This will be improved in the future. ```typescript // Cron: fill at 1pm on weekdays new ScheduledWarmRunner(stack, 'Business Hours', { runners, provider: myProvider, count: 3, owner: 'my-org', repo: 'my-repo', schedule: events.Schedule.cron({ hour: '13', minute: '0', weekDay: 'MON-FRI' }), duration: cdk.Duration.hours(2), }); ``` ```typescript // Rate: fill every 12 hours new ScheduledWarmRunner(stack, 'Every 12 Hours', { runners, provider: myProvider, count: 2, owner: 'my-org', repo: 'my-repo', schedule: events.Schedule.rate(cdk.Duration.hours(5)), duration: cdk.Duration.hours(12), }); ```](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md **Limitations** - **No deployment-fill**: Unlike `AlwaysOnWarmRunner`, scheduled warm runners do not get an initial fill on deploy. The first fill happens at the next schedule occurrence. If you deploy at 1pm for a 2pm schedule, runners will not appear until 2pm. - Jobs will still trigger provisioning of on-demand runners, even if a warm runner ends up being used. - You may briefly see more than `count` runners when changing config or at rotation. - To remove: set `count` to 0, deploy, wait for warm runners to stop, then remove and deploy again. If you don't follow this procedure, warm runners may linger until they expire. - Provider failures or timeouts (like Lambda provider timing out after 15 minutes) will result in a gap in coverage until the retry succeeds. Current retry mechanism has built-in back-off rate and can be tweaked using `retryOptions`. This will be improved in the future. ```typescript // Cron: fill at 1pm on weekdays new ScheduledWarmRunner(stack, 'Business Hours', { runners, provider: myProvider, count: 3, owner: 'my-org', repo: 'my-repo', schedule: events.Schedule.cron({ hour: '13', minute: '0', weekDay: 'MON-FRI' }), duration: cdk.Duration.hours(2), }); ``` ```typescript // Rate: fill every 12 hours new ScheduledWarmRunner(stack, 'Every 12 Hours', { runners, provider: myProvider, count: 2, owner: 'my-org', repo: 'my-repo', schedule: events.Schedule.rate(cdk.Duration.hours(5)), duration: cdk.Duration.hours(12), }); ```) #### Initializers ```typescript import { ScheduledWarmRunner } from '@cloudsnorkel/cdk-github-runners' new ScheduledWarmRunner(scope: Construct, id: string, props: ScheduledWarmRunnerProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | ScheduledWarmRunnerProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Required - *Type:* ScheduledWarmRunnerProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### `isConstruct` ```typescript import { ScheduledWarmRunner } from '@cloudsnorkel/cdk-github-runners' ScheduledWarmRunner.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. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ### Secrets Secrets required for GitHub runners operation. #### Initializers ```typescript import { Secrets } from '@cloudsnorkel/cdk-github-runners' new Secrets(scope: Construct, id: string) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript 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. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### `isConstruct` ```typescript import { Secrets } from '@cloudsnorkel/cdk-github-runners' Secrets.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. | | github | aws-cdk-lib.aws_secretsmanager.Secret | Authentication secret for GitHub containing either app details or personal access token. | | githubPrivateKey | aws-cdk-lib.aws_secretsmanager.Secret | GitHub app private key. Not needed when using personal access tokens. | | setup | aws-cdk-lib.aws_secretsmanager.Secret | Setup secret used to authenticate user for our setup wizard. | | webhook | aws-cdk-lib.aws_secretsmanager.Secret | Webhook secret used to confirm events are coming from GitHub and nowhere else. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `github`^Required ```typescript public readonly github: Secret; ``` - *Type:* aws-cdk-lib.aws_secretsmanager.Secret Authentication secret for GitHub containing either app details or personal access token. This secret is used to register runners and cancel jobs when the runner fails to start. This secret is meant to be edited by the user after being created. --- ##### `githubPrivateKey`^Required ```typescript public readonly githubPrivateKey: Secret; ``` - *Type:* aws-cdk-lib.aws_secretsmanager.Secret GitHub app private key. Not needed when using personal access tokens. This secret is meant to be edited by the user after being created. It is separate than the main GitHub secret because inserting private keys into JSON is hard. --- ##### `setup`^Required ```typescript public readonly setup: Secret; ``` - *Type:* aws-cdk-lib.aws_secretsmanager.Secret Setup secret used to authenticate user for our setup wizard. Should be empty after setup has been completed. --- ##### `webhook`^Required ```typescript public readonly webhook: Secret; ``` - *Type:* aws-cdk-lib.aws_secretsmanager.Secret Webhook secret used to confirm events are coming from GitHub and nowhere else. --- ## Structs ### AlwaysOnWarmRunnerProps Properties for always on warm runners. #### Initializer ```typescript import { AlwaysOnWarmRunnerProps } from '@cloudsnorkel/cdk-github-runners' const alwaysOnWarmRunnerProps: AlwaysOnWarmRunnerProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | count | number | Number of warm runners to maintain. | | owner | string | GitHub owner where runners will be registered (org or user login). | | provider | IRunnerProvider \| ICompositeProvider | Provider to use. | | runners | GitHubRunners | The GitHubRunners construct that owns the shared warm runner infrastructure. | | registrationLevel | string | Registration level — must match how your runners are set up in GitHub. | | repo | string | Repository name (without owner) where runners will be registered. | --- ##### `count`^Required ```typescript public readonly count: number; ``` - *Type:* number Number of warm runners to maintain. --- ##### `owner`^Required ```typescript public readonly owner: string; ``` - *Type:* string GitHub owner where runners will be registered (org or user login). --- ##### `provider`^Required ```typescript public readonly provider: IRunnerProvider | ICompositeProvider; ``` - *Type:* IRunnerProvider | ICompositeProvider Provider to use. Warm runners bypass the provider selector — they always use this provider, regardless of job characteristics. Labels cannot be modified. --- ##### `runners`^Required ```typescript public readonly runners: GitHubRunners; ``` - *Type:* GitHubRunners The GitHubRunners construct that owns the shared warm runner infrastructure. --- ##### `registrationLevel`^Optional ```typescript public readonly registrationLevel: string; ``` - *Type:* string - *Default:* 'repo' Registration level — must match how your runners are set up in GitHub. Choose 'org' for org-wide runners, 'repo' for repo-level. See the setup wizard for choosing repo vs org. > [https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md) --- ##### `repo`^Optional ```typescript public readonly repo: string; ``` - *Type:* string Repository name (without owner) where runners will be registered. Required when `registrationLevel` is 'repo'. --- ### ApiGatewayAccessProps #### Initializer ```typescript import { ApiGatewayAccessProps } from '@cloudsnorkel/cdk-github-runners' const apiGatewayAccessProps: ApiGatewayAccessProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | allowedIps | string[] | List of IP addresses in CIDR notation that are allowed to access the API Gateway. | | allowedSecurityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | List of security groups that are allowed to access the API Gateway. | | allowedVpc | aws-cdk-lib.aws_ec2.IVpc | Create a private API Gateway and allow access from the specified VPC. | | allowedVpcEndpoints | aws-cdk-lib.aws_ec2.IVpcEndpoint[] | Create a private API Gateway and allow access from the specified VPC endpoints. | --- ##### `allowedIps`^Optional ```typescript public readonly allowedIps: string[]; ``` - *Type:* string[] List of IP addresses in CIDR notation that are allowed to access the API Gateway. If not specified on public API Gateway, all IP addresses are allowed. If not specified on private API Gateway, no IP addresses are allowed (but specified security groups are). --- ##### `allowedSecurityGroups`^Optional ```typescript public readonly allowedSecurityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] List of security groups that are allowed to access the API Gateway. Only works for private API Gateways with {@link allowedVpc}. --- ##### `allowedVpc`^Optional ```typescript public readonly allowedVpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc Create a private API Gateway and allow access from the specified VPC. --- ##### `allowedVpcEndpoints`^Optional ```typescript public readonly allowedVpcEndpoints: IVpcEndpoint[]; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpcEndpoint[] Create a private API Gateway and allow access from the specified VPC endpoints. Use this to make use of existing VPC endpoints or to share an endpoint between multiple functions. The VPC endpoint must point to `ec2.InterfaceVpcEndpointAwsService.APIGATEWAY`. No other settings are supported when using this option. All endpoints will be allowed access, but only the first one will be used as the URL by the runner system for setting up the webhook, and as setup URL. --- ### AwsImageBuilderRunnerImageBuilderProps #### Initializer ```typescript import { AwsImageBuilderRunnerImageBuilderProps } from '@cloudsnorkel/cdk-github-runners' const awsImageBuilderRunnerImageBuilderProps: AwsImageBuilderRunnerImageBuilderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | amiTags | {[ key: string ]: string} | Additional tags to apply to the AMI built by this builder. | | fastLaunchOptions | FastLaunchOptions | Options for fast launch. | | instanceType | aws-cdk-lib.aws_ec2.InstanceType | The instance type used to build the image. | | storageSize | aws-cdk-lib.Size | Size of volume available for builder instances. This modifies the boot volume size and doesn't add any additional volumes. | --- ##### `amiTags`^Optional ```typescript public readonly amiTags: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} - *Default:* no additional tags Additional tags to apply to the AMI built by this builder. These additional tags are set on top of `Name`, `GitHubRunners:Stack`, and `GitHubRunners:Builder`. You may override the built-in tags. Overriding `GitHubRunners:Stack` will stop old AMIs from being deleted, as the image cleaner is only allowed to touch AMIs tagged with the name of the stack it lives in. You will have to delete those AMIs yourself. --- ##### `fastLaunchOptions`^Optional ```typescript public readonly fastLaunchOptions: FastLaunchOptions; ``` - *Type:* FastLaunchOptions - *Default:* disabled Options for fast launch. This is only supported for Windows AMIs. --- ##### `instanceType`^Optional ```typescript public readonly instanceType: InstanceType; ``` - *Type:* aws-cdk-lib.aws_ec2.InstanceType - *Default:* m6i.large The instance type used to build the image. --- ##### `storageSize`^Optional ```typescript public readonly storageSize: Size; ``` - *Type:* aws-cdk-lib.Size - *Default:* default size for AMI (usually 30GB for Linux and 50GB for Windows) Size of volume available for builder instances. This modifies the boot volume size and doesn't add any additional volumes. Use this if you're building images with big components and need more space. --- ### CodeBuildRunnerImageBuilderProps #### Initializer ```typescript import { CodeBuildRunnerImageBuilderProps } from '@cloudsnorkel/cdk-github-runners' const codeBuildRunnerImageBuilderProps: CodeBuildRunnerImageBuilderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | buildImage | aws-cdk-lib.aws_codebuild.IBuildImage | Build image to use in CodeBuild. | | computeType | aws-cdk-lib.aws_codebuild.ComputeType | The type of compute to use for this build. See the {@link ComputeType} enum for the possible values. | | timeout | aws-cdk-lib.Duration | The number of minutes after which AWS CodeBuild stops the build if it's not complete. | --- ##### `buildImage`^Optional ```typescript public readonly buildImage: IBuildImage; ``` - *Type:* aws-cdk-lib.aws_codebuild.IBuildImage - *Default:* Amazon Linux 2023 Build image to use in CodeBuild. This is the image that's going to run the code that builds the runner image. The only action taken in CodeBuild is running `docker build`. You would therefore not need to change this setting often. --- ##### `computeType`^Optional ```typescript public readonly computeType: ComputeType; ``` - *Type:* aws-cdk-lib.aws_codebuild.ComputeType - *Default:* {@link ComputeType#SMALL } The type of compute to use for this build. See the {@link ComputeType} enum for the possible values. The compute type determines CPU, memory, and disk space: - SMALL: 2 vCPU, 3 GB RAM, 64 GB disk - MEDIUM: 4 vCPU, 7 GB RAM, 128 GB disk - LARGE: 8 vCPU, 15 GB RAM, 128 GB disk - X2_LARGE: 72 vCPU, 145 GB RAM, 256 GB disk (Linux) or 824 GB disk (Windows) Use a larger compute type when you need more disk space for building larger Docker images. For more details, see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html#environment.types --- ##### `timeout`^Optional ```typescript public readonly timeout: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* Duration.hours(1) The number of minutes after which AWS CodeBuild stops the build if it's not complete. For valid values, see the timeoutInMinutes field in the AWS CodeBuild User Guide. --- ### CodeBuildRunnerProviderProps #### Initializer ```typescript import { CodeBuildRunnerProviderProps } from '@cloudsnorkel/cdk-github-runners' const codeBuildRunnerProviderProps: CodeBuildRunnerProviderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | defaultLabels | boolean | Add default labels based on OS and architecture of the runner. | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | | computeType | aws-cdk-lib.aws_codebuild.ComputeType | The type of compute to use for this build. See the {@link ComputeType} enum for the possible values. | | dockerInDocker | boolean | Support building and running Docker images by enabling Docker-in-Docker (dind) and the required CodeBuild privileged mode. | | gpu | boolean | Use GPU compute for builds. | | group | string | GitHub Actions runner group name. | | imageBuilder | IRunnerImageBuilder | Runner image builder used to build Docker images containing GitHub Runner and all requirements. | | labels | string[] | GitHub Actions labels used for this provider. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups to assign to this instance. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Where to place the network interfaces within the VPC. | | timeout | aws-cdk-lib.Duration | The number of minutes after which AWS CodeBuild stops the build if it's not complete. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC to launch the runners in. | --- ##### `defaultLabels`^Optional ```typescript public readonly defaultLabels: boolean; ``` - *Type:* boolean - *Default:* true Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`. --- ##### `logRetention`^Optional ```typescript public readonly logRetention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* logs.RetentionDays.ONE_MONTH The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to `INFINITE`. --- ##### `computeType`^Optional ```typescript public readonly computeType: ComputeType; ``` - *Type:* aws-cdk-lib.aws_codebuild.ComputeType - *Default:* {@link ComputeType#SMALL } The type of compute to use for this build. See the {@link ComputeType} enum for the possible values. The compute type determines CPU, memory, and disk space: - SMALL: 2 vCPU, 3 GB RAM, 64 GB disk - MEDIUM: 4 vCPU, 7 GB RAM, 128 GB disk - LARGE: 8 vCPU, 15 GB RAM, 128 GB disk - X2_LARGE: 72 vCPU, 145 GB RAM, 256 GB disk (Linux) or 824 GB disk (Windows) Use a larger compute type when you need more disk space for building larger Docker images. For more details, see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html#environment.types --- ##### `dockerInDocker`^Optional ```typescript public readonly dockerInDocker: boolean; ``` - *Type:* boolean - *Default:* true Support building and running Docker images by enabling Docker-in-Docker (dind) and the required CodeBuild privileged mode. Disabling this can speed up provisioning of CodeBuild runners. If you don't intend on running or building Docker images, disable this for faster start-up times. --- ##### `gpu`^Optional ```typescript public readonly gpu: boolean; ``` - *Type:* boolean - *Default:* false Use GPU compute for builds. When enabled, the default compute type is BUILD_GENERAL1_SMALL (4 vCPU, 16 GB RAM, 1 NVIDIA A10G GPU). You can override the compute type using the `computeType` property (for example, to use BUILD_GENERAL1_LARGE for more resources), subject to the supported GPU compute types. When using GPU compute, ensure your runner image includes any required GPU libraries (for example, CUDA) either by using a base image that has them preinstalled (such as an appropriate nvidia/cuda image) or by adding image components that install them. The default image builder does not automatically switch to a CUDA-enabled base image when GPU is enabled. GPU compute is only available for Linux x64 images. Not supported on Windows or ARM. --- ##### `group`^Optional ```typescript public readonly group: string; ``` - *Type:* string - *Default:* undefined GitHub Actions runner group name. If specified, the runner will be registered with this group name. Setting a runner group can help managing access to self-hosted runners. It requires a paid GitHub account and organization level runner registration. The group must exist or the runner will not start. Users will still be able to trigger this runner with the correct labels. But the runner will only be able to run jobs from repos allowed to use the group. --- ##### `imageBuilder`^Optional ```typescript public readonly imageBuilder: IRunnerImageBuilder; ``` - *Type:* IRunnerImageBuilder - *Default:* CodeBuildRunnerProvider.imageBuilder() Runner image builder used to build Docker images containing GitHub Runner and all requirements. The image builder must contain the {@link RunnerImageComponent.docker} component unless `dockerInDocker` is set to false. The image builder determines the OS and architecture of the runner. --- ##### `labels`^Optional ```typescript public readonly labels: string[]; ``` - *Type:* string[] - *Default:* ['codebuild'] GitHub Actions labels used for this provider. These labels are used to identify which provider should spawn a new on-demand runner. Every job sends a webhook with the labels it's looking for based on runs-on. We match the labels from the webhook with the labels specified here. If all the labels specified here are present in the job's labels, this provider will be chosen and spawn a new runner. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] - *Default:* a new security group, if {@link vpc } is used Security groups to assign to this instance. --- ##### `subnetSelection`^Optional ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection - *Default:* no subnet Where to place the network interfaces within the VPC. --- ##### `timeout`^Optional ```typescript public readonly timeout: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* Duration.hours(1) The number of minutes after which AWS CodeBuild stops the build if it's not complete. For valid values, see the timeoutInMinutes field in the AWS CodeBuild User Guide. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc - *Default:* no VPC VPC to launch the runners in. --- ### Ec2RunnerProviderProps Properties for {@link Ec2RunnerProvider} construct. #### Initializer ```typescript import { Ec2RunnerProviderProps } from '@cloudsnorkel/cdk-github-runners' const ec2RunnerProviderProps: Ec2RunnerProviderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | defaultLabels | boolean | Add default labels based on OS and architecture of the runner. | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | | group | string | GitHub Actions runner group name. | | imageBuilder | IRunnerImageBuilder | Runner image builder used to build AMI containing GitHub Runner and all requirements. | | instanceType | aws-cdk-lib.aws_ec2.InstanceType | Instance type for launched runner instances. | | labels | string[] | GitHub Actions labels used for this provider. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups to assign to launched runner instances. | | spot | boolean | Use spot instances to save money. | | spotMaxPrice | string | Set a maximum price for spot instances. | | storageOptions | StorageOptions | Options for runner instance storage volume. | | storageSize | aws-cdk-lib.Size | Size of volume available for launched runner instances. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Where to place the network interfaces within the VPC. | | tags | {[ key: string ]: string} | Additional tags to apply to launched runner instances and their volumes. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC where runner instances will be launched. | --- ##### `defaultLabels`^Optional ```typescript public readonly defaultLabels: boolean; ``` - *Type:* boolean - *Default:* true Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`. --- ##### `logRetention`^Optional ```typescript public readonly logRetention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* logs.RetentionDays.ONE_MONTH The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to `INFINITE`. --- ##### `group`^Optional ```typescript public readonly group: string; ``` - *Type:* string - *Default:* undefined GitHub Actions runner group name. If specified, the runner will be registered with this group name. Setting a runner group can help managing access to self-hosted runners. It requires a paid GitHub account and organization level runner registration. The group must exist or the runner will not start. Users will still be able to trigger this runner with the correct labels. But the runner will only be able to run jobs from repos allowed to use the group. --- ##### `imageBuilder`^Optional ```typescript public readonly imageBuilder: IRunnerImageBuilder; ``` - *Type:* IRunnerImageBuilder - *Default:* Ec2RunnerProvider.imageBuilder() Runner image builder used to build AMI containing GitHub Runner and all requirements. The image builder determines the OS and architecture of the runner. --- ##### `instanceType`^Optional ```typescript public readonly instanceType: InstanceType; ``` - *Type:* aws-cdk-lib.aws_ec2.InstanceType - *Default:* m6i.large Instance type for launched runner instances. For GPU instance types (g4dn, g5, p3, etc.), we automatically use a GPU base image (AWS Deep Learning AMI) with NVIDIA drivers pre-installed. If you provide your own image builder, use `baseAmi: BaseImage.fromGpuBase(os, architecture)` or another image preloaded with NVIDIA drivers, or use an image component to install NVIDIA drivers. --- ##### `labels`^Optional ```typescript public readonly labels: string[]; ``` - *Type:* string[] - *Default:* ['ec2'] GitHub Actions labels used for this provider. These labels are used to identify which provider should spawn a new on-demand runner. Every job sends a webhook with the labels it's looking for based on runs-on. We match the labels from the webhook with the labels specified here. If all the labels specified here are present in the job's labels, this provider will be chosen and spawn a new runner. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] - *Default:* a new security group Security groups to assign to launched runner instances. --- ##### `spot`^Optional ```typescript public readonly spot: boolean; ``` - *Type:* boolean - *Default:* false Use spot instances to save money. Spot instances are cheaper but not always available and can be stopped prematurely. --- ##### `spotMaxPrice`^Optional ```typescript public readonly spotMaxPrice: string; ``` - *Type:* string - *Default:* no max price (you will pay current spot price) Set a maximum price for spot instances. --- ##### `storageOptions`^Optional ```typescript public readonly storageOptions: StorageOptions; ``` - *Type:* StorageOptions Options for runner instance storage volume. --- ##### `storageSize`^Optional ```typescript public readonly storageSize: Size; ``` - *Type:* aws-cdk-lib.Size - *Default:* 30GB Size of volume available for launched runner instances. This modifies the boot volume size and doesn't add any additional volumes. --- ##### `subnetSelection`^Optional ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection - *Default:* default VPC subnet Where to place the network interfaces within the VPC. Only the first matched subnet will be used. --- ##### `tags`^Optional ```typescript public readonly tags: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} - *Default:* no additional tags Additional tags to apply to launched runner instances and their volumes. These additional tags are set on top of `Name`, `GitHubRunners:Provider`, `GitHubRunners:Repo`, and `GitHubRunners:Labels`, and `GitHubRunners:Runner`. You may only override `Name`. Tags prefixed `GitHubRunners:` are reserved and rejected. Some of our reserved tags are used for house-keeping purposes. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc - *Default:* default account VPC VPC where runner instances will be launched. --- ### EcsRunnerProviderProps Properties for EcsRunnerProvider. #### Initializer ```typescript import { EcsRunnerProviderProps } from '@cloudsnorkel/cdk-github-runners' const ecsRunnerProviderProps: EcsRunnerProviderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | defaultLabels | boolean | Add default labels based on OS and architecture of the runner. | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | | capacityProvider | aws-cdk-lib.aws_ecs.AsgCapacityProvider | Existing capacity provider to use. | | cluster | aws-cdk-lib.aws_ecs.Cluster | Existing ECS cluster to use. | | cpu | number | The number of cpu units used by the task. | | dockerInDocker | boolean | Support building and running Docker images by enabling Docker-in-Docker (dind) and the required privileged mode for the runner container. | | gpu | number | Number of GPUs to request for the runner task. When set, the task will be scheduled on GPU-capable instances. | | group | string | GitHub Actions runner group name. | | imageBuilder | IRunnerImageBuilder | Runner image builder used to build Docker images containing GitHub Runner and all requirements. | | instanceType | aws-cdk-lib.aws_ec2.InstanceType | Instance type of ECS cluster instances. | | labels | string[] | GitHub Actions labels used for this provider. | | maxInstances | number | The maximum number of instances to run in the cluster. | | memoryLimitMiB | number | The amount (in MiB) of memory used by the task. | | memoryReservationMiB | number | The soft limit (in MiB) of memory to reserve for the container. | | minInstances | number | The minimum number of instances to run in the cluster. | | placementConstraints | aws-cdk-lib.aws_ecs.PlacementConstraint[] | ECS placement constraints to influence task placement. | | placementStrategies | aws-cdk-lib.aws_ecs.PlacementStrategy[] | ECS placement strategies to influence task placement. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups to assign to the task. | | spot | boolean | Use spot capacity. | | spotMaxPrice | string | Maximum price for spot instances. | | storageOptions | StorageOptions | Options for runner instance storage volume. | | storageSize | aws-cdk-lib.Size | Size of volume available for launched cluster instances. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Subnets to run the runners in. | | tags | {[ key: string ]: string} | Additional tags to apply to launched runner tasks. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC to launch the runners in. | --- ##### `defaultLabels`^Optional ```typescript public readonly defaultLabels: boolean; ``` - *Type:* boolean - *Default:* true Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`. --- ##### `logRetention`^Optional ```typescript public readonly logRetention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* logs.RetentionDays.ONE_MONTH The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to `INFINITE`. --- ##### `capacityProvider`^Optional ```typescript public readonly capacityProvider: AsgCapacityProvider; ``` - *Type:* aws-cdk-lib.aws_ecs.AsgCapacityProvider - *Default:* new capacity provider Existing capacity provider to use. Make sure the AMI used by the capacity provider is compatible with ECS. Runner containers use bridge networking and share the instance with other jobs. Its launch template must require IMDSv2 and set the metadata hop limit to 1 (`requireImdsv2: true` and `httpPutResponseHopLimit: 1`), or jobs can take the instance role. A warning is added when we can't confirm both. --- ##### `cluster`^Optional ```typescript public readonly cluster: Cluster; ``` - *Type:* aws-cdk-lib.aws_ecs.Cluster - *Default:* a new cluster Existing ECS cluster to use. Jobs from all providers using the same cluster can share instances. Only share a cluster between providers whose jobs are equally trusted. > [https://github.com/CloudSnorkel/cdk-github-runners#job-isolation](https://github.com/CloudSnorkel/cdk-github-runners#job-isolation) --- ##### `cpu`^Optional ```typescript public readonly cpu: number; ``` - *Type:* number - *Default:* 1024 The number of cpu units used by the task. 1024 units is 1 vCPU. Fractions of a vCPU are supported. --- ##### `dockerInDocker`^Optional ```typescript public readonly dockerInDocker: boolean; ``` - *Type:* boolean - *Default:* true Support building and running Docker images by enabling Docker-in-Docker (dind) and the required privileged mode for the runner container. A job running in a privileged container can take over the instance, access other jobs running on it, and affect jobs that run on it later. All jobs that can run on the same cluster should be equally trusted. Disable this if your jobs don't need Docker. Disabling Docker-in-Docker can also speed up runner provisioning as the runner doesn't have to wait for Docker to boot. > [https://github.com/CloudSnorkel/cdk-github-runners#job-isolation](https://github.com/CloudSnorkel/cdk-github-runners#job-isolation) --- ##### `gpu`^Optional ```typescript public readonly gpu: number; ``` - *Type:* number - *Default:* undefined (no GPU) Number of GPUs to request for the runner task. When set, the task will be scheduled on GPU-capable instances. Requires a GPU-capable instance type (e.g., g4dn.xlarge for 1 GPU, g4dn.12xlarge for 4 GPUs) and GPU AMI. When creating a new cluster, instanceType defaults to g4dn.xlarge and the ECS Optimized GPU AMI is used. You must ensure that the task's container image includes the CUDA runtime. Provide a CUDA-enabled base image via `baseDockerImage`, use an image builder that starts from a GPU-capable image (such as nvidia/cuda), or add an image component that installs the CUDA runtime into the image. --- ##### `group`^Optional ```typescript public readonly group: string; ``` - *Type:* string - *Default:* undefined GitHub Actions runner group name. If specified, the runner will be registered with this group name. Setting a runner group can help managing access to self-hosted runners. It requires a paid GitHub account and organization level runner registration. The group must exist or the runner will not start. Users will still be able to trigger this runner with the correct labels. But the runner will only be able to run jobs from repos allowed to use the group. --- ##### `imageBuilder`^Optional ```typescript public readonly imageBuilder: IRunnerImageBuilder; ``` - *Type:* IRunnerImageBuilder - *Default:* EcsRunnerProvider.imageBuilder() Runner image builder used to build Docker images containing GitHub Runner and all requirements. The image builder determines the OS and architecture of the runner. --- ##### `instanceType`^Optional ```typescript public readonly instanceType: InstanceType; ``` - *Type:* aws-cdk-lib.aws_ec2.InstanceType - *Default:* m6i.large or m6g.large Instance type of ECS cluster instances. Only used when creating a new cluster. --- ##### `labels`^Optional ```typescript public readonly labels: string[]; ``` - *Type:* string[] - *Default:* ['ecs'] GitHub Actions labels used for this provider. These labels are used to identify which provider should spawn a new on-demand runner. Every job sends a webhook with the labels it's looking for based on runs-on. We match the labels from the webhook with the labels specified here. If all the labels specified here are present in the job's labels, this provider will be chosen and spawn a new runner. --- ##### `maxInstances`^Optional ```typescript public readonly maxInstances: number; ``` - *Type:* number - *Default:* 5 The maximum number of instances to run in the cluster. Only used when creating a new cluster. --- ##### `memoryLimitMiB`^Optional ```typescript public readonly memoryLimitMiB: number; ``` - *Type:* number - *Default:* 3500, unless `memoryReservationMiB` is used and then it's undefined The amount (in MiB) of memory used by the task. --- ##### `memoryReservationMiB`^Optional ```typescript public readonly memoryReservationMiB: number; ``` - *Type:* number - *Default:* undefined The soft limit (in MiB) of memory to reserve for the container. --- ##### `minInstances`^Optional ```typescript public readonly minInstances: number; ``` - *Type:* number - *Default:* 0 The minimum number of instances to run in the cluster. Only used when creating a new cluster. --- ##### `placementConstraints`^Optional ```typescript public readonly placementConstraints: PlacementConstraint[]; ``` - *Type:* aws-cdk-lib.aws_ecs.PlacementConstraint[] - *Default:* undefined (no placement constraints) ECS placement constraints to influence task placement. Example: [ecs.PlacementConstraint.memberOf('ecs-placement')] --- ##### `placementStrategies`^Optional ```typescript public readonly placementStrategies: PlacementStrategy[]; ``` - *Type:* aws-cdk-lib.aws_ecs.PlacementStrategy[] - *Default:* undefined (no placement strategies) ECS placement strategies to influence task placement. Example: [ecs.PlacementStrategy.packedByCpu()] --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] - *Default:* a new security group Security groups to assign to the task. --- ##### `spot`^Optional ```typescript public readonly spot: boolean; ``` - *Type:* boolean - *Default:* false (true if spotMaxPrice is specified) Use spot capacity. --- ##### `spotMaxPrice`^Optional ```typescript public readonly spotMaxPrice: string; ``` - *Type:* string Maximum price for spot instances. --- ##### `storageOptions`^Optional ```typescript public readonly storageOptions: StorageOptions; ``` - *Type:* StorageOptions Options for runner instance storage volume. --- ##### `storageSize`^Optional ```typescript public readonly storageSize: Size; ``` - *Type:* aws-cdk-lib.Size - *Default:* default size for AMI (usually 30GB for Linux and 50GB for Windows) Size of volume available for launched cluster instances. This modifies the boot volume size and doesn't add any additional volumes. Each instance can be used by multiple runners, so make sure there is enough space for all of them. --- ##### `subnetSelection`^Optional ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection - *Default:* ECS default Subnets to run the runners in. --- ##### `tags`^Optional ```typescript public readonly tags: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} - *Default:* no additional tags Additional tags to apply to launched runner tasks. These additional tags are set on top of `Name`, `GitHubRunners:Provider`, `GitHubRunners:Repo`, and `GitHubRunners:Labels`. You may not override tags with the `GitHubRunners:` prefix. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc - *Default:* default account VPC VPC to launch the runners in. --- ### FargateRunnerProviderProps Properties for FargateRunnerProvider. #### Initializer ```typescript import { FargateRunnerProviderProps } from '@cloudsnorkel/cdk-github-runners' const fargateRunnerProviderProps: FargateRunnerProviderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | defaultLabels | boolean | Add default labels based on OS and architecture of the runner. | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | | assignPublicIp | boolean | Assign public IP to the runner task. | | cluster | aws-cdk-lib.aws_ecs.Cluster | Existing Fargate cluster to use. | | cpu | number | The number of cpu units used by the task. | | ephemeralStorageGiB | number | The amount (in GiB) of ephemeral storage to be allocated to the task. | | group | string | GitHub Actions runner group name. | | imageBuilder | IRunnerImageBuilder | Runner image builder used to build Docker images containing GitHub Runner and all requirements. | | labels | string[] | GitHub Actions labels used for this provider. | | memoryLimitMiB | number | The amount (in MiB) of memory used by the task. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups to assign to the task. | | spot | boolean | Use Fargate spot capacity provider to save money. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Subnets to run the runners in. | | tags | {[ key: string ]: string} | Additional tags to apply to launched runner tasks. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC to launch the runners in. | --- ##### `defaultLabels`^Optional ```typescript public readonly defaultLabels: boolean; ``` - *Type:* boolean - *Default:* true Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`. --- ##### `logRetention`^Optional ```typescript public readonly logRetention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* logs.RetentionDays.ONE_MONTH The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to `INFINITE`. --- ##### `assignPublicIp`^Optional ```typescript public readonly assignPublicIp: boolean; ``` - *Type:* boolean - *Default:* true Assign public IP to the runner task. Make sure the task will have access to GitHub. A public IP might be required unless you have NAT gateway. --- ##### `cluster`^Optional ```typescript public readonly cluster: Cluster; ``` - *Type:* aws-cdk-lib.aws_ecs.Cluster - *Default:* a new cluster Existing Fargate cluster to use. --- ##### `cpu`^Optional ```typescript public readonly cpu: number; ``` - *Type:* number - *Default:* 1024 The number of cpu units used by the task. For tasks using the Fargate launch type, this field is required and you must use one of the following values, which determines your range of valid values for the memory parameter: 256 (.25 vCPU) - Available memory values: 512 (0.5 GB), 1024 (1 GB), 2048 (2 GB) 512 (.5 vCPU) - Available memory values: 1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB) 1024 (1 vCPU) - Available memory values: 2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB) 2048 (2 vCPU) - Available memory values: Between 4096 (4 GB) and 16384 (16 GB) in increments of 1024 (1 GB) 4096 (4 vCPU) - Available memory values: Between 8192 (8 GB) and 30720 (30 GB) in increments of 1024 (1 GB) --- ##### `ephemeralStorageGiB`^Optional ```typescript public readonly ephemeralStorageGiB: number; ``` - *Type:* number - *Default:* 20 The amount (in GiB) of ephemeral storage to be allocated to the task. The maximum supported value is 200 GiB. NOTE: This parameter is only supported for tasks hosted on AWS Fargate using platform version 1.4.0 or later. --- ##### `group`^Optional ```typescript public readonly group: string; ``` - *Type:* string - *Default:* undefined GitHub Actions runner group name. If specified, the runner will be registered with this group name. Setting a runner group can help managing access to self-hosted runners. It requires a paid GitHub account and organization level runner registration. The group must exist or the runner will not start. Users will still be able to trigger this runner with the correct labels. But the runner will only be able to run jobs from repos allowed to use the group. --- ##### `imageBuilder`^Optional ```typescript public readonly imageBuilder: IRunnerImageBuilder; ``` - *Type:* IRunnerImageBuilder - *Default:* FargateRunnerProvider.imageBuilder() Runner image builder used to build Docker images containing GitHub Runner and all requirements. The image builder determines the OS and architecture of the runner. --- ##### `labels`^Optional ```typescript public readonly labels: string[]; ``` - *Type:* string[] - *Default:* ['fargate'] GitHub Actions labels used for this provider. These labels are used to identify which provider should spawn a new on-demand runner. Every job sends a webhook with the labels it's looking for based on runs-on. We match the labels from the webhook with the labels specified here. If all the labels specified here are present in the job's labels, this provider will be chosen and spawn a new runner. --- ##### `memoryLimitMiB`^Optional ```typescript public readonly memoryLimitMiB: number; ``` - *Type:* number - *Default:* 2048 The amount (in MiB) of memory used by the task. For tasks using the Fargate launch type, this field is required and you must use one of the following values, which determines your range of valid values for the cpu parameter: 512 (0.5 GB), 1024 (1 GB), 2048 (2 GB) - Available cpu values: 256 (.25 vCPU) 1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB) - Available cpu values: 512 (.5 vCPU) 2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB) - Available cpu values: 1024 (1 vCPU) Between 4096 (4 GB) and 16384 (16 GB) in increments of 1024 (1 GB) - Available cpu values: 2048 (2 vCPU) Between 8192 (8 GB) and 30720 (30 GB) in increments of 1024 (1 GB) - Available cpu values: 4096 (4 vCPU) --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] - *Default:* a new security group Security groups to assign to the task. --- ##### `spot`^Optional ```typescript public readonly spot: boolean; ``` - *Type:* boolean - *Default:* false Use Fargate spot capacity provider to save money. * Runners may fail to start due to missing capacity. * Runners might be stopped prematurely with spot pricing. --- ##### `subnetSelection`^Optional ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection - *Default:* Fargate default Subnets to run the runners in. --- ##### `tags`^Optional ```typescript public readonly tags: {[ key: string ]: string}; ``` - *Type:* {[ key: string ]: string} - *Default:* no additional tags Additional tags to apply to launched runner tasks. These additional tags are set on top of `Name`, `GitHubRunners:Provider`, `GitHubRunners:Repo`, and `GitHubRunners:Labels`. You may not override tags with the `GitHubRunners:` prefix. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc - *Default:* default account VPC VPC to launch the runners in. --- ### FastLaunchOptions Options for fast launch. #### Initializer ```typescript import { FastLaunchOptions } from '@cloudsnorkel/cdk-github-runners' const fastLaunchOptions: FastLaunchOptions = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | enabled | boolean | Enable fast launch for AMIs generated by this builder. | | maxParallelLaunches | number | The maximum number of parallel instances that are launched for creating resources. | | targetResourceCount | number | The number of pre-provisioned snapshots to keep on hand for a fast-launch enabled Windows AMI. | --- ##### `enabled`^Optional ```typescript public readonly enabled: boolean; ``` - *Type:* boolean - *Default:* false Enable fast launch for AMIs generated by this builder. It creates a snapshot of the root volume and uses it to launch new instances faster. This is only supported for Windows AMIs. --- ##### `maxParallelLaunches`^Optional ```typescript public readonly maxParallelLaunches: number; ``` - *Type:* number - *Default:* 6 The maximum number of parallel instances that are launched for creating resources. Must be at least 6. --- ##### `targetResourceCount`^Optional ```typescript public readonly targetResourceCount: number; ``` - *Type:* number - *Default:* 1 The number of pre-provisioned snapshots to keep on hand for a fast-launch enabled Windows AMI. --- ### GitHubRunnersProps Properties for GitHubRunners. #### Initializer ```typescript import { GitHubRunnersProps } from '@cloudsnorkel/cdk-github-runners' const gitHubRunnersProps: GitHubRunnersProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | allowPublicSubnet | boolean | Allow management functions to run in public subnets. Lambda Functions in a public subnet can NOT access the internet. | | extraCertificates | string | 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. | | idleTimeout | aws-cdk-lib.Duration | Time to wait before stopping a runner that remains idle. | | logOptions | LogOptions | Logging options for the state machine that manages the runners. | | providers | IRunnerProvider \| ICompositeProvider[] | List of runner providers to use. | | providerSelector | aws-cdk-lib.aws_lambda.IFunction | Optional Lambda function to customize provider selection logic and label assignment. | | requireSelfHostedLabel | boolean | Whether to require the `self-hosted` label. | | retryOptions | ProviderRetryOptions | Options to retry operation in case of failure like missing capacity, or API quota issues. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups attached to all management functions. | | setupAccess | LambdaAccess | Access configuration for the setup function. | | statusAccess | LambdaAccess | Access configuration for the status function. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC. | | vpcSubnets | aws-cdk-lib.aws_ec2.SubnetSelection | VPC subnets used for all management functions. | | webhookAccess | LambdaAccess | Access configuration for the webhook function. | --- ##### `allowPublicSubnet`^Optional ```typescript public readonly allowPublicSubnet: boolean; ``` - *Type:* boolean - *Default:* false Allow management functions to run in public subnets. 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. --- ##### `extraCertificates`^Optional ```typescript public readonly extraCertificates: string; ``` - *Type:* string 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. 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(selfSignedCertificates, 'private-ca')); const provider = new CodeBuildRunnerProvider(this, 'CodeBuild', { imageBuilder: imageBuilder, }); new GitHubRunners( this, 'runners', { providers: [provider], extraCertificates: selfSignedCertificates, } ); ``` --- ##### `idleTimeout`^Optional ```typescript public readonly idleTimeout: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* 5 minutes Time to wait before stopping a runner that remains idle. If the user cancelled the job, or if another runner stole it, this stops the runner to avoid wasting resources. --- ##### `logOptions`^Optional ```typescript public readonly logOptions: LogOptions; ``` - *Type:* LogOptions - *Default:* no logs Logging options for the state machine that manages the runners. --- ##### `providers`^Optional ```typescript public readonly providers: (IRunnerProvider | ICompositeProvider)[]; ``` - *Type:* IRunnerProvider | ICompositeProvider[] - *Default:* CodeBuild, Lambda and Fargate runners with all the defaults (no VPC or default account VPC) List of runner providers to use. At least one provider is required. Provider will be selected when its label matches the labels requested by the workflow job. --- ##### `providerSelector`^Optional ```typescript public readonly providerSelector: IFunction; ``` - *Type:* aws-cdk-lib.aws_lambda.IFunction Optional Lambda function to customize provider selection logic and label assignment. * The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } * The function returns a selected provider and its labels as {@link ProviderSelectorResult } * You can decline to provision a runner by returning undefined as the provider in the selector result * You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) * Labels don't have to match the labels originally configured for the provider, but see warnings below * This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard. > [https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md) --- ##### `requireSelfHostedLabel`^Optional ```typescript public readonly requireSelfHostedLabel: boolean; ``` - *Type:* boolean - *Default:* true Whether to require the `self-hosted` label. If `true`, the runner will only start if the workflow job explicitly requests the `self-hosted` label. Be careful when setting this to `false`. Avoid setting up providers with generic label requirements like `linux` as they may match workflows that are not meant to run on self-hosted runners. --- ##### `retryOptions`^Optional ```typescript public readonly retryOptions: ProviderRetryOptions; ``` - *Type:* ProviderRetryOptions - *Default:* retry 210 times over a bit more than 24 hours Options to retry operation in case of failure like missing capacity, or API quota issues. GitHub jobs time out after not being able to get a runner for 24 hours. You should not retry for more than 24 hours. Retries use full jitter, so total time spent waiting is about half the sum of min(interval * backoffRate ^ attempt, maxDelay) over all attempts. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] Security groups attached to all management functions. 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. --- ##### `setupAccess`^Optional ```typescript public readonly setupAccess: LambdaAccess; ``` - *Type:* LambdaAccess - *Default:* LambdaAccess.lambdaUrl() Access configuration for the setup function. Once you finish the setup process, you can set this to `LambdaAccess.noAccess()` to remove access to the setup function. You can also use `LambdaAccess.apiGateway({ allowedIps: ['my-ip/0']})` to limit access to your IP only. --- ##### `statusAccess`^Optional ```typescript public readonly statusAccess: LambdaAccess; ``` - *Type:* LambdaAccess - *Default:* LambdaAccess.noAccess() Access configuration for the status function. This function returns a lot of sensitive information about the runner, so you should only allow access to it from trusted IPs, if at all. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.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 * SQS * Step Functions * CloudFormation (status function only) * EC2 * ECR (status function only) --- ##### `vpcSubnets`^Optional ```typescript public readonly vpcSubnets: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection 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`^Optional ```typescript public readonly webhookAccess: LambdaAccess; ``` - *Type:* LambdaAccess - *Default:* LambdaAccess.lambdaUrl() Access configuration for the webhook function. This function is called by GitHub when a new workflow job is scheduled. For an extra layer of security, you can set this to `LambdaAccess.apiGateway({ allowedIps: LambdaAccess.githubWebhookIps() })`. You can also set this to `LambdaAccess.apiGateway({allowedVpc: vpc, allowedIps: ['GHES.IP.ADDRESS/32']})` if your GitHub Enterprise Server is hosted in a VPC. This will create an API Gateway endpoint that's only accessible from within the VPC. *WARNING*: changing access type may change the URL. When the URL changes, you must update GitHub as well. --- ### LambdaRunnerProviderProps #### Initializer ```typescript import { LambdaRunnerProviderProps } from '@cloudsnorkel/cdk-github-runners' const lambdaRunnerProviderProps: LambdaRunnerProviderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | defaultLabels | boolean | Add default labels based on OS and architecture of the runner. | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | | ephemeralStorageSize | aws-cdk-lib.Size | The size of the function’s /tmp directory in MiB. | | group | string | GitHub Actions runner group name. | | imageBuilder | IRunnerImageBuilder | Runner image builder used to build Docker images containing GitHub Runner and all requirements. | | labels | string[] | GitHub Actions labels used for this provider. | | memorySize | number | The amount of memory, in MB, that is allocated to your Lambda function. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups to assign to this instance. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Where to place the network interfaces within the VPC. | | timeout | aws-cdk-lib.Duration | The function execution time (in seconds) after which Lambda terminates the function. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC to launch the runners in. | --- ##### `defaultLabels`^Optional ```typescript public readonly defaultLabels: boolean; ``` - *Type:* boolean - *Default:* true Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`. --- ##### `logRetention`^Optional ```typescript public readonly logRetention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* logs.RetentionDays.ONE_MONTH The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to `INFINITE`. --- ##### `ephemeralStorageSize`^Optional ```typescript public readonly ephemeralStorageSize: Size; ``` - *Type:* aws-cdk-lib.Size - *Default:* 10 GiB The size of the function’s /tmp directory in MiB. --- ##### `group`^Optional ```typescript public readonly group: string; ``` - *Type:* string - *Default:* undefined GitHub Actions runner group name. If specified, the runner will be registered with this group name. Setting a runner group can help managing access to self-hosted runners. It requires a paid GitHub account and organization level runner registration. The group must exist or the runner will not start. Users will still be able to trigger this runner with the correct labels. But the runner will only be able to run jobs from repos allowed to use the group. --- ##### `imageBuilder`^Optional ```typescript public readonly imageBuilder: IRunnerImageBuilder; ``` - *Type:* IRunnerImageBuilder - *Default:* LambdaRunnerProvider.imageBuilder() Runner image builder used to build Docker images containing GitHub Runner and all requirements. The image builder must contain the {@link RunnerImageComponent.lambdaEntrypoint} component. The image builder determines the OS and architecture of the runner. --- ##### `labels`^Optional ```typescript public readonly labels: string[]; ``` - *Type:* string[] - *Default:* ['lambda'] GitHub Actions labels used for this provider. These labels are used to identify which provider should spawn a new on-demand runner. Every job sends a webhook with the labels it's looking for based on runs-on. We match the labels from the webhook with the labels specified here. If all the labels specified here are present in the job's labels, this provider will be chosen and spawn a new runner. --- ##### `memorySize`^Optional ```typescript public readonly memorySize: number; ``` - *Type:* number - *Default:* 2048 The amount of memory, in MB, that is allocated to your Lambda function. Lambda uses this value to proportionally allocate the amount of CPU power. For more information, see Resource Model in the AWS Lambda Developer Guide. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] - *Default:* public lambda with no security group Security groups to assign to this instance. --- ##### `subnetSelection`^Optional ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection - *Default:* no subnet Where to place the network interfaces within the VPC. --- ##### `timeout`^Optional ```typescript public readonly timeout: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* Duration.minutes(15) The function execution time (in seconds) after which Lambda terminates the function. Because the execution time affects cost, set this value based on the function's expected execution time. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc - *Default:* no VPC VPC to launch the runners in. --- ### LogOptions Defines what execution history events are logged and where they are logged. #### Initializer ```typescript import { LogOptions } from '@cloudsnorkel/cdk-github-runners' const logOptions: LogOptions = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | includeExecutionData | boolean | Determines whether execution data is included in your log. | | level | aws-cdk-lib.aws_stepfunctions.LogLevel | Defines which category of execution history events are logged. | | logGroupName | string | The log group where the execution history events will be logged. | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | --- ##### `includeExecutionData`^Optional ```typescript public readonly includeExecutionData: boolean; ``` - *Type:* boolean - *Default:* true Determines whether execution data is included in your log. --- ##### `level`^Optional ```typescript public readonly level: LogLevel; ``` - *Type:* aws-cdk-lib.aws_stepfunctions.LogLevel - *Default:* ALL Defines which category of execution history events are logged. --- ##### `logGroupName`^Optional ```typescript public readonly logGroupName: string; ``` - *Type:* string The log group where the execution history events will be logged. --- ##### `logRetention`^Optional ```typescript public readonly logRetention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* logs.RetentionDays.ONE_MONTH The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to `INFINITE`. --- ### ProviderRetryOptions Retry options for providers. The default is to retry 210 times for a bit over 24 hours with increasing interval. Retries use full jitter, so every wait is a random time between zero and the calculated interval. This spreads out runners that all failed at the same time, so they don't hit the same missing capacity or API quota together again. It also means the average wait is half the calculated interval, and that's what the 24 hours are calculated from. #### Initializer ```typescript import { ProviderRetryOptions } from '@cloudsnorkel/cdk-github-runners' const providerRetryOptions: ProviderRetryOptions = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | backoffRate | number | Multiplication for how much longer the wait interval gets on every retry. | | interval | aws-cdk-lib.Duration | How much time to wait after first retryable failure. | | maxAttempts | number | How many times to retry. | | maxDelay | aws-cdk-lib.Duration | Maximum wait between retries. | | retry | boolean | Set to true to retry provider on supported failures. | --- ##### `backoffRate`^Optional ```typescript public readonly backoffRate: number; ``` - *Type:* number - *Default:* 2 Multiplication for how much longer the wait interval gets on every retry. --- ##### `interval`^Optional ```typescript public readonly interval: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* 1 minute How much time to wait after first retryable failure. This interval will be multiplied by {@link backoffRate} each retry, up to {@link maxDelay}. --- ##### `maxAttempts`^Optional ```typescript public readonly maxAttempts: number; ``` - *Type:* number - *Default:* 210 How many times to retry. --- ##### `maxDelay`^Optional ```typescript public readonly maxDelay: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* 15 minutes Maximum wait between retries. Without it, exponential backoff quickly grows to hours between attempts, so a job can end up waiting hours for a runner even though capacity came back minutes after it failed. Don't go too low either. A lower maximum needs more attempts to cover the same 24 hours, and every attempt adds to the execution history that Step Functions caps at 25,000 events. --- ##### `retry`^Optional ```typescript public readonly retry: boolean; ``` - *Type:* boolean - *Default:* true Set to true to retry provider on supported failures. Which failures generate a retry depends on the specific provider. --- ### ProviderSelectorInput Input to the provider selector Lambda function. #### Initializer ```typescript import { ProviderSelectorInput } from '@cloudsnorkel/cdk-github-runners' const providerSelectorInput: ProviderSelectorInput = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | payload | any | Full GitHub webhook payload (workflow_job event structure with action="queued"). | | providers | {[ key: string ]: string[]} | Map of available provider node paths to their configured labels. | | defaultLabels | string[] | Labels that would have been used by default (the selected provider's labels). | | defaultProvider | string | Provider node path that would have been selected by default label matching. | --- ##### `payload`^Required ```typescript public readonly payload: any; ``` - *Type:* any Full GitHub webhook payload (workflow_job event structure with action="queued"). * Original labels requested by the workflow job can be found at `payload.workflow_job.labels`. * Repository path (e.g. CloudSnorkel/cdk-github-runners) is at `payload.repository.full_name`. * Commit hash is at `payload.workflow_job.head_sha`. > [https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=queued#workflow_job](https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=queued#workflow_job) --- ##### `providers`^Required ```typescript public readonly providers: {[ key: string ]: string[]}; ``` - *Type:* {[ key: string ]: string[]} Map of available provider node paths to their configured labels. Example: { "MyStack/Small": ["linux", "small"], "MyStack/Large": ["linux", "large"] } --- ##### `defaultLabels`^Optional ```typescript public readonly defaultLabels: string[]; ``` - *Type:* string[] Labels that would have been used by default (the selected provider's labels). May be undefined if no provider matched by default. --- ##### `defaultProvider`^Optional ```typescript public readonly defaultProvider: string; ``` - *Type:* string Provider node path that would have been selected by default label matching. Use this to easily return the default selection: `{ provider: input.defaultProvider, labels: input.defaultLabels }` May be undefined if no provider matched by default. --- ### ProviderSelectorResult Result from the provider selector Lambda function. #### Initializer ```typescript import { ProviderSelectorResult } from '@cloudsnorkel/cdk-github-runners' const providerSelectorResult: ProviderSelectorResult = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | labels | string[] | Labels to use when registering the runner. | | provider | string | Node path of the provider to use (e.g., "MyStack/MyProvider"). Must match one of the configured provider node paths from the input. If not provided, the job will be skipped (no runner created). | --- ##### `labels`^Optional ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels to use when registering the runner. Must be returned when a provider is selected. Can be used to add, remove, or modify labels. --- ##### `provider`^Optional ```typescript public readonly provider: string; ``` - *Type:* string Node path of the provider to use (e.g., "MyStack/MyProvider"). Must match one of the configured provider node paths from the input. If not provided, the job will be skipped (no runner created). --- ### RunnerAmi Description of a AMI built by {@link RunnerImageBuilder }. #### Initializer ```typescript import { RunnerAmi } from '@cloudsnorkel/cdk-github-runners' const runnerAmi: RunnerAmi = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | architecture | Architecture | Architecture of the image. | | launchTemplate | aws-cdk-lib.aws_ec2.ILaunchTemplate | Launch template pointing to the latest AMI. | | os | Os | OS type of the image. | | cacheKey | string | Set this to a value that changes whenever the AMI changes (the AMI id or any version string works). | | logGroup | aws-cdk-lib.aws_logs.LogGroup | Log group where image builds are logged. | --- ##### `architecture`^Required ```typescript public readonly architecture: Architecture; ``` - *Type:* Architecture Architecture of the image. --- ##### `launchTemplate`^Required ```typescript public readonly launchTemplate: ILaunchTemplate; ``` - *Type:* aws-cdk-lib.aws_ec2.ILaunchTemplate Launch template pointing to the latest AMI. --- ##### `os`^Required ```typescript public readonly os: Os; ``` - *Type:* Os OS type of the image. --- ##### `cacheKey`^Optional ```typescript public readonly cacheKey: string; ``` - *Type:* string Set this to a value that changes whenever the AMI changes (the AMI id or any version string works). It's used to know when the AMI's root device name needs to be looked up again. If left empty, the root device name is looked up once and reused. That's fine as long as the AMI's root device never changes. This value may be used for other things in the future that require knowing when the AMI changed. --- ##### `logGroup`^Optional ```typescript public readonly logGroup: LogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.LogGroup Log group where image builds are logged. --- ### RunnerImage Description of a Docker image built by {@link RunnerImageBuilder }. #### Initializer ```typescript import { RunnerImage } from '@cloudsnorkel/cdk-github-runners' const runnerImage: RunnerImage = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | architecture | Architecture | Architecture of the image. | | imageRepository | aws-cdk-lib.aws_ecr.IRepository | ECR repository containing the image. | | imageTag | string | Static image tag where the image will be pushed. | | os | Os | OS type of the image. | | logGroup | aws-cdk-lib.aws_logs.LogGroup | Log group where image builds are logged. | --- ##### `architecture`^Required ```typescript public readonly architecture: Architecture; ``` - *Type:* Architecture Architecture of the image. --- ##### `imageRepository`^Required ```typescript public readonly imageRepository: IRepository; ``` - *Type:* aws-cdk-lib.aws_ecr.IRepository ECR repository containing the image. --- ##### `imageTag`^Required ```typescript public readonly imageTag: string; ``` - *Type:* string Static image tag where the image will be pushed. --- ##### `os`^Required ```typescript public readonly os: Os; ``` - *Type:* Os OS type of the image. --- ##### `logGroup`^Optional ```typescript public readonly logGroup: LogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.LogGroup Log group where image builds are logged. --- ### RunnerImageAsset Asset to copy into a built image. #### Initializer ```typescript import { RunnerImageAsset } from '@cloudsnorkel/cdk-github-runners' const runnerImageAsset: RunnerImageAsset = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | source | string | Path on local system to copy into the image. | | target | string | Target path in the built image. | --- ##### `source`^Required ```typescript public readonly source: string; ``` - *Type:* string Path on local system to copy into the image. Can be a file or a directory. --- ##### `target`^Required ```typescript public readonly target: string; ``` - *Type:* string Target path in the built image. --- ### RunnerImageBuilderProps #### Initializer ```typescript import { RunnerImageBuilderProps } from '@cloudsnorkel/cdk-github-runners' const runnerImageBuilderProps: RunnerImageBuilderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | architecture | Architecture | Image architecture. | | awsImageBuilderOptions | AwsImageBuilderRunnerImageBuilderProps | Options specific to AWS Image Builder. | | baseAmi | BaseImage | Base AMI from which runner AMIs will be built. | | baseDockerImage | BaseContainerImage | Base image from which Docker runner images will be built. | | builderType | RunnerImageBuilderType | *No description.* | | codeBuildOptions | CodeBuildRunnerImageBuilderProps | Options specific to CodeBuild image builder. | | components | RunnerImageComponent[] | Components to install on the image. | | dockerSetupCommands | string[] | Additional commands to run on the build host before starting the Docker runner image build. | | logRemovalPolicy | aws-cdk-lib.RemovalPolicy | Removal policy for logs of image builds. | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | | os | Os | Image OS. | | rebuildInterval | aws-cdk-lib.Duration | Schedule the image to be rebuilt every given interval. | | runnerVersion | RunnerVersion | Version of GitHub Runners to install. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security Groups to assign to this instance. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Where to place the network interfaces within the VPC. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC to build the image in. | | waitOnDeploy | boolean | Wait for image to finish building during deployment. | --- ##### `architecture`^Optional ```typescript public readonly architecture: Architecture; ``` - *Type:* Architecture - *Default:* Architecture.X86_64 Image architecture. --- ##### `awsImageBuilderOptions`^Optional ```typescript public readonly awsImageBuilderOptions: AwsImageBuilderRunnerImageBuilderProps; ``` - *Type:* AwsImageBuilderRunnerImageBuilderProps Options specific to AWS Image Builder. Only used when builderType is RunnerImageBuilderType.AWS_IMAGE_BUILDER. --- ##### `baseAmi`^Optional ```typescript public readonly baseAmi: BaseImage; ``` - *Type:* BaseImage - *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 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`^Optional ```typescript public readonly baseDockerImage: BaseContainerImage; ``` - *Type:* BaseContainerImage - *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 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}. --- ##### `builderType`^Optional ```typescript public readonly builderType: RunnerImageBuilderType; ``` - *Type:* RunnerImageBuilderType - *Default:* CodeBuild for Linux Docker image, AWS Image Builder for Windows Docker image and any AMI --- ##### `codeBuildOptions`^Optional ```typescript public readonly codeBuildOptions: CodeBuildRunnerImageBuilderProps; ``` - *Type:* CodeBuildRunnerImageBuilderProps Options specific to CodeBuild image builder. Only used when builderType is RunnerImageBuilderType.CODE_BUILD. --- ##### `components`^Optional ```typescript public readonly components: RunnerImageComponent[]; ``` - *Type:* RunnerImageComponent[] - *Default:* none Components to install on the image. --- ##### `dockerSetupCommands`^Optional ```typescript public readonly dockerSetupCommands: string[]; ``` - *Type:* string[] - *Default:* [] Additional commands to run on the build host before starting the Docker runner image build. Use this to execute commands such as `docker login` or `aws ecr get-login-password` to pull private base images. --- ##### `logRemovalPolicy`^Optional ```typescript public readonly logRemovalPolicy: RemovalPolicy; ``` - *Type:* aws-cdk-lib.RemovalPolicy - *Default:* RemovalPolicy.DESTROY Removal policy for logs of image builds. If deployment fails on the custom resource, try setting this to `RemovalPolicy.RETAIN`. This way the CodeBuild logs can still be viewed, and you can see why the build failed. We try to not leave anything behind when removed. But sometimes a log staying behind is useful. --- ##### `logRetention`^Optional ```typescript public readonly logRetention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* logs.RetentionDays.ONE_MONTH The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to `INFINITE`. --- ##### `os`^Optional ```typescript public readonly os: Os; ``` - *Type:* Os - *Default:* OS.LINUX_UBUNTU Image OS. --- ##### `rebuildInterval`^Optional ```typescript public readonly rebuildInterval: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* Duration.days(7) Schedule the image to be rebuilt every given interval. Useful for keeping the image up-do-date with the latest GitHub runner version and latest OS updates. Set to zero to disable. --- ##### `runnerVersion`^Optional ```typescript public readonly runnerVersion: RunnerVersion; ``` - *Type:* RunnerVersion - *Default:* latest version available Version of GitHub Runners to install. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] Security Groups to assign to this instance. --- ##### `subnetSelection`^Optional ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection - *Default:* no subnet Where to place the network interfaces within the VPC. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc - *Default:* no VPC VPC to build the image in. --- ##### `waitOnDeploy`^Optional ```typescript public readonly waitOnDeploy: boolean; ``` - *Type:* boolean - *Default:* true Wait for image to finish building during deployment. It's usually best to leave this enabled to ensure everything is ready once deployment is done. However, it can be disabled to speed up deployment in case where you have a lot of image components that can take a long time to build. Disabling this option means a finished deployment is not ready to be used. You will have to wait for the image to finish building before the system can be used. Disabling this option may also mean any changes to settings or components can take up to a week (default rebuild interval) to take effect. --- ### RunnerImageComponentCustomProps #### Initializer ```typescript import { RunnerImageComponentCustomProps } from '@cloudsnorkel/cdk-github-runners' const runnerImageComponentCustomProps: RunnerImageComponentCustomProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | assets | RunnerImageAsset[] | Assets to copy into the built image. | | commands | string[] | Commands to run in the built image. | | dockerCommands | string[] | Docker commands to run in the built image. | | name | string | Component name used for (1) image build logging and (2) identifier for {@link IConfigurableRunnerImageBuilder.removeComponent }. | --- ##### `assets`^Optional ```typescript public readonly assets: RunnerImageAsset[]; ``` - *Type:* RunnerImageAsset[] Assets to copy into the built image. --- ##### `commands`^Optional ```typescript public readonly commands: string[]; ``` - *Type:* string[] Commands to run in the built image. --- ##### `dockerCommands`^Optional ```typescript public readonly dockerCommands: string[]; ``` - *Type:* string[] Docker commands to run in the built image. For example: `['ENV foo=bar', 'RUN echo $foo']` These commands are ignored when building AMIs. --- ##### `name`^Optional ```typescript public readonly name: string; ``` - *Type:* string Component name used for (1) image build logging and (2) identifier for {@link IConfigurableRunnerImageBuilder.removeComponent }. Name must only contain alphanumeric characters and dashes. --- ### RunnerProviderProps Common properties for all runner providers. #### Initializer ```typescript import { RunnerProviderProps } from '@cloudsnorkel/cdk-github-runners' const runnerProviderProps: RunnerProviderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | defaultLabels | boolean | Add default labels based on OS and architecture of the runner. | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | --- ##### `defaultLabels`^Optional ```typescript public readonly defaultLabels: boolean; ``` - *Type:* boolean - *Default:* true Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like `self-hosted`, `linux`, `x64`, and `arm64`. --- ##### `logRetention`^Optional ```typescript public readonly logRetention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* logs.RetentionDays.ONE_MONTH The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to `INFINITE`. --- ### ScheduledWarmRunnerProps Properties for scheduled warm runners. #### Initializer ```typescript import { ScheduledWarmRunnerProps } from '@cloudsnorkel/cdk-github-runners' const scheduledWarmRunnerProps: ScheduledWarmRunnerProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | count | number | Number of warm runners to maintain. | | duration | aws-cdk-lib.Duration | How long the warm runners should be maintained from the fill time (schedule). | | owner | string | GitHub owner where runners will be registered (org or user login). | | provider | IRunnerProvider \| ICompositeProvider | Provider to use. | | runners | GitHubRunners | The GitHubRunners construct that owns the shared warm runner infrastructure. | | schedule | aws-cdk-lib.aws_events.Schedule | When to start filling the pool (e.g. start of business hours). | | registrationLevel | string | Registration level — must match how your runners are set up in GitHub. | | repo | string | Repository name (without owner) where runners will be registered. | --- ##### `count`^Required ```typescript public readonly count: number; ``` - *Type:* number Number of warm runners to maintain. --- ##### `duration`^Required ```typescript public readonly duration: Duration; ``` - *Type:* aws-cdk-lib.Duration How long the warm runners should be maintained from the fill time (schedule). Defines the end of the window (schedule time + duration). --- ##### `owner`^Required ```typescript public readonly owner: string; ``` - *Type:* string GitHub owner where runners will be registered (org or user login). --- ##### `provider`^Required ```typescript public readonly provider: IRunnerProvider | ICompositeProvider; ``` - *Type:* IRunnerProvider | ICompositeProvider Provider to use. Warm runners bypass the provider selector — they always use this provider, regardless of job characteristics. Labels cannot be modified. --- ##### `runners`^Required ```typescript public readonly runners: GitHubRunners; ``` - *Type:* GitHubRunners The GitHubRunners construct that owns the shared warm runner infrastructure. --- ##### `schedule`^Required ```typescript public readonly schedule: Schedule; ``` - *Type:* aws-cdk-lib.aws_events.Schedule When to start filling the pool (e.g. start of business hours). --- ##### `registrationLevel`^Optional ```typescript public readonly registrationLevel: string; ``` - *Type:* string - *Default:* 'repo' Registration level — must match how your runners are set up in GitHub. Choose 'org' for org-wide runners, 'repo' for repo-level. See the setup wizard for choosing repo vs org. > [https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/SETUP_GITHUB.md) --- ##### `repo`^Optional ```typescript public readonly repo: string; ``` - *Type:* string Repository name (without owner) where runners will be registered. Required when `registrationLevel` is 'repo'. --- ### StorageOptions Storage options for the runner instance. #### Initializer ```typescript import { StorageOptions } from '@cloudsnorkel/cdk-github-runners' const storageOptions: StorageOptions = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | iops | number | The number of I/O operations per second (IOPS) to provision for the volume. | | throughput | number | The throughput that the volume supports, in MiB/s Takes a minimum of 125 and maximum of 1000. | | volumeType | aws-cdk-lib.aws_ec2.EbsDeviceVolumeType | The EBS volume type. | --- ##### `iops`^Optional ```typescript public readonly iops: number; ``` - *Type:* number - *Default:* none, required for `EbsDeviceVolumeType.IO1` The number of I/O operations per second (IOPS) to provision for the volume. Must only be set for `volumeType`: `EbsDeviceVolumeType.IO1` The maximum ratio of IOPS to volume size (in GiB) is 50:1, so for 5,000 provisioned IOPS, you need at least 100 GiB storage on the volume. > [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html) --- ##### `throughput`^Optional ```typescript public readonly throughput: number; ``` - *Type:* number - *Default:* 125 MiB/s. Only valid on gp3 volumes. The throughput that the volume supports, in MiB/s Takes a minimum of 125 and maximum of 1000. > [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-volume.html#cfn-ec2-volume-throughput](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-volume.html#cfn-ec2-volume-throughput) --- ##### `volumeType`^Optional ```typescript public readonly volumeType: EbsDeviceVolumeType; ``` - *Type:* aws-cdk-lib.aws_ec2.EbsDeviceVolumeType - *Default:* `EbsDeviceVolumeType.GP2` The EBS volume type. > [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html) --- ### WeightedRunnerProvider Configuration for weighted distribution of runners. #### Initializer ```typescript import { WeightedRunnerProvider } from '@cloudsnorkel/cdk-github-runners' const weightedRunnerProvider: WeightedRunnerProvider = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | provider | IRunnerProvider | The runner provider to use. | | weight | number | Weight for this provider. | --- ##### `provider`^Required ```typescript public readonly provider: IRunnerProvider; ``` - *Type:* IRunnerProvider The runner provider to use. --- ##### `weight`^Required ```typescript public readonly weight: number; ``` - *Type:* number Weight for this provider. Higher weights mean higher probability of selection. Must be a positive number. --- ## Classes ### Architecture CPU architecture enum for an image. #### Methods | **Name** | **Description** | | --- | --- | | instanceTypeMatch | Checks if a given EC2 instance type matches this architecture. | | is | Checks if the given architecture is the same as this one. | | isIn | Checks if this architecture is in a given list. | --- ##### `instanceTypeMatch` ```typescript public instanceTypeMatch(instanceType: InstanceType): boolean ``` Checks if a given EC2 instance type matches this architecture. ###### `instanceType`^Required - *Type:* aws-cdk-lib.aws_ec2.InstanceType instance type to check. --- ##### `is` ```typescript public is(arch: Architecture): boolean ``` Checks if the given architecture is the same as this one. ###### `arch`^Required - *Type:* Architecture architecture to compare. --- ##### `isIn` ```typescript public isIn(arches: Architecture[]): boolean ``` Checks if this architecture is in a given list. ###### `arches`^Required - *Type:* Architecture[] architectures to check. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | name | string | *No description.* | --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | ARM64 | Architecture | ARM64. | | X86_64 | Architecture | X86_64. | --- ##### `ARM64`^Required ```typescript public readonly ARM64: Architecture; ``` - *Type:* Architecture ARM64. --- ##### `X86_64`^Required ```typescript public readonly X86_64: Architecture; ``` - *Type:* Architecture X86_64. --- ### BaseContainerImage 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 ```typescript import { BaseContainerImage } from '@cloudsnorkel/cdk-github-runners' new BaseContainerImage(image: string, ecrRepository?: IRepository) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | image | string | *No description.* | | ecrRepository | aws-cdk-lib.aws_ecr.IRepository | *No description.* | --- ##### `image`^Required - *Type:* string --- ##### `ecrRepository`^Optional - *Type:* aws-cdk-lib.aws_ecr.IRepository --- #### Static Functions | **Name** | **Description** | | --- | --- | | fromDockerHub | The DockerHub image to use as the base image in a container recipe. | | fromEcr | The ECR container image to use as the base image in a container recipe. | | fromEcrPublic | The ECR public container image to use as the base image in a container recipe. | | fromString | The string value of the base image to use in a container recipe. | --- ##### `fromDockerHub` ```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`^Required - *Type:* string The DockerHub repository where the base image resides in. --- ###### `tag`^Required - *Type:* string The tag of the base image in the DockerHub repository. --- ##### `fromEcr` ```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`^Required - *Type:* aws-cdk-lib.aws_ecr.IRepository The ECR repository where the base image resides in. --- ###### `tag`^Required - *Type:* string The tag of the base image in the ECR repository. --- ##### `fromEcrPublic` ```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`^Required - *Type:* string The alias of the ECR public registry where the base image resides in. --- ###### `repositoryName`^Required - *Type:* string The name of the ECR public repository, where the base image resides in. --- ###### `tag`^Required - *Type:* string The tag of the base image in the ECR public repository. --- ##### `fromString` ```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`^Required - *Type:* string The base image as a direct string value. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | image | string | The rendered base image to use. | | ecrRepository | aws-cdk-lib.aws_ecr.IRepository | The ECR repository if this image was created from an ECR repository. | --- ##### `image`^Required ```typescript public readonly image: string; ``` - *Type:* string The rendered base image to use. --- ##### `ecrRepository`^Optional ```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 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 ```typescript import { BaseImage } from '@cloudsnorkel/cdk-github-runners' new BaseImage(image: string) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | image | string | *No description.* | --- ##### `image`^Required - *Type:* string --- #### Static Functions | **Name** | **Description** | | --- | --- | | fromAmiId | The AMI ID to use as a base image in an image recipe. | | fromGpuBase | A base AMI with NVIDIA drivers pre-installed for GPU workloads. | | fromImageBuilder | An AWS-provided EC2 Image Builder image to use as a base image in an image recipe. | | fromMarketplaceProductId | The marketplace product ID for an AMI product to use as the base image in an image recipe. | | fromSsmParameter | The SSM parameter to use as the base image in an image recipe. | | fromSsmParameterName | The parameter name for the SSM parameter to use as the base image in an image recipe. | | fromString | The direct string value of the base image to use in an image recipe. | --- ##### `fromAmiId` ```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`^Required - *Type:* string The AMI ID to use as the base image. --- ##### `fromGpuBase` ```typescript import { BaseImage } from '@cloudsnorkel/cdk-github-runners' BaseImage.fromGpuBase(os: Os, architecture: Architecture) ``` A base AMI with NVIDIA drivers pre-installed for GPU workloads. Uses AWS Deep Learning AMIs for Linux (Ubuntu, Amazon Linux 2, Amazon Linux 2023). For Windows, subscribe to NVIDIA RTX Virtual Workstation in AWS Marketplace, then use {@link fromMarketplaceProductId} with the product ID. ###### `os`^Required - *Type:* Os Target operating system. --- ###### `architecture`^Required - *Type:* Architecture Target architecture. --- ##### `fromImageBuilder` ```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`^Required - *Type:* constructs.Construct The construct scope (used to determine the stack and region). --- ###### `resourceName`^Required - *Type:* string The Image Builder resource name pattern (e.g., `ubuntu-server-22-lts-x86` or `ubuntu-server-22-lts-${arch}`). --- ###### `version`^Optional - *Type:* string The version pattern (defaults to `x.x.x` to use the latest version). --- ##### `fromMarketplaceProductId` ```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`^Required - *Type:* string The Marketplace AMI product ID to use as the base image. --- ##### `fromSsmParameter` ```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`^Required - *Type:* aws-cdk-lib.aws_ssm.IParameter The SSM parameter to use as the base image. --- ##### `fromSsmParameterName` ```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`^Required - *Type:* string The name of the SSM parameter to use as the base image. --- ##### `fromString` ```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`^Required - *Type:* string The base image as a direct string value. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | image | string | The rendered base image to use. | --- ##### `image`^Required ```typescript public readonly image: string; ``` - *Type:* string The rendered base image to use. --- ### CompositeProvider A composite runner provider that implements fallback and distribution strategies. #### Initializers ```typescript import { CompositeProvider } from '@cloudsnorkel/cdk-github-runners' new CompositeProvider() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Static Functions | **Name** | **Description** | | --- | --- | | distribute | Creates a weighted distribution runner provider that randomly selects a provider based on weights. | | fallback | Creates a fallback runner provider that tries each provider in order until one succeeds. | --- ##### `distribute` ```typescript import { CompositeProvider } from '@cloudsnorkel/cdk-github-runners' CompositeProvider.distribute(scope: Construct, id: string, weightedProviders: WeightedRunnerProvider[]) ``` Creates a weighted distribution runner provider that randomly selects a provider based on weights. For example, given providers A (weight 10), B (weight 20), C (weight 30): - Total weight = 60 - Probability of selecting A = 10/60 = 16.67% - Probability of selecting B = 20/60 = 33.33% - Probability of selecting C = 30/60 = 50% You can use this to distribute load across multiple instance types or availability zones. ###### `scope`^Required - *Type:* constructs.Construct The scope in which to define this construct. --- ###### `id`^Required - *Type:* string The scoped construct ID. --- ###### `weightedProviders`^Required - *Type:* WeightedRunnerProvider[] List of weighted runner providers. --- ##### `fallback` ```typescript import { CompositeProvider } from '@cloudsnorkel/cdk-github-runners' CompositeProvider.fallback(scope: Construct, id: string, providers: IRunnerProvider[]) ``` Creates a fallback runner provider that tries each provider in order until one succeeds. For example, given providers A, B, C: - Try A first - If A fails, try B - If B fails, try C You can use this to try spot instance first, and switch to on-demand instances if spot is unavailable. Or you can use this to try different instance types in order of preference. ###### `scope`^Required - *Type:* constructs.Construct The scope in which to define this construct. --- ###### `id`^Required - *Type:* string The scoped construct ID. --- ###### `providers`^Required - *Type:* IRunnerProvider[] List of runner providers to try in order. --- ### LambdaAccess Access configuration options for Lambda functions like setup and webhook function. Use this to limit access to these functions. If you need a custom access point, you can implement this abstract class yourself. Note that the Lambda functions expect API Gateway v1 or v2 input. They also expect every URL under the constructed URL to point to the function. #### Initializers ```typescript import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners' new LambdaAccess() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Methods | **Name** | **Description** | | --- | --- | | bind | Creates all required resources and returns access URL or empty string if disabled. | --- ##### `bind` ```typescript public bind(scope: Construct, id: string, lambdaFunction: Function): string ``` Creates all required resources and returns access URL or empty string if disabled. ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `lambdaFunction`^Required - *Type:* aws-cdk-lib.aws_lambda.Function --- #### Static Functions | **Name** | **Description** | | --- | --- | | apiGateway | Provide access using API Gateway. | | githubWebhookIps | Downloads the list of IP addresses used by GitHub.com for webhooks. | | lambdaUrl | Provide access using Lambda URL. | | noAccess | Disables access to the configured Lambda function. | --- ##### `apiGateway` ```typescript import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners' LambdaAccess.apiGateway(props?: ApiGatewayAccessProps) ``` Provide access using API Gateway. This is the most secure option, but requires additional configuration. It allows you to limit access to specific IP addresses and even to a specific VPC. To limit access to GitHub.com use: ``` LambdaAccess.apiGateway({ allowedIps: LambdaAccess.githubWebhookIps(), }); ``` Alternatively, get and manually update the list manually with: ``` curl https://api.github.com/meta | jq .hooks ``` ###### `props`^Optional - *Type:* ApiGatewayAccessProps --- ##### `githubWebhookIps` ```typescript import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners' LambdaAccess.githubWebhookIps() ``` Downloads the list of IP addresses used by GitHub.com for webhooks. Note that downloading dynamic data during deployment is not recommended in CDK. This is a workaround for the lack of a better solution. ##### `lambdaUrl` ```typescript import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners' LambdaAccess.lambdaUrl() ``` Provide access using Lambda URL. This is the default and simplest option. It puts no limits on the requester, but the Lambda functions themselves authenticate every request. ##### `noAccess` ```typescript import { LambdaAccess } from '@cloudsnorkel/cdk-github-runners' LambdaAccess.noAccess() ``` Disables access to the configured Lambda function. This is useful for the setup function after setup is done. ### Os OS enum for an image. #### Methods | **Name** | **Description** | | --- | --- | | is | Checks if the given OS is the same as this one. | | isIn | Checks if this OS is in a given list. | --- ##### `is` ```typescript public is(os: Os): boolean ``` Checks if the given OS is the same as this one. ###### `os`^Required - *Type:* Os OS to compare. --- ##### `isIn` ```typescript public isIn(oses: Os[]): boolean ``` Checks if this OS is in a given list. ###### `oses`^Required - *Type:* Os[] list of OS to check. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | name | string | *No description.* | --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | LINUX_AMAZON_2 | Os | Amazon Linux 2. | | LINUX_AMAZON_2023 | Os | Amazon Linux 2023. | | LINUX_UBUNTU | Os | Ubuntu Linux. | | LINUX_UBUNTU_2204 | Os | Ubuntu Linux 22.04. | | LINUX_UBUNTU_2404 | Os | Ubuntu Linux 24.04. | | WINDOWS | Os | Windows. | --- ##### `LINUX_AMAZON_2`^Required ```typescript public readonly LINUX_AMAZON_2: Os; ``` - *Type:* Os Amazon Linux 2. --- ##### `LINUX_AMAZON_2023`^Required ```typescript public readonly LINUX_AMAZON_2023: Os; ``` - *Type:* Os Amazon Linux 2023. --- ##### `LINUX_UBUNTU`^Required ```typescript public readonly LINUX_UBUNTU: Os; ``` - *Type:* Os Ubuntu Linux. --- ##### `LINUX_UBUNTU_2204`^Required ```typescript public readonly LINUX_UBUNTU_2204: Os; ``` - *Type:* Os Ubuntu Linux 22.04. --- ##### `LINUX_UBUNTU_2404`^Required ```typescript public readonly LINUX_UBUNTU_2404: Os; ``` - *Type:* Os Ubuntu Linux 24.04. --- ##### `WINDOWS`^Required ```typescript public readonly WINDOWS: Os; ``` - *Type:* Os Windows. --- ### RunnerImageComponent Components are used to build runner images. They can run commands in the image, copy files into the image, and run some Docker commands. #### Initializers ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' new RunnerImageComponent() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Methods | **Name** | **Description** | | --- | --- | | getAssets | Returns assets to copy into the built image. | | getCommands | Returns commands to run to in built image. | | getDockerCommands | Returns Docker commands to run to in built image. | | shouldReboot | Returns true if the image builder should be rebooted after this component is installed. | --- ##### `getAssets` ```typescript public getAssets(_os: Os, _architecture: Architecture): RunnerImageAsset[] ``` Returns assets to copy into the built image. Can be used to copy files into the image. ###### `_os`^Required - *Type:* Os --- ###### `_architecture`^Required - *Type:* Architecture --- ##### `getCommands` ```typescript public getCommands(_os: Os, _architecture: Architecture): string[] ``` Returns commands to run to in built image. Can be used to install packages, setup build prerequisites, etc. ###### `_os`^Required - *Type:* Os --- ###### `_architecture`^Required - *Type:* Architecture --- ##### `getDockerCommands` ```typescript public getDockerCommands(_os: Os, _architecture: Architecture): string[] ``` Returns Docker commands to run to in built image. Can be used to add commands like `VOLUME`, `ENTRYPOINT`, `CMD`, etc. Docker commands are added after assets and normal commands. ###### `_os`^Required - *Type:* Os --- ###### `_architecture`^Required - *Type:* Architecture --- ##### `shouldReboot` ```typescript public shouldReboot(_os: Os, _architecture: Architecture): boolean ``` Returns true if the image builder should be rebooted after this component is installed. ###### `_os`^Required - *Type:* Os --- ###### `_architecture`^Required - *Type:* Architecture --- #### Static Functions | **Name** | **Description** | | --- | --- | | awsCli | A component to install the AWS CLI. | | cloudWatchAgent | A component to install CloudWatch Agent for the runner so we can send logs. | | custom | Define a custom component that can run commands in the image, copy files into the image, and run some Docker commands. | | docker | A component to install Docker. | | environmentVariables | A component to add environment variables for jobs the runner executes. | | extraCertificates | A component to add a trusted certificate authority. | | git | A component to install Git. | | githubCli | A component to install the GitHub CLI. | | githubRunner | A component to install the GitHub Actions Runner. | | jobCompletedHook | A component that runs a script after every job the runner executes. | | jobStartedHook | A component that runs a script before every job the runner executes. | | lambdaEntrypoint | A component to set up the required Lambda entrypoint for Lambda runners. | | requiredPackages | A component to install the required packages for the runner. | | runnerUser | A component to prepare the required runner user. | --- ##### `awsCli` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.awsCli(version?: string) ``` A component to install the AWS CLI. ###### `version`^Optional - *Type:* string Software version to install (e.g. '2.15.0'). Default: latest. --- ##### `cloudWatchAgent` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.cloudWatchAgent() ``` A component to install CloudWatch Agent for the runner so we can send logs. ##### `custom` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.custom(props: RunnerImageComponentCustomProps) ``` Define a custom component that can run commands in the image, copy files into the image, and run some Docker commands. The order of operations is (1) assets (2) commands (3) docker commands. Use this to customize the image for the runner. **WARNING:** Docker commands are not guaranteed to be included before the next component ###### `props`^Required - *Type:* RunnerImageComponentCustomProps --- ##### `docker` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.docker(version?: string) ``` A component to install Docker. On Windows this sets up dockerd for Windows containers without Docker Desktop. If you need Linux containers on Windows, you'll need to install Docker Desktop which doesn't seem to play well with servers (PRs welcome). ###### `version`^Optional - *Type:* string Software version to install (e.g. '29.1.5'). Default: latest. Only used on Windows; on Linux (Ubuntu, Amazon Linux 2 and Amazon Linux 2023) the package version format is not reliably predictable so latest is always used. --- ##### `environmentVariables` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.environmentVariables(vars: {[ key: string ]: string}) ``` A component to add environment variables for jobs the runner executes. These variables only affect the jobs ran by the runner. They are not global. They do not affect other components. It is not recommended to use this component to pass secrets. Instead, use GitHub Secrets or AWS Secrets Manager. Must be used after the {@link githubRunner} component. ###### `vars`^Required - *Type:* {[ key: string ]: string} --- ##### `extraCertificates` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.extraCertificates(source: string, name: string) ``` A component to add a trusted certificate authority. This can be used to support GitHub Enterprise Server with self-signed certificate. ###### `source`^Required - *Type:* string path to certificate file in PEM format, or a directory containing certificate files (.pem or .crt). --- ###### `name`^Required - *Type:* string unique certificate name to be used on runner file system. --- ##### `git` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.git(version?: string) ``` A component to install Git. ###### `version`^Optional - *Type:* string Software version to install (e.g. '2.43.0.windows.1'). Default: latest. Only used on Windows; on Linux the package manager is used. --- ##### `githubCli` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.githubCli(version?: string) ``` A component to install the GitHub CLI. ###### `version`^Optional - *Type:* string Software version to install (e.g. '2.40.0'). Default: latest. Only used on Windows (x64/windows_amd64); on Linux the package manager is used. --- ##### `githubRunner` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.githubRunner(runnerVersion: RunnerVersion) ``` A component to install the GitHub Actions Runner. This is the actual executable that connects to GitHub to ask for jobs and then execute them. ###### `runnerVersion`^Required - *Type:* RunnerVersion The version of the runner to install. Usually you would set this to latest. --- ##### `jobCompletedHook` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.jobCompletedHook(sourcePath: string) ``` A component that runs a script after every job the runner executes. Point this at a local script file. It is copied into the image, made executable, and the runner is configured to run it after each job through the [`ACTIONS_RUNNER_HOOK_JOB_COMPLETED`](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/run-scripts) environment variable. GitHub passes job context to the script as environment variables such as `GITHUB_REPOSITORY` and `GITHUB_RUN_ID`. Must be used after the {@link githubRunner} component. ###### `sourcePath`^Required - *Type:* string path to a local script file to run after every job. --- ##### `jobStartedHook` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.jobStartedHook(sourcePath: string) ``` A component that runs a script before every job the runner executes. Point this at a local script file. It is copied into the image, made executable, and the runner is configured to run it before each job through the [`ACTIONS_RUNNER_HOOK_JOB_STARTED`](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/run-scripts) environment variable. GitHub passes job context to the script as environment variables such as `GITHUB_REPOSITORY` and `GITHUB_RUN_ID`. Must be used after the {@link githubRunner} component. ###### `sourcePath`^Required - *Type:* string path to a local script file to run before every job. --- ##### `lambdaEntrypoint` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.lambdaEntrypoint() ``` A component to set up the required Lambda entrypoint for Lambda runners. ##### `requiredPackages` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.requiredPackages() ``` A component to install the required packages for the runner. ##### `runnerUser` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.runnerUser() ``` A component to prepare the required runner user. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | name | string | Component name. | --- ##### `name`^Required ```typescript public readonly name: string; ``` - *Type:* string Component name. Used to identify component in image build logs, and for {@link IConfigurableRunnerImageBuilder.removeComponent } --- ### RunnerVersion Defines desired GitHub Actions runner version. #### Initializers ```typescript import { RunnerVersion } from '@cloudsnorkel/cdk-github-runners' new RunnerVersion(version: string) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | version | string | *No description.* | --- ##### `version`^Required - *Type:* string --- #### Methods | **Name** | **Description** | | --- | --- | | is | Check if two versions are the same. | --- ##### `is` ```typescript public is(other: RunnerVersion): boolean ``` Check if two versions are the same. ###### `other`^Required - *Type:* RunnerVersion version to compare. --- #### Static Functions | **Name** | **Description** | | --- | --- | | latest | Use the latest version available at the time the runner provider image is built. | | specific | Use a specific version. | --- ##### `latest` ```typescript import { RunnerVersion } from '@cloudsnorkel/cdk-github-runners' RunnerVersion.latest() ``` Use the latest version available at the time the runner provider image is built. ##### `specific` ```typescript import { RunnerVersion } from '@cloudsnorkel/cdk-github-runners' RunnerVersion.specific(version: string) ``` Use a specific version. > [https://github.com/actions/runner/releases](https://github.com/actions/runner/releases) ###### `version`^Required - *Type:* string GitHub Runner version. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | version | string | *No description.* | --- ##### `version`^Required ```typescript public readonly version: string; ``` - *Type:* string --- ### StaticRunnerImage Helper class with methods to use static images that are built outside the context of this project. #### Initializers ```typescript import { StaticRunnerImage } from '@cloudsnorkel/cdk-github-runners' new StaticRunnerImage() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Static Functions | **Name** | **Description** | | --- | --- | | fromDockerHub | Create a builder from an existing Docker Hub image. | | fromEcrRepository | Create a builder (that doesn't actually build anything) from an existing image in an existing repository. | --- ##### `fromDockerHub` ```typescript import { StaticRunnerImage } from '@cloudsnorkel/cdk-github-runners' StaticRunnerImage.fromDockerHub(scope: Construct, id: string, image: string, architecture?: Architecture, os?: Os) ``` Create a builder from an existing Docker Hub image. The image must already have GitHub Actions runner installed. You are responsible to update it and remove it when done. We create a CodeBuild image builder behind the scenes to copy the image over to ECR. This helps avoid Docker Hub rate limits and prevent failures. ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `image`^Required - *Type:* string Docker Hub image with optional tag. --- ###### `architecture`^Optional - *Type:* Architecture image architecture. --- ###### `os`^Optional - *Type:* Os image OS. --- ##### `fromEcrRepository` ```typescript import { StaticRunnerImage } from '@cloudsnorkel/cdk-github-runners' StaticRunnerImage.fromEcrRepository(repository: IRepository, tag?: string, architecture?: Architecture, os?: Os) ``` Create a builder (that doesn't actually build anything) from an existing image in an existing repository. The image must already have GitHub Actions runner installed. You are responsible to update it and remove it when done. ###### `repository`^Required - *Type:* aws-cdk-lib.aws_ecr.IRepository ECR repository. --- ###### `tag`^Optional - *Type:* string image tag. --- ###### `architecture`^Optional - *Type:* Architecture image architecture. --- ###### `os`^Optional - *Type:* Os image OS. --- ## Protocols ### ICompositeProvider - *Extends:* constructs.IConstruct - *Implemented By:* ICompositeProvider Interface for composite runner providers that combine multiple sub-providers. Unlike IRunnerProvider, composite providers do not have connections, grant capabilities, or log groups as they delegate to their sub-providers. Note that this interface cannot be implemented by external code. Use {@link CompositeProvider } factory methods. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | labels | string[] | GitHub Actions labels used for this provider. | | providers | IRunnerProvider[] | All sub-providers contained in this composite provider. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `labels`^Required ```typescript public readonly labels: string[]; ``` - *Type:* string[] GitHub Actions labels used for this provider. These labels are used to identify which provider should spawn a new on-demand runner. Every job sends a webhook with the labels it's looking for based on runs-on. We use match the labels from the webhook with the labels specified here. If all the labels specified here are present in the job's labels, this provider will be chosen and spawn a new runner. --- ##### `providers`^Required ```typescript public readonly providers: IRunnerProvider[]; ``` - *Type:* IRunnerProvider[] All sub-providers contained in this composite provider. This is used to extract providers for metric filters and other operations. --- ### IConfigurableRunnerImageBuilder - *Extends:* IRunnerImageBuilder, aws-cdk-lib.aws_ec2.IConnectable, aws-cdk-lib.aws_iam.IGrantable - *Implemented By:* RunnerImageBuilder, IConfigurableRunnerImageBuilder Interface for constructs that build an image that can be used in {@link IRunnerProvider }. The image can be configured by adding or removing components. The image builder can be configured by adding grants or allowing connections. An image can be a Docker image or AMI. #### Methods | **Name** | **Description** | | --- | --- | | addComponent | Add a component to the image builder. | | removeComponent | Remove a component from the image builder. | --- ##### `addComponent` ```typescript public addComponent(component: RunnerImageComponent): void ``` Add a component to the image builder. The component will be added to the end of the list of components. ###### `component`^Required - *Type:* RunnerImageComponent component to add. --- ##### `removeComponent` ```typescript public removeComponent(component: RunnerImageComponent): void ``` Remove a component from the image builder. Removal is done by component name. Multiple components with the same name will all be removed. ###### `component`^Required - *Type:* RunnerImageComponent component to remove. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | connections | aws-cdk-lib.aws_ec2.Connections | The network connections associated with this resource. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | The principal to grant permissions to. | --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### `grantPrincipal`^Required ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to. --- ### IRunnerAmiStatus - *Implemented By:* IRunnerAmiStatus AMI status returned from runner providers to be displayed as output of status function. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | launchTemplate | string | Id of launch template pointing to the latest AMI built by the AMI builder. | | amiBuilderLogGroup | string | Log group name for the AMI builder where history of builds can be analyzed. | --- ##### `launchTemplate`^Required ```typescript public readonly launchTemplate: string; ``` - *Type:* string Id of launch template pointing to the latest AMI built by the AMI builder. --- ##### `amiBuilderLogGroup`^Optional ```typescript public readonly amiBuilderLogGroup: string; ``` - *Type:* string Log group name for the AMI builder where history of builds can be analyzed. --- ### IRunnerImageBuilder - *Implemented By:* RunnerImageBuilder, IConfigurableRunnerImageBuilder, IRunnerImageBuilder Interface for constructs that build an image that can be used in {@link IRunnerProvider }. An image can be a Docker image or AMI. #### Methods | **Name** | **Description** | | --- | --- | | bindAmi | Build and return an AMI with GitHub Runner installed in it. | | bindDockerImage | Build and return a Docker image with GitHub Runner installed in it. | --- ##### `bindAmi` ```typescript public bindAmi(): RunnerAmi ``` Build and return an AMI with GitHub Runner installed in it. Anything that ends up with a launch template pointing to an AMI that runs GitHub self-hosted runners can be used. A simple implementation could even point to an existing AMI and nothing else. The AMI can be further updated over time manually or using a schedule as long as it is always written to the same launch template. ##### `bindDockerImage` ```typescript public bindDockerImage(): RunnerImage ``` Build and return a Docker image with GitHub Runner installed in it. Anything that ends up with an ECR repository containing a Docker image that runs GitHub self-hosted runners can be used. A simple implementation could even point to an existing image and nothing else. It's important that the specified image tag be available at the time the repository is available. Providers usually assume the image is ready and will fail if it's not. The image can be further updated over time manually or using a schedule as long as it is always written to the same tag. ### IRunnerImageStatus - *Implemented By:* IRunnerImageStatus Image status returned from runner providers to be displayed in status.json. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | imageRepository | string | Image repository where image builder pushes runner images. | | imageTag | string | Tag of image that should be used. | | imageBuilderLogGroup | string | Log group name for the image builder where history of image builds can be analyzed. | --- ##### `imageRepository`^Required ```typescript public readonly imageRepository: string; ``` - *Type:* string Image repository where image builder pushes runner images. --- ##### `imageTag`^Required ```typescript public readonly imageTag: string; ``` - *Type:* string Tag of image that should be used. --- ##### `imageBuilderLogGroup`^Optional ```typescript public readonly imageBuilderLogGroup: string; ``` - *Type:* string Log group name for the image builder where history of image builds can be analyzed. --- ### IRunnerProvider - *Extends:* aws-cdk-lib.aws_ec2.IConnectable, aws-cdk-lib.aws_iam.IGrantable, constructs.IConstruct - *Implemented By:* CodeBuildRunnerProvider, Ec2RunnerProvider, EcsRunnerProvider, FargateRunnerProvider, LambdaRunnerProvider, IRunnerProvider Interface for all runner providers. This interface cannot be implemented by external code. If the built-in providers don't cover your use case, open an issue so we can discuss it. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | connections | aws-cdk-lib.aws_ec2.Connections | The network connections associated with this resource. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | The principal to grant permissions to. | | node | constructs.Node | The tree node. | | labels | string[] | GitHub Actions labels used for this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | --- ##### `connections`^Required ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### `grantPrincipal`^Required ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to. --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `labels`^Required ```typescript public readonly labels: string[]; ``` - *Type:* string[] GitHub Actions labels used for this provider. These labels are used to identify which provider should spawn a new on-demand runner. Every job sends a webhook with the labels it's looking for based on runs-on. We use match the labels from the webhook with the labels specified here. If all the labels specified here are present in the job's labels, this provider will be chosen and spawn a new runner. --- ##### `logGroup`^Required ```typescript public readonly logGroup: ILogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.ILogGroup Log group where provided runners will save their logs. Note that this is not the job log, but the runner itself. It will not contain output from the GitHub Action but only metadata on its execution. --- ### IRunnerProviderStatus - *Implemented By:* IRunnerProviderStatus Interface for runner image status used by status.json. #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | labels | string[] | Labels associated with provider. | | type | string | Runner provider type. | | ami | IRunnerAmiStatus | Details about AMI used by this runner provider. | | constructPath | string | CDK construct node path for this provider. | | image | IRunnerImageStatus | Details about Docker image used by this runner provider. | | logGroup | string | Log group for runners. | | roleArn | string | Role attached to runners. | | securityGroups | string[] | Security groups attached to runners. | | vpcArn | string | VPC where runners will be launched. | --- ##### `labels`^Required ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with provider. --- ##### `type`^Required ```typescript public readonly type: string; ``` - *Type:* string Runner provider type. --- ##### `ami`^Optional ```typescript public readonly ami: IRunnerAmiStatus; ``` - *Type:* IRunnerAmiStatus Details about AMI used by this runner provider. --- ##### `constructPath`^Optional ```typescript public readonly constructPath: string; ``` - *Type:* string CDK construct node path for this provider. --- ##### `image`^Optional ```typescript public readonly image: IRunnerImageStatus; ``` - *Type:* IRunnerImageStatus Details about Docker image used by this runner provider. --- ##### `logGroup`^Optional ```typescript public readonly logGroup: string; ``` - *Type:* string Log group for runners. --- ##### `roleArn`^Optional ```typescript public readonly roleArn: string; ``` - *Type:* string Role attached to runners. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: string[]; ``` - *Type:* string[] Security groups attached to runners. --- ##### `vpcArn`^Optional ```typescript public readonly vpcArn: string; ``` - *Type:* string VPC where runners will be launched. --- ## Enums ### RunnerImageBuilderType #### Members | **Name** | **Description** | | --- | --- | | CODE_BUILD | Build runner images using AWS CodeBuild. | | AWS_IMAGE_BUILDER | Build runner images using AWS Image Builder. | --- ##### `CODE_BUILD` Build runner images using AWS CodeBuild. Faster than AWS Image Builder, but can only be used to build Linux Docker images. --- ##### `AWS_IMAGE_BUILDER` Build runner images using AWS Image Builder. Slower than CodeBuild, but can be used to build any type of image including AMIs and Windows images. ---