# 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. --- ### AmiBuilder - *Implements:* IRunnerImageBuilder An AMI builder that uses AWS Image Builder to build AMIs pre-baked with all the GitHub Actions runner requirements. Builders can be used with {@link Ec2RunnerProvider }. Each builder re-runs automatically at a set interval to make sure the AMIs contain the latest versions of everything. You can create an instance of this construct to customize the AMI used to spin-up runners. Some runner providers may require custom components. Check the runner provider documentation. For example, to set a specific runner version, rebuild the image every 2 weeks, and add a few packages for the EC2 provider, use: ``` const builder = new AmiBuilder(this, 'Builder', { runnerVersion: RunnerVersion.specific('2.293.0'), rebuildInterval: Duration.days(14), }); builder.addComponent(new ImageBuilderComponent(scope, id, { platform: 'Linux', displayName: 'p7zip', description: 'Install some more packages', commands: [ 'apt-get install p7zip', ], })); new Ec2RunnerProvider(this, 'EC2 provider', { labels: ['custom-ec2'], amiBuilder: builder, }); ``` #### Initializers ```typescript import { AmiBuilder } from '@cloudsnorkel/cdk-github-runners' new AmiBuilder(scope: Construct, id: string, props?: AmiBuilderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | AmiBuilderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* AmiBuilderProps --- #### 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 be installed. | | addExtraCertificates | Add extra trusted certificates. | | bindAmi | Called by IRunnerProvider to finalize settings and create the AMI builder. | | bindDockerImage | Build and return a Docker image with GitHub Runner installed in it. | | prependComponent | Add a component to be installed before any other components. | --- ##### ~~`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: ImageBuilderComponent): void ``` Add a component to be installed. ###### `component`^Required - *Type:* ImageBuilderComponent --- ##### ~~`addExtraCertificates`~~ ```typescript public addExtraCertificates(path: string): void ``` Add extra trusted certificates. This helps deal with self-signed certificates for GitHub Enterprise Server. ###### `path`^Required - *Type:* string path to directory containing a file called certs.pem containing all the required certificates. --- ##### ~~`bindAmi`~~ ```typescript public bindAmi(): RunnerAmi ``` Called by IRunnerProvider to finalize settings and create the AMI builder. ##### ~~`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. ##### ~~`prependComponent`~~ ```typescript public prependComponent(component: ImageBuilderComponent): void ``` Add a component to be installed before any other components. Useful for required system settings like certificates or proxy settings. ###### `component`^Required - *Type:* ImageBuilderComponent --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### ~~`isConstruct`~~ ```typescript import { AmiBuilder } from '@cloudsnorkel/cdk-github-runners' AmiBuilder.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 | The network connections associated with this resource. | --- ##### ~~`node`~~^Required - *Deprecated:* use RunnerImageBuilder, e.g. with Ec2RunnerProvider.imageBuilder() ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`connections`~~^Required - *Deprecated:* use RunnerImageBuilder, e.g. with Ec2RunnerProvider.imageBuilder() ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ### CodeBuildImageBuilder - *Implements:* IRunnerImageBuilder An image builder that uses CodeBuild to build Docker images pre-baked with all the GitHub Actions runner requirements. Builders can be used with runner providers. Each builder re-runs automatically at a set interval to make sure the images contain the latest versions of everything. You can create an instance of this construct to customize the image used to spin-up runners. Each provider has its own requirements for what an image should do. That's why they each provide their own Dockerfile. For example, to set a specific runner version, rebuild the image every 2 weeks, and add a few packages for the Fargate provider, use: ``` const builder = new CodeBuildImageBuilder(this, 'Builder', { dockerfilePath: FargateRunnerProvider.LINUX_X64_DOCKERFILE_PATH, runnerVersion: RunnerVersion.specific('2.293.0'), rebuildInterval: Duration.days(14), }); builder.setBuildArg('EXTRA_PACKAGES', 'nginx xz-utils'); new FargateRunnerProvider(this, 'Fargate provider', { labels: ['customized-fargate'], imageBuilder: builder, }); ``` #### Initializers ```typescript import { CodeBuildImageBuilder } from '@cloudsnorkel/cdk-github-runners' new CodeBuildImageBuilder(scope: Construct, id: string, props: CodeBuildImageBuilderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | CodeBuildImageBuilderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Required - *Type:* CodeBuildImageBuilderProps --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | | addExtraCertificates | Add extra trusted certificates. This helps deal with self-signed certificates for GitHub Enterprise Server. | | addFiles | Uploads a folder to the build server at a given folder name. | | addPolicyStatement | Add a policy statement to the builder to access resources required to the image build. | | addPostBuildCommand | Adds a command that runs after `docker build` and `docker push`. | | addPreBuildCommand | Adds a command that runs before `docker build`. | | bindAmi | Build and return an AMI with GitHub Runner installed in it. | | bindDockerImage | Called by IRunnerProvider to finalize settings and create the image builder. | | setBuildArg | Adds a build argument for Docker. | --- ##### ~~`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. --- ##### ~~`addExtraCertificates`~~ ```typescript public addExtraCertificates(path: string): void ``` Add extra trusted certificates. This helps deal with self-signed certificates for GitHub Enterprise Server. All first party Dockerfiles support this. Others may not. ###### `path`^Required - *Type:* string path to directory containing a file called certs.pem containing all the required certificates. --- ##### ~~`addFiles`~~ ```typescript public addFiles(sourcePath: string, destName: string): void ``` Uploads a folder to the build server at a given folder name. ###### `sourcePath`^Required - *Type:* string path to source directory. --- ###### `destName`^Required - *Type:* string name of destination folder. --- ##### ~~`addPolicyStatement`~~ ```typescript public addPolicyStatement(statement: PolicyStatement): void ``` Add a policy statement to the builder to access resources required to the image build. ###### `statement`^Required - *Type:* aws-cdk-lib.aws_iam.PolicyStatement IAM policy statement. --- ##### ~~`addPostBuildCommand`~~ ```typescript public addPostBuildCommand(command: string): void ``` Adds a command that runs after `docker build` and `docker push`. ###### `command`^Required - *Type:* string command to add. --- ##### ~~`addPreBuildCommand`~~ ```typescript public addPreBuildCommand(command: string): void ``` Adds a command that runs before `docker build`. ###### `command`^Required - *Type:* string command to add. --- ##### ~~`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 ``` Called by IRunnerProvider to finalize settings and create the image builder. ##### ~~`setBuildArg`~~ ```typescript public setBuildArg(name: string, value: string): void ``` Adds a build argument for Docker. See the documentation for the Dockerfile you're using for a list of supported build arguments. ###### `name`^Required - *Type:* string build argument name. --- ###### `value`^Required - *Type:* string build argument value. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### ~~`isConstruct`~~ ```typescript import { CodeBuildImageBuilder } from '@cloudsnorkel/cdk-github-runners' CodeBuildImageBuilder.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 | *No description.* | | props | CodeBuildImageBuilderProps | *No description.* | --- ##### ~~`node`~~^Required - *Deprecated:* use RunnerImageBuilder ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`connections`~~^Required - *Deprecated:* use RunnerImageBuilder ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections --- ##### ~~`props`~~^Required - *Deprecated:* use RunnerImageBuilder ```typescript public readonly props: CodeBuildImageBuilderProps; ``` - *Type:* CodeBuildImageBuilderProps --- ### CodeBuildRunner #### Initializers ```typescript import { CodeBuildRunner } from '@cloudsnorkel/cdk-github-runners' new CodeBuildRunner(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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### ~~`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. --- ##### ~~`getStepFunctionTask`~~ ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### ~~`grantStateMachine`~~ ```typescript public grantStateMachine(_: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `_`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`status`~~ ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`stepFunctionConstants`~~ ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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 { CodeBuildRunner } from '@cloudsnorkel/cdk-github-runners' CodeBuildRunner.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 { CodeBuildRunner } from '@cloudsnorkel/cdk-github-runners' CodeBuildRunner.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. | | image | RunnerImage | Docker image loaded with GitHub Actions Runner and its prerequisites. | | 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. | | retryableErrors | string[] | List of step functions errors that should be retried. | --- ##### ~~`node`~~^Required - *Deprecated:* use {@link CodeBuildRunnerProvider } ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`connections`~~^Required - *Deprecated:* use {@link CodeBuildRunnerProvider } ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### ~~`grantPrincipal`~~^Required - *Deprecated:* use {@link CodeBuildRunnerProvider } ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### ~~`image`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly image: RunnerImage; ``` - *Type:* RunnerImage Docker image loaded with GitHub Actions Runner and its prerequisites. The image is built by an image builder and is specific to CodeBuild. --- ##### ~~`labels`~~^Required - *Deprecated:* use {@link CodeBuildRunnerProvider } ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### ~~`logGroup`~~^Required - *Deprecated:* use {@link CodeBuildRunnerProvider } ```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 - *Deprecated:* use {@link CodeBuildRunnerProvider } ```typescript public readonly project: Project; ``` - *Type:* aws-cdk-lib.aws_codebuild.Project CodeBuild project hosting the runner. --- ##### ~~`retryableErrors`~~^Required - *Deprecated:* use {@link CodeBuildRunnerProvider } ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | LINUX_ARM64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux ARM64 with all the requirements for CodeBuild runner. | | LINUX_X64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux x64 with all the requirements for CodeBuild runner. | --- ##### ~~`LINUX_ARM64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_ARM64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux ARM64 with all the requirements for CodeBuild runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image. * `EXTRA_PACKAGES` can be used to install additional packages. * `DOCKER_CHANNEL` overrides the channel from which Docker will be downloaded. Defaults to `"stable"`. * `DIND_COMMIT` overrides the commit where dind is found. * `DOCKER_VERSION` overrides the installed Docker version. * `DOCKER_COMPOSE_VERSION` overrides the installed docker-compose version. --- ##### ~~`LINUX_X64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_X64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux x64 with all the requirements for CodeBuild runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image. * `EXTRA_PACKAGES` can be used to install additional packages. * `DOCKER_CHANNEL` overrides the channel from which Docker will be downloaded. Defaults to `"stable"`. * `DIND_COMMIT` overrides the commit where dind is found. * `DOCKER_VERSION` overrides the installed Docker version. * `DOCKER_COMPOSE_VERSION` overrides the installed docker-compose version. --- ### CodeBuildRunnerProvider - *Implements:* IRunnerProvider 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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### `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. --- ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### `grantStateMachine` ```typescript public grantStateMachine(_: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `_`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `status` ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `stepFunctionConstants` ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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. | | image | RunnerImage | Docker image loaded with GitHub Actions Runner and its prerequisites. | | 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. | | retryableErrors | string[] | List of step functions errors that should be retried. | --- ##### `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. --- ##### ~~`image`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly image: RunnerImage; ``` - *Type:* RunnerImage Docker image loaded with GitHub Actions Runner and its prerequisites. The image is built by an image builder and is specific to CodeBuild. --- ##### `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. --- ##### `retryableErrors`^Required ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | LINUX_ARM64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux ARM64 with all the requirements for CodeBuild runner. | | LINUX_X64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux x64 with all the requirements for CodeBuild runner. | --- ##### ~~`LINUX_ARM64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_ARM64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux ARM64 with all the requirements for CodeBuild runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image. * `EXTRA_PACKAGES` can be used to install additional packages. * `DOCKER_CHANNEL` overrides the channel from which Docker will be downloaded. Defaults to `"stable"`. * `DIND_COMMIT` overrides the commit where dind is found. * `DOCKER_VERSION` overrides the installed Docker version. * `DOCKER_COMPOSE_VERSION` overrides the installed docker-compose version. --- ##### ~~`LINUX_X64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_X64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux x64 with all the requirements for CodeBuild runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image. * `EXTRA_PACKAGES` can be used to install additional packages. * `DOCKER_CHANNEL` overrides the channel from which Docker will be downloaded. Defaults to `"stable"`. * `DIND_COMMIT` overrides the commit where dind is found. * `DOCKER_VERSION` overrides the installed Docker version. * `DOCKER_COMPOSE_VERSION` overrides the installed docker-compose version. --- ### ContainerImageBuilder - *Implements:* IRunnerImageBuilder An image builder that uses AWS Image Builder to build Docker images pre-baked with all the GitHub Actions runner requirements. Builders can be used with runner providers. The CodeBuild builder is better and faster. Only use this one if you have no choice. For example, if you need Windows containers. Each builder re-runs automatically at a set interval to make sure the images contain the latest versions of everything. You can create an instance of this construct to customize the image used to spin-up runners. Some runner providers may require custom components. Check the runner provider documentation. The default components work with CodeBuild and Fargate. For example, to set a specific runner version, rebuild the image every 2 weeks, and add a few packages for the Fargate provider, use: ``` const builder = new ContainerImageBuilder(this, 'Builder', { runnerVersion: RunnerVersion.specific('2.293.0'), rebuildInterval: Duration.days(14), }); new CodeBuildRunnerProvider(this, 'CodeBuild provider', { labels: ['custom-codebuild'], imageBuilder: builder, }); ``` #### Initializers ```typescript import { ContainerImageBuilder } from '@cloudsnorkel/cdk-github-runners' new ContainerImageBuilder(scope: Construct, id: string, props?: ContainerImageBuilderProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | ContainerImageBuilderProps | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Optional - *Type:* ContainerImageBuilderProps --- #### 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 be installed. | | addExtraCertificates | Add extra trusted certificates. This helps deal with self-signed certificates for GitHub Enterprise Server. | | bindAmi | Build and return an AMI with GitHub Runner installed in it. | | bindDockerImage | Called by IRunnerProvider to finalize settings and create the image builder. | | prependComponent | Add a component to be installed before any other components. | --- ##### ~~`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: ImageBuilderComponent): void ``` Add a component to be installed. ###### `component`^Required - *Type:* ImageBuilderComponent --- ##### ~~`addExtraCertificates`~~ ```typescript public addExtraCertificates(path: string): void ``` Add extra trusted certificates. This helps deal with self-signed certificates for GitHub Enterprise Server. All first party Dockerfiles support this. Others may not. ###### `path`^Required - *Type:* string path to directory containing a file called certs.pem containing all the required certificates. --- ##### ~~`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 ``` Called by IRunnerProvider to finalize settings and create the image builder. ##### ~~`prependComponent`~~ ```typescript public prependComponent(component: ImageBuilderComponent): void ``` Add a component to be installed before any other components. Useful for required system settings like certificates or proxy settings. ###### `component`^Required - *Type:* ImageBuilderComponent --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### ~~`isConstruct`~~ ```typescript import { ContainerImageBuilder } from '@cloudsnorkel/cdk-github-runners' ContainerImageBuilder.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 | The network connections associated with this resource. | | repository | aws-cdk-lib.aws_ecr.IRepository | *No description.* | --- ##### ~~`node`~~^Required - *Deprecated:* use RunnerImageBuilder ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`connections`~~^Required - *Deprecated:* use RunnerImageBuilder ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### ~~`repository`~~^Required - *Deprecated:* use RunnerImageBuilder ```typescript public readonly repository: IRepository; ``` - *Type:* aws-cdk-lib.aws_ecr.IRepository --- ### Ec2Runner #### Initializers ```typescript import { Ec2Runner } from '@cloudsnorkel/cdk-github-runners' new Ec2Runner(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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### ~~`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. --- ##### ~~`getStepFunctionTask`~~ ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### ~~`grantStateMachine`~~ ```typescript public grantStateMachine(stateMachineRole: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `stateMachineRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`status`~~ ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`stepFunctionConstants`~~ ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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 { Ec2Runner } from '@cloudsnorkel/cdk-github-runners' Ec2Runner.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 { Ec2Runner } from '@cloudsnorkel/cdk-github-runners' Ec2Runner.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. | | retryableErrors | string[] | List of step functions errors that should be retried. | --- ##### ~~`node`~~^Required - *Deprecated:* use {@link Ec2RunnerProvider } ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`connections`~~^Required - *Deprecated:* use {@link Ec2RunnerProvider } ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### ~~`grantPrincipal`~~^Required - *Deprecated:* use {@link Ec2RunnerProvider } ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### ~~`labels`~~^Required - *Deprecated:* use {@link Ec2RunnerProvider } ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### ~~`logGroup`~~^Required - *Deprecated:* use {@link Ec2RunnerProvider } ```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. --- ##### ~~`retryableErrors`~~^Required - *Deprecated:* use {@link Ec2RunnerProvider } ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- ### Ec2RunnerProvider - *Implements:* IRunnerProvider 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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### `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. --- ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### `grantStateMachine` ```typescript public grantStateMachine(stateMachineRole: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `stateMachineRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `status` ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `stepFunctionConstants` ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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. | | retryableErrors | string[] | List of step functions errors that should be retried. | --- ##### `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. --- ##### `retryableErrors`^Required ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- ### 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. 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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### `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. --- ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### `grantStateMachine` ```typescript public grantStateMachine(_: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `_`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `status` ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `stepFunctionConstants` ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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. | | retryableErrors | string[] | List of step functions errors that should be retried. | --- ##### `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. --- ##### `retryableErrors`^Required ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- ### FargateRunner #### Initializers ```typescript import { FargateRunner } from '@cloudsnorkel/cdk-github-runners' new FargateRunner(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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### ~~`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. --- ##### ~~`getStepFunctionTask`~~ ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### ~~`grantStateMachine`~~ ```typescript public grantStateMachine(_: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `_`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`status`~~ ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`stepFunctionConstants`~~ ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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 { FargateRunner } from '@cloudsnorkel/cdk-github-runners' FargateRunner.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 { FargateRunner } from '@cloudsnorkel/cdk-github-runners' FargateRunner.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. | | assignPublicIp | boolean | Whether runner task will have a public IP. | | 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. | | container | aws-cdk-lib.aws_ecs.ContainerDefinition | Container definition hosting the runner. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | Grant principal used to add permissions to the runner role. | | image | RunnerImage | Docker image loaded with GitHub Actions Runner and its prerequisites. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | | retryableErrors | string[] | List of step functions errors that should be retried. | | spot | boolean | Use spot pricing for Fargate tasks. | | task | aws-cdk-lib.aws_ecs.FargateTaskDefinition | Fargate task hosting the runner. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Subnets used for hosting the runner task. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC used for hosting the runner task. | --- ##### ~~`node`~~^Required - *Deprecated:* use {@link FargateRunnerProvider } ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`assignPublicIp`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly assignPublicIp: boolean; ``` - *Type:* boolean Whether runner task will have a public IP. --- ##### ~~`cluster`~~^Required - *Deprecated:* use {@link FargateRunnerProvider } ```typescript public readonly cluster: Cluster; ``` - *Type:* aws-cdk-lib.aws_ecs.Cluster Cluster hosting the task hosting the runner. --- ##### ~~`connections`~~^Required - *Deprecated:* use {@link FargateRunnerProvider } ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### ~~`container`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly container: ContainerDefinition; ``` - *Type:* aws-cdk-lib.aws_ecs.ContainerDefinition Container definition hosting the runner. --- ##### ~~`grantPrincipal`~~^Required - *Deprecated:* use {@link FargateRunnerProvider } ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### ~~`image`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly image: RunnerImage; ``` - *Type:* RunnerImage Docker image loaded with GitHub Actions Runner and its prerequisites. The image is built by an image builder and is specific to Fargate tasks. --- ##### ~~`labels`~~^Required - *Deprecated:* use {@link FargateRunnerProvider } ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### ~~`logGroup`~~^Required - *Deprecated:* use {@link FargateRunnerProvider } ```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. --- ##### ~~`retryableErrors`~~^Required - *Deprecated:* use {@link FargateRunnerProvider } ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- ##### ~~`spot`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly spot: boolean; ``` - *Type:* boolean Use spot pricing for Fargate tasks. --- ##### ~~`task`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly task: FargateTaskDefinition; ``` - *Type:* aws-cdk-lib.aws_ecs.FargateTaskDefinition Fargate task hosting the runner. --- ##### ~~`subnetSelection`~~^Optional - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection Subnets used for hosting the runner task. --- ##### ~~`vpc`~~^Optional - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc VPC used for hosting the runner task. --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | LINUX_ARM64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux ARM64 with all the requirement for Fargate runner. | | LINUX_X64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux x64 with all the requirement for Fargate runner. | --- ##### ~~`LINUX_ARM64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_ARM64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux ARM64 with all the requirement for Fargate runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image. * `EXTRA_PACKAGES` can be used to install additional packages. --- ##### ~~`LINUX_X64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_X64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux x64 with all the requirement for Fargate runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image. * `EXTRA_PACKAGES` can be used to install additional packages. --- ### 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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### `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. --- ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### `grantStateMachine` ```typescript public grantStateMachine(_: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `_`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `status` ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `stepFunctionConstants` ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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. | | assignPublicIp | boolean | Whether runner task will have a public IP. | | 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. | | container | aws-cdk-lib.aws_ecs.ContainerDefinition | Container definition hosting the runner. | | grantPrincipal | aws-cdk-lib.aws_iam.IPrincipal | Grant principal used to add permissions to the runner role. | | image | RunnerImage | Docker image loaded with GitHub Actions Runner and its prerequisites. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | | retryableErrors | string[] | List of step functions errors that should be retried. | | spot | boolean | Use spot pricing for Fargate tasks. | | task | aws-cdk-lib.aws_ecs.FargateTaskDefinition | Fargate task hosting the runner. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Subnets used for hosting the runner task. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC used for hosting the runner task. | --- ##### `node`^Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`assignPublicIp`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly assignPublicIp: boolean; ``` - *Type:* boolean Whether runner task will have a public IP. --- ##### `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. --- ##### ~~`container`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly container: ContainerDefinition; ``` - *Type:* aws-cdk-lib.aws_ecs.ContainerDefinition Container definition hosting the 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. --- ##### ~~`image`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly image: RunnerImage; ``` - *Type:* RunnerImage Docker image loaded with GitHub Actions Runner and its prerequisites. The image is built by an image builder and is specific to Fargate tasks. --- ##### `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. --- ##### `retryableErrors`^Required ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- ##### ~~`spot`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly spot: boolean; ``` - *Type:* boolean Use spot pricing for Fargate tasks. --- ##### ~~`task`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly task: FargateTaskDefinition; ``` - *Type:* aws-cdk-lib.aws_ecs.FargateTaskDefinition Fargate task hosting the runner. --- ##### ~~`subnetSelection`~~^Optional - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection Subnets used for hosting the runner task. --- ##### ~~`vpc`~~^Optional - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc VPC used for hosting the runner task. --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | LINUX_ARM64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux ARM64 with all the requirement for Fargate runner. | | LINUX_X64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux x64 with all the requirement for Fargate runner. | --- ##### ~~`LINUX_ARM64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_ARM64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux ARM64 with all the requirement for Fargate runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image. * `EXTRA_PACKAGES` can be used to install additional packages. --- ##### ~~`LINUX_X64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_X64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux x64 with all the requirement for Fargate runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image. * `EXTRA_PACKAGES` can be used to install additional packages. --- ### 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. | | 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. | | 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. --- ##### `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 * "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. 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 --- ##### `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 --- ### ImageBuilderComponent Components are a set of commands to run and optional files to add to an image. Components are the building blocks of images built by Image Builder. Example: ``` new ImageBuilderComponent(this, 'AWS CLI', { platform: 'Windows', displayName: 'AWS CLI', description: 'Install latest version of AWS CLI', commands: [ '$p = Start-Process msiexec.exe -PassThru -Wait -ArgumentList \'/i https://awscli.amazonaws.com/AWSCLIV2.msi /qn\'', 'if ($p.ExitCode -ne 0) { throw "Exit code is $p.ExitCode" }', ], } ``` #### Initializers ```typescript import { ImageBuilderComponent } from '@cloudsnorkel/cdk-github-runners' new ImageBuilderComponent(scope: Construct, id: string, props: ImageBuilderComponentProperties) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | *No description.* | | id | string | *No description.* | | props | ImageBuilderComponentProperties | *No description.* | --- ##### `scope`^Required - *Type:* constructs.Construct --- ##### `id`^Required - *Type:* string --- ##### `props`^Required - *Type:* ImageBuilderComponentProperties --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | | applyRemovalPolicy | Apply the given removal policy to this resource. | | grantAssetsRead | Grants read permissions to the principal on the assets buckets. | | prefixCommandsWithErrorHandling | *No description.* | --- ##### ~~`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. --- ##### ~~`applyRemovalPolicy`~~ ```typescript public applyRemovalPolicy(policy: RemovalPolicy): void ``` Apply the given removal policy to this resource. The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced. The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS account for data recovery and cleanup later (`RemovalPolicy.RETAIN`). ###### `policy`^Required - *Type:* aws-cdk-lib.RemovalPolicy --- ##### ~~`grantAssetsRead`~~ ```typescript public grantAssetsRead(grantee: IGrantable): void ``` Grants read permissions to the principal on the assets buckets. ###### `grantee`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`prefixCommandsWithErrorHandling`~~ ```typescript public prefixCommandsWithErrorHandling(platform: string, commands: string[]): string[] ``` ###### `platform`^Required - *Type:* string --- ###### `commands`^Required - *Type:* string[] --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | | isOwnedResource | Returns true if the construct was created by CDK, and false otherwise. | | isResource | Check whether the given construct is a Resource. | --- ##### ~~`isConstruct`~~ ```typescript import { ImageBuilderComponent } from '@cloudsnorkel/cdk-github-runners' ImageBuilderComponent.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. --- ##### ~~`isOwnedResource`~~ ```typescript import { ImageBuilderComponent } from '@cloudsnorkel/cdk-github-runners' ImageBuilderComponent.isOwnedResource(construct: IConstruct) ``` Returns true if the construct was created by CDK, and false otherwise. ###### `construct`^Required - *Type:* constructs.IConstruct --- ##### ~~`isResource`~~ ```typescript import { ImageBuilderComponent } from '@cloudsnorkel/cdk-github-runners' ImageBuilderComponent.isResource(construct: IConstruct) ``` Check whether the given construct is a Resource. ###### `construct`^Required - *Type:* constructs.IConstruct --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | env | aws-cdk-lib.interfaces.ResourceEnvironment | The environment this resource belongs to. | | stack | aws-cdk-lib.Stack | The stack in which this resource is defined. | | arn | string | Component ARN. | | platform | string | Supported platform for the component. | --- ##### ~~`node`~~^Required - *Deprecated:* Use `RunnerImageComponent` instead as this be internal soon. ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`env`~~^Required - *Deprecated:* Use `RunnerImageComponent` instead as this be internal soon. ```typescript public readonly env: ResourceEnvironment; ``` - *Type:* aws-cdk-lib.interfaces.ResourceEnvironment The environment this resource belongs to. For resources that are created and managed in a Stack (those created by creating new class instances like `new Role()`, `new Bucket()`, etc.), this is always the same as the environment of the stack they belong to. For referenced resources (those obtained from referencing methods like `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be different than the stack they were imported into. --- ##### ~~`stack`~~^Required - *Deprecated:* Use `RunnerImageComponent` instead as this be internal soon. ```typescript public readonly stack: Stack; ``` - *Type:* aws-cdk-lib.Stack The stack in which this resource is defined. --- ##### ~~`arn`~~^Required - *Deprecated:* Use `RunnerImageComponent` instead as this be internal soon. ```typescript public readonly arn: string; ``` - *Type:* string Component ARN. --- ##### ~~`platform`~~^Required - *Deprecated:* Use `RunnerImageComponent` instead as this be internal soon. ```typescript public readonly platform: string; ``` - *Type:* string Supported platform for the component. --- ### LambdaRunner #### Initializers ```typescript import { LambdaRunner } from '@cloudsnorkel/cdk-github-runners' new LambdaRunner(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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### ~~`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. --- ##### ~~`getStepFunctionTask`~~ ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### ~~`grantStateMachine`~~ ```typescript public grantStateMachine(_: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `_`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`status`~~ ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### ~~`stepFunctionConstants`~~ ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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 { LambdaRunner } from '@cloudsnorkel/cdk-github-runners' LambdaRunner.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 { LambdaRunner } from '@cloudsnorkel/cdk-github-runners' LambdaRunner.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. | | image | RunnerImage | Docker image loaded with GitHub Actions Runner and its prerequisites. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | | retryableErrors | string[] | List of step functions errors that should be retried. | --- ##### ~~`node`~~^Required - *Deprecated:* use {@link LambdaRunnerProvider } ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### ~~`connections`~~^Required - *Deprecated:* use {@link LambdaRunnerProvider } ```typescript public readonly connections: Connections; ``` - *Type:* aws-cdk-lib.aws_ec2.Connections The network connections associated with this resource. --- ##### ~~`function`~~^Required - *Deprecated:* use {@link LambdaRunnerProvider } ```typescript public readonly function: Function; ``` - *Type:* aws-cdk-lib.aws_lambda.Function The function hosting the GitHub runner. --- ##### ~~`grantPrincipal`~~^Required - *Deprecated:* use {@link LambdaRunnerProvider } ```typescript public readonly grantPrincipal: IPrincipal; ``` - *Type:* aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role. --- ##### ~~`image`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly image: RunnerImage; ``` - *Type:* RunnerImage Docker image loaded with GitHub Actions Runner and its prerequisites. The image is built by an image builder and is specific to Lambda. --- ##### ~~`labels`~~^Required - *Deprecated:* use {@link LambdaRunnerProvider } ```typescript public readonly labels: string[]; ``` - *Type:* string[] Labels associated with this provider. --- ##### ~~`logGroup`~~^Required - *Deprecated:* use {@link LambdaRunnerProvider } ```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. --- ##### ~~`retryableErrors`~~^Required - *Deprecated:* use {@link LambdaRunnerProvider } ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | LINUX_ARM64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux ARM64 with all the requirement for Lambda runner. | | LINUX_X64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux x64 with all the requirement for Lambda runner. | --- ##### ~~`LINUX_ARM64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_ARM64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux ARM64 with all the requirement for Lambda runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be similar to public.ecr.aws/lambda/nodejs:14. * `EXTRA_PACKAGES` can be used to install additional packages. --- ##### ~~`LINUX_X64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_X64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux x64 with all the requirement for Lambda runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be similar to public.ecr.aws/lambda/nodejs:14. * `EXTRA_PACKAGES` can be used to install additional packages. --- ### LambdaRunnerProvider - *Implements:* IRunnerProvider GitHub Actions runner provider using Lambda to execute jobs. Creates a Docker-based function that gets executed 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 { 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. | | getStepFunctionTask | Generate step function task(s) to start a new runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Override to inject static strings into `$.consts` on the orchestrator state machine. | --- ##### `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. --- ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters workflow job details. --- ##### `grantStateMachine` ```typescript public grantStateMachine(_: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `_`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `status` ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable --- ##### `stepFunctionConstants` ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Override to inject static strings into `$.consts` on the orchestrator state machine. #### 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. | | image | RunnerImage | Docker image loaded with GitHub Actions Runner and its prerequisites. | | labels | string[] | Labels associated with this provider. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group where provided runners will save their logs. | | retryableErrors | string[] | List of step functions errors that should be retried. | --- ##### `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. --- ##### ~~`image`~~^Required - *Deprecated:* This field is internal and should not be accessed directly. ```typescript public readonly image: RunnerImage; ``` - *Type:* RunnerImage Docker image loaded with GitHub Actions Runner and its prerequisites. The image is built by an image builder and is specific to Lambda. --- ##### `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. --- ##### `retryableErrors`^Required ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- #### Constants | **Name** | **Type** | **Description** | | --- | --- | --- | | LINUX_ARM64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux ARM64 with all the requirement for Lambda runner. | | LINUX_X64_DOCKERFILE_PATH | string | Path to Dockerfile for Linux x64 with all the requirement for Lambda runner. | --- ##### ~~`LINUX_ARM64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_ARM64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux ARM64 with all the requirement for Lambda runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be similar to public.ecr.aws/lambda/nodejs:14. * `EXTRA_PACKAGES` can be used to install additional packages. --- ##### ~~`LINUX_X64_DOCKERFILE_PATH`~~^Required - *Deprecated:* Use `imageBuilder()` instead. ```typescript public readonly LINUX_X64_DOCKERFILE_PATH: string; ``` - *Type:* string Path to Dockerfile for Linux x64 with all the requirement for Lambda runner. Use this Dockerfile unless you need to customize it further than allowed by hooks. Available build arguments that can be set in the image builder: * `BASE_IMAGE` sets the `FROM` line. This should be similar to public.ecr.aws/lambda/nodejs:14. * `EXTRA_PACKAGES` can be used to install additional packages. --- ### 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'. --- ### AmiBuilderProps Properties for {@link AmiBuilder} construct. #### Initializer ```typescript import { AmiBuilderProps } from '@cloudsnorkel/cdk-github-runners' const amiBuilderProps: AmiBuilderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | architecture | Architecture | Image architecture. | | installDocker | boolean | Install Docker inside the image, so it can be used by the runner. | | instanceType | aws-cdk-lib.aws_ec2.InstanceType | The instance type used to build the image. | | 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 AMI to be rebuilt every given interval. | | runnerVersion | RunnerVersion | Version of GitHub Runners to install. | | securityGroup | aws-cdk-lib.aws_ec2.ISecurityGroup | Security group to assign to launched builder instances. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups to assign to launched builder instances. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Where to place the network interfaces within the VPC. | | vpc | aws-cdk-lib.aws_ec2.IVpc | VPC where builder instances will be launched. | --- ##### `architecture`^Optional ```typescript public readonly architecture: Architecture; ``` - *Type:* Architecture - *Default:* Architecture.X86_64 Image architecture. --- ##### `installDocker`^Optional ```typescript public readonly installDocker: boolean; ``` - *Type:* boolean - *Default:* true Install Docker inside the image, so it can be used by the runner. --- ##### `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. --- ##### `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 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 Image OS. --- ##### `rebuildInterval`^Optional ```typescript public readonly rebuildInterval: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* Duration.days(7) Schedule the AMI to be rebuilt every given interval. Useful for keeping the AMI 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. --- ##### ~~`securityGroup`~~^Optional - *Deprecated:* use {@link securityGroups } ```typescript public readonly securityGroup: ISecurityGroup; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup - *Default:* new security group Security group to assign to launched builder instances. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] - *Default:* new security group Security groups to assign to launched builder instances. --- ##### `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. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc - *Default:* default account VPC VPC where builder instances will be launched. --- ### 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** | | --- | --- | --- | | 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. | --- ##### `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. --- ### CodeBuildImageBuilderProps Properties for CodeBuildImageBuilder construct. #### Initializer ```typescript import { CodeBuildImageBuilderProps } from '@cloudsnorkel/cdk-github-runners' const codeBuildImageBuilderProps: CodeBuildImageBuilderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | dockerfilePath | string | Path to Dockerfile to be built. | | architecture | Architecture | Image architecture. | | 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. | | 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. | | securityGroup | aws-cdk-lib.aws_ec2.ISecurityGroup | Security Group 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 build the image in. | --- ##### `dockerfilePath`^Required ```typescript public readonly dockerfilePath: string; ``` - *Type:* string Path to Dockerfile to be built. It can be a path to a Dockerfile, a folder containing a Dockerfile, or a zip file containing a Dockerfile. --- ##### `architecture`^Optional ```typescript public readonly architecture: Architecture; ``` - *Type:* Architecture - *Default:* Architecture.X86_64 Image architecture. --- ##### `buildImage`^Optional ```typescript public readonly buildImage: IBuildImage; ``` - *Type:* aws-cdk-lib.aws_codebuild.IBuildImage - *Default:* Ubuntu 22.04 for x64 and Amazon Linux 2 for ARM64 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. --- ##### `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 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. --- ##### `securityGroup`^Optional ```typescript public readonly securityGroup: ISecurityGroup; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup - *Default:* public project with no security group Security Group 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 build the image in. --- ### 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. | | retryOptions | ProviderRetryOptions | *No description.* | | 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. | | label | string | GitHub Actions label used for this provider. | | labels | string[] | GitHub Actions labels used for this provider. | | securityGroup | aws-cdk-lib.aws_ec2.ISecurityGroup | Security group to assign to this instance. | | 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`. --- ##### ~~`retryOptions`~~^Optional - *Deprecated:* use {@link retryOptions } on {@link GitHubRunners } instead ```typescript public readonly retryOptions: ProviderRetryOptions; ``` - *Type:* ProviderRetryOptions --- ##### `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. 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. --- ##### ~~`label`~~^Optional - *Deprecated:* use {@link labels } instead ```typescript public readonly label: string; ``` - *Type:* string - *Default:* undefined GitHub Actions label used for this provider. --- ##### `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. --- ##### ~~`securityGroup`~~^Optional - *Deprecated:* use {@link securityGroups } ```typescript public readonly securityGroup: ISecurityGroup; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup - *Default:* public project with no security group Security group to assign to this instance. --- ##### `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. --- ### ContainerImageBuilderProps Properties for ContainerImageBuilder construct. #### Initializer ```typescript import { ContainerImageBuilderProps } from '@cloudsnorkel/cdk-github-runners' const containerImageBuilderProps: ContainerImageBuilderProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | architecture | Architecture | Image architecture. | | instanceType | aws-cdk-lib.aws_ec2.InstanceType | The instance type used to build the image. | | 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. | | parentImage | string | Parent image for the new Docker Image. | | rebuildInterval | aws-cdk-lib.Duration | Schedule the image to be rebuilt every given interval. | | runnerVersion | RunnerVersion | Version of GitHub Runners to install. | | securityGroup | aws-cdk-lib.aws_ec2.ISecurityGroup | Security group to assign to launched builder instances. | | securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups to assign to launched builder instances. | | 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 launch the runners in. | --- ##### `architecture`^Optional ```typescript public readonly architecture: Architecture; ``` - *Type:* Architecture - *Default:* Architecture.X86_64 Image architecture. --- ##### `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. --- ##### `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 Image OS. --- ##### `parentImage`^Optional ```typescript public readonly parentImage: string; ``` - *Type:* string - *Default:* 'mcr.microsoft.com/windows/servercore:ltsc2019-amd64' Parent image for the new Docker Image. You can use either Image Builder image ARN or public registry image. --- ##### `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. --- ##### ~~`securityGroup`~~^Optional - *Deprecated:* use {@link securityGroups } ```typescript public readonly securityGroup: ISecurityGroup; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup - *Default:* new security group Security group to assign to launched builder instances. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] - *Default:* new security group Security groups to assign to launched builder instances. --- ##### `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. --- ##### `vpc`^Optional ```typescript public readonly vpc: IVpc; ``` - *Type:* aws-cdk-lib.aws_ec2.IVpc - *Default:* default account 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. | | retryOptions | ProviderRetryOptions | *No description.* | | amiBuilder | IRunnerImageBuilder | *No description.* | | 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. | | securityGroup | aws-cdk-lib.aws_ec2.ISecurityGroup | Security Group to assign to launched runner instances. | | 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. | | subnet | aws-cdk-lib.aws_ec2.ISubnet | Subnet where the runner instances will be launched. | | subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Where to place the network interfaces within the VPC. | | 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`. --- ##### ~~`retryOptions`~~^Optional - *Deprecated:* use {@link retryOptions } on {@link GitHubRunners } instead ```typescript public readonly retryOptions: ProviderRetryOptions; ``` - *Type:* ProviderRetryOptions --- ##### ~~`amiBuilder`~~^Optional - *Deprecated:* use imageBuilder ```typescript public readonly amiBuilder: IRunnerImageBuilder; ``` - *Type:* IRunnerImageBuilder --- ##### `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. 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. --- ##### ~~`securityGroup`~~^Optional - *Deprecated:* use {@link securityGroups } ```typescript public readonly securityGroup: ISecurityGroup; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup - *Default:* a new security group Security Group to assign to launched runner instances. --- ##### `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. --- ##### ~~`subnet`~~^Optional - *Deprecated:* use {@link vpc } and {@link subnetSelection } ```typescript public readonly subnet: ISubnet; ``` - *Type:* aws-cdk-lib.aws_ec2.ISubnet - *Default:* default subnet of account's default VPC Subnet where the runner instances will be launched. --- ##### `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. --- ##### `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. | | retryOptions | ProviderRetryOptions | *No description.* | | assignPublicIp | boolean | Assign public IP to the runner task. | | 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 CodeBuild privileged mode. | | 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. | | 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`. --- ##### ~~`retryOptions`~~^Optional - *Deprecated:* use {@link retryOptions } on {@link GitHubRunners } instead ```typescript public readonly retryOptions: ProviderRetryOptions; ``` - *Type:* ProviderRetryOptions --- ##### `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. --- ##### `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. --- ##### `cluster`^Optional ```typescript public readonly cluster: Cluster; ``` - *Type:* aws-cdk-lib.aws_ecs.Cluster - *Default:* a new cluster Existing ECS cluster to use. --- ##### `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 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: 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. 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. --- ##### `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. | | retryOptions | ProviderRetryOptions | *No description.* | | 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. | | label | string | GitHub Actions label used for this provider. | | labels | string[] | GitHub Actions labels used for this provider. | | memoryLimitMiB | number | The amount (in MiB) of memory used by the task. | | securityGroup | aws-cdk-lib.aws_ec2.ISecurityGroup | Security group to assign to 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. | | 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`. --- ##### ~~`retryOptions`~~^Optional - *Deprecated:* use {@link retryOptions } on {@link GitHubRunners } instead ```typescript public readonly retryOptions: ProviderRetryOptions; ``` - *Type:* ProviderRetryOptions --- ##### `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. 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. --- ##### ~~`label`~~^Optional - *Deprecated:* use {@link labels } instead ```typescript public readonly label: string; ``` - *Type:* string - *Default:* undefined GitHub Actions label used for this provider. --- ##### `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) --- ##### ~~`securityGroup`~~^Optional - *Deprecated:* use {@link securityGroups } ```typescript public readonly securityGroup: ISecurityGroup; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup - *Default:* a new security group Security group to assign to the task. --- ##### `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. --- ##### `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. | | securityGroup | aws-cdk-lib.aws_ec2.ISecurityGroup | Security group attached to all management functions. | | 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 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 23 times up to about 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. Total time spent waiting can be calculated with interval * (backoffRate ^ maxAttempts) / (backoffRate - 1). --- ##### ~~`securityGroup`~~^Optional - *Deprecated:* use {@link securityGroups } instead ```typescript public readonly securityGroup: ISecurityGroup; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup Security group attached to all management functions. Use this with to provide access to GitHub Enterprise Server hosted inside a VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting. --- ##### `securityGroups`^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 (status function only) * 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. --- ### ImageBuilderAsset An asset including file or directory to place inside the built image. #### Initializer ```typescript import { ImageBuilderAsset } from '@cloudsnorkel/cdk-github-runners' const imageBuilderAsset: ImageBuilderAsset = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | asset | aws-cdk-lib.aws_s3_assets.Asset | Asset to place in the image. | | path | string | Path to place asset in the image. | --- ##### `asset`^Required ```typescript public readonly asset: Asset; ``` - *Type:* aws-cdk-lib.aws_s3_assets.Asset Asset to place in the image. --- ##### `path`^Required ```typescript public readonly path: string; ``` - *Type:* string Path to place asset in the image. --- ### ImageBuilderComponentProperties Properties for ImageBuilderComponent construct. #### Initializer ```typescript import { ImageBuilderComponentProperties } from '@cloudsnorkel/cdk-github-runners' const imageBuilderComponentProperties: ImageBuilderComponentProperties = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | commands | string[] | Shell commands to run when adding this component to the image. | | description | string | Component description. | | displayName | string | Component display name. | | platform | string | Component platform. | | assets | ImageBuilderAsset[] | Optional assets to add to the built image. | | reboot | boolean | Require a reboot after installing this component. | --- ##### `commands`^Required ```typescript public readonly commands: string[]; ``` - *Type:* string[] Shell commands to run when adding this component to the image. On Linux, these are bash commands. On Windows, there are PowerShell commands. --- ##### `description`^Required ```typescript public readonly description: string; ``` - *Type:* string Component description. --- ##### `displayName`^Required ```typescript public readonly displayName: string; ``` - *Type:* string Component display name. --- ##### `platform`^Required ```typescript public readonly platform: string; ``` - *Type:* string Component platform. Must match the builder platform. --- ##### `assets`^Optional ```typescript public readonly assets: ImageBuilderAsset[]; ``` - *Type:* ImageBuilderAsset[] Optional assets to add to the built image. --- ##### `reboot`^Optional ```typescript public readonly reboot: boolean; ``` - *Type:* boolean - *Default:* false Require a reboot after installing this component. --- ### 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. | | retryOptions | ProviderRetryOptions | *No description.* | | 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. | | label | string | GitHub Actions label used for this provider. | | labels | string[] | GitHub Actions labels used for this provider. | | memorySize | number | The amount of memory, in MB, that is allocated to your Lambda function. | | securityGroup | aws-cdk-lib.aws_ec2.ISecurityGroup | Security group to assign to this instance. | | 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`. --- ##### ~~`retryOptions`~~^Optional - *Deprecated:* use {@link retryOptions } on {@link GitHubRunners } instead ```typescript public readonly retryOptions: ProviderRetryOptions; ``` - *Type:* ProviderRetryOptions --- ##### `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. 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. --- ##### ~~`label`~~^Optional - *Deprecated:* use {@link labels } instead ```typescript public readonly label: string; ``` - *Type:* string - *Default:* undefined GitHub Actions label used for this provider. --- ##### `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. --- ##### ~~`securityGroup`~~^Optional - *Deprecated:* use {@link securityGroups } ```typescript public readonly securityGroup: ISecurityGroup; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup - *Default:* public lambda with no security group Security group to assign to this instance. --- ##### `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:* false Determines whether execution data is included in your log. --- ##### `level`^Optional ```typescript public readonly level: LogLevel; ``` - *Type:* aws-cdk-lib.aws_stepfunctions.LogLevel - *Default:* ERROR 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 23 times for about 24 hours with increasing interval. #### 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. | | retry | boolean | Set to true to retry provider on supported failures. | --- ##### `backoffRate`^Optional ```typescript public readonly backoffRate: number; ``` - *Type:* number - *Default:* 1.3 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. --- ##### `maxAttempts`^Optional ```typescript public readonly maxAttempts: number; ``` - *Type:* number - *Default:* 23 How many times to retry. --- ##### `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. | | runnerVersion | RunnerVersion | Installed runner version. | | 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. --- ##### ~~`runnerVersion`~~^Required - *Deprecated:* open a ticket if you need this ```typescript public readonly runnerVersion: RunnerVersion; ``` - *Type:* RunnerVersion Installed runner version. --- ##### `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. | | runnerVersion | RunnerVersion | Installed runner version. | | 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. --- ##### ~~`runnerVersion`~~^Required - *Deprecated:* open a ticket if you need this ```typescript public readonly runnerVersion: RunnerVersion; ``` - *Type:* RunnerVersion Installed runner version. --- ##### `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 | string \| BaseImage | Base AMI from which runner AMIs will be built. | | baseDockerImage | string \| 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: string | BaseImage; ``` - *Type:* string | 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 string (AMI ID, Image Builder ARN, SSM parameter reference, or Marketplace product ID) - deprecated, use BaseImage static factory methods instead - A BaseImage instance created using static factory methods: - `BaseImage.fromAmiId('ami-12345')` - Use an AMI ID - `BaseImage.fromString('arn:aws:imagebuilder:...')` - Use any string (ARN, AMI ID, etc.) - `BaseImage.fromSsmParameter(parameter)` - Use an SSM parameter object - `BaseImage.fromSsmParameterName('/aws/service/ami/...')` - Use an SSM parameter by name - `BaseImage.fromMarketplaceProductId('product-id')` - Use a Marketplace product ID - `BaseImage.fromImageBuilder(scope, 'ubuntu-server-22-lts-x86')` - Use an AWS-provided Image Builder image For example `BaseImage.fromImageBuilder(scope, 'ubuntu-server-22-lts-x86')` would always use the latest version of Ubuntu 22.04 in each build. If you want a specific version, you can pass the version as the third parameter. --- ##### `baseDockerImage`^Optional ```typescript public readonly baseDockerImage: string | BaseContainerImage; ``` - *Type:* string | 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 string (ECR/ECR public image URI, DockerHub image, or Image Builder ARN) - deprecated, use BaseContainerImage static factory methods instead - A BaseContainerImage instance created using static factory methods: - `BaseContainerImage.fromDockerHub('ubuntu', '22.04')` - Use DockerHub - `BaseContainerImage.fromEcr(repo, 'latest')` - Use ECR (automatically grants permissions with CodeBuild) - `BaseContainerImage.fromEcrPublic('lts', 'ubuntu', '22.04')` - Use ECR Public - `BaseContainerImage.fromString('public.ecr.aws/lts/ubuntu:22.04')` - Use any string When using private images from a different account or not on ECR, you may need to include additional setup commands with {@link dockerSetupCommands}. --- ##### `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. | | retryOptions | ProviderRetryOptions | *No description.* | --- ##### `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`. --- ##### ~~`retryOptions`~~^Optional - *Deprecated:* use {@link retryOptions } on {@link GitHubRunners } instead ```typescript public readonly retryOptions: ProviderRetryOptions; ``` - *Type:* ProviderRetryOptions --- ### 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. ### LinuxUbuntuComponents Components for Ubuntu Linux that can be used with AWS Image Builder based builders. These cannot be used by {@link CodeBuildImageBuilder }. #### Initializers ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' new LinuxUbuntuComponents() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Static Functions | **Name** | **Description** | | --- | --- | | awsCli | *No description.* | | docker | *No description.* | | extraCertificates | *No description.* | | git | *No description.* | | githubCli | *No description.* | | githubRunner | *No description.* | | requiredPackages | *No description.* | | runnerUser | *No description.* | --- ##### ~~`awsCli`~~ ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' LinuxUbuntuComponents.awsCli(scope: Construct, id: string, architecture: Architecture) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `architecture`^Required - *Type:* Architecture --- ##### ~~`docker`~~ ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' LinuxUbuntuComponents.docker(scope: Construct, id: string, _architecture: Architecture) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `_architecture`^Required - *Type:* Architecture --- ##### ~~`extraCertificates`~~ ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' LinuxUbuntuComponents.extraCertificates(scope: Construct, id: string, path: string) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `path`^Required - *Type:* string --- ##### ~~`git`~~ ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' LinuxUbuntuComponents.git(scope: Construct, id: string, _architecture: Architecture) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `_architecture`^Required - *Type:* Architecture --- ##### ~~`githubCli`~~ ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' LinuxUbuntuComponents.githubCli(scope: Construct, id: string, _architecture: Architecture) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `_architecture`^Required - *Type:* Architecture --- ##### ~~`githubRunner`~~ ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' LinuxUbuntuComponents.githubRunner(scope: Construct, id: string, runnerVersion: RunnerVersion, architecture: Architecture) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `runnerVersion`^Required - *Type:* RunnerVersion --- ###### `architecture`^Required - *Type:* Architecture --- ##### ~~`requiredPackages`~~ ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' LinuxUbuntuComponents.requiredPackages(scope: Construct, id: string, architecture: Architecture) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `architecture`^Required - *Type:* Architecture --- ##### ~~`runnerUser`~~ ```typescript import { LinuxUbuntuComponents } from '@cloudsnorkel/cdk-github-runners' LinuxUbuntuComponents.runnerUser(scope: Construct, id: string, _architecture: Architecture) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `_architecture`^Required - *Type:* Architecture --- ### 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 | Os | Linux. | | 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`~~^Required - *Deprecated:* use {@link LINUX_UBUNTU }, {@link LINUX_UBUNTU_2404 }, {@link LINUX_AMAZON_2 } or {@link LINUX_AMAZON_2023 } ```typescript public readonly LINUX: Os; ``` - *Type:* Os Linux. --- ##### `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. | | dockerInDocker | A component to install Docker-in-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. | | 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. --- ##### ~~`dockerInDocker`~~ ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.dockerInDocker(version?: string) ``` A component to install Docker-in-Docker. ###### `version`^Optional - *Type:* string Software version to install (e.g. '29.1.5'). Default: latest. --- ##### `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. --- ##### `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. --- ### WindowsComponents Components for Windows that can be used with AWS Image Builder based builders. These cannot be used by {@link CodeBuildImageBuilder }. #### Initializers ```typescript import { WindowsComponents } from '@cloudsnorkel/cdk-github-runners' new WindowsComponents() ``` | **Name** | **Type** | **Description** | | --- | --- | --- | --- #### Static Functions | **Name** | **Description** | | --- | --- | | awsCli | *No description.* | | cloudwatchAgent | *No description.* | | docker | *No description.* | | extraCertificates | *No description.* | | git | *No description.* | | githubCli | *No description.* | | githubRunner | *No description.* | --- ##### ~~`awsCli`~~ ```typescript import { WindowsComponents } from '@cloudsnorkel/cdk-github-runners' WindowsComponents.awsCli(scope: Construct, id: string) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ##### ~~`cloudwatchAgent`~~ ```typescript import { WindowsComponents } from '@cloudsnorkel/cdk-github-runners' WindowsComponents.cloudwatchAgent(scope: Construct, id: string) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ##### ~~`docker`~~ ```typescript import { WindowsComponents } from '@cloudsnorkel/cdk-github-runners' WindowsComponents.docker(scope: Construct, id: string) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ##### ~~`extraCertificates`~~ ```typescript import { WindowsComponents } from '@cloudsnorkel/cdk-github-runners' WindowsComponents.extraCertificates(scope: Construct, id: string, path: string) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `path`^Required - *Type:* string --- ##### ~~`git`~~ ```typescript import { WindowsComponents } from '@cloudsnorkel/cdk-github-runners' WindowsComponents.git(scope: Construct, id: string) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ##### ~~`githubCli`~~ ```typescript import { WindowsComponents } from '@cloudsnorkel/cdk-github-runners' WindowsComponents.githubCli(scope: Construct, id: string) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ##### ~~`githubRunner`~~ ```typescript import { WindowsComponents } from '@cloudsnorkel/cdk-github-runners' WindowsComponents.githubRunner(scope: Construct, id: string, runnerVersion: RunnerVersion) ``` ###### `scope`^Required - *Type:* constructs.Construct --- ###### `id`^Required - *Type:* string --- ###### `runnerVersion`^Required - *Type:* RunnerVersion --- ## Protocols ### ICompositeProvider - *Extends:* constructs.IConstruct - *Implemented By:* ICompositeProvider Interface for composite runner providers that interact with multiple sub-providers. Unlike IRunnerProvider, composite providers do not have connections, grant capabilities, log groups, or retryable errors as they delegate to their sub-providers. #### Methods | **Name** | **Description** | | --- | --- | | getStepFunctionTask | Generate step function tasks that execute the runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return statuses of all sub-providers to be used in the main status function. | | stepFunctionConstants | Merged constants from all sub-providers for the single orchestrator `$.consts` pass. Duplicate keys across sub-providers must be avoided. | --- ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function tasks that execute the runner. If the provider has multiple attempts, each attempt should be followed by a `Catch` that deletes the failed runner. Use {@link IRunnerRuntimeParameters.addCatchAndCleanUp} to add the catch. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters specific build parameters. --- ##### `grantStateMachine` ```typescript public grantStateMachine(stateMachineRole: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `stateMachineRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable role for the state machine that executes the task returned from {@link getStepFunctionTask}. --- ##### `status` ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus[] ``` Return statuses of all sub-providers to be used in the main status function. Also gives the status function any needed permissions to query the Docker images or AMIs. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable grantable for the status function. --- ##### `stepFunctionConstants` ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Merged constants from all sub-providers for the single orchestrator `$.consts` pass. Duplicate keys across sub-providers must be avoided. #### 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:* AmiBuilder, CodeBuildImageBuilder, ContainerImageBuilder, 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:* CodeBuildRunner, CodeBuildRunnerProvider, Ec2Runner, Ec2RunnerProvider, EcsRunnerProvider, FargateRunner, FargateRunnerProvider, LambdaRunner, LambdaRunnerProvider, IRunnerProvider Interface for all runner providers. Implementations create all required resources and return a step function task that starts those resources from {@link getStepFunctionTask}. This interface is not guaranteed to be stable. If you end up implementing your own provider, please let us know so we can consider changing that contract. #### Methods | **Name** | **Description** | | --- | --- | | getStepFunctionTask | Generate step function tasks that execute the runner. | | grantStateMachine | An optional method that modifies the role of the state machine after all the tasks have been generated. | | status | Return status of the runner provider to be used in the main status function. | | stepFunctionConstants | Static string constants injected once into the orchestrator execution input at `$.consts`. Use unique keys for dynamic values (e.g. include `this.node.path` in the key). Values must be plain strings known at synthesis time. | --- ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: IRunnerRuntimeParameters): IChainable ``` Generate step function tasks that execute the runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* IRunnerRuntimeParameters specific build parameters. --- ##### `grantStateMachine` ```typescript public grantStateMachine(stateMachineRole: IGrantable): void ``` An optional method that modifies the role of the state machine after all the tasks have been generated. This can be used to add additional policy statements to the state machine role that are not automatically added by the task returned from {@link getStepFunctionTask}. ###### `stateMachineRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable role for the state machine that executes the task returned from {@link getStepFunctionTask}. --- ##### `status` ```typescript public status(statusFunctionRole: IGrantable): IRunnerProviderStatus ``` Return status of the runner provider to be used in the main status function. Also gives the status function any needed permissions to query the Docker image or AMI. ###### `statusFunctionRole`^Required - *Type:* aws-cdk-lib.aws_iam.IGrantable grantable for the status function. --- ##### `stepFunctionConstants` ```typescript public stepFunctionConstants(): {[ key: string ]: string} ``` Static string constants injected once into the orchestrator execution input at `$.consts`. Use unique keys for dynamic values (e.g. include `this.node.path` in the key). Values must be plain strings known at synthesis time. To use the constants in your provider, use `'$.consts.key'` as a path. #### 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. | | retryableErrors | string[] | List of step functions errors that should be retried. | --- ##### `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. --- ##### ~~`retryableErrors`~~^Required - *Deprecated:* do not use ```typescript public readonly retryableErrors: string[]; ``` - *Type:* string[] List of step functions errors that should be retried. --- ### 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. --- ### IRunnerRuntimeParameters - *Implemented By:* IRunnerRuntimeParameters Workflow job parameters as parsed from the webhook event. Pass these into your runner executor and run something like:. ```sh ./config.sh --unattended --url "{REGISTRATION_URL}" --token "${RUNNER_TOKEN}" --ephemeral --work _work --labels "${RUNNER_LABEL}" --name "${RUNNER_NAME}" --disableupdate ``` All parameters are specified as step function paths and therefore must be used only in step function task parameters. #### Methods | **Name** | **Description** | | --- | --- | | addCatchAndCleanUp | Catches all errors and cleans up the failed runner from GitHub Actions. | --- ##### `addCatchAndCleanUp` ```typescript public addCatchAndCleanUp(state: TaskStateBase | Parallel | Map, next?: IChainable): void ``` Catches all errors and cleans up the failed runner from GitHub Actions. It is important to fully clean up after any failed runner provisioning. GitHub will fail booting a new runner if the previous one with the same name is not fully cleaned up. ###### `state`^Required - *Type:* aws-cdk-lib.aws_stepfunctions.TaskStateBase | aws-cdk-lib.aws_stepfunctions.Parallel | aws-cdk-lib.aws_stepfunctions.Map state whose failures should trigger cleanup. --- ###### `next`^Optional - *Type:* aws-cdk-lib.aws_stepfunctions.IChainable optional subgraph to run after cleanup. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | githubDomainPath | string | Path to GitHub domain. | | labelsPath | string | Path to comma-separated labels string to use for runner. | | ownerPath | string | Path to repository owner name. | | registrationUrl | string | Repository or organization URL to register runner at. | | repoPath | string | Path to repository name. | | runnerNamePath | string | Path to desired runner name. | | runnerTokenPath | string | Path to runner token used to register token. | --- ##### `githubDomainPath`^Required ```typescript public readonly githubDomainPath: string; ``` - *Type:* string Path to GitHub domain. Most of the time this will be github.com but for self-hosted GitHub instances, this will be different. --- ##### `labelsPath`^Required ```typescript public readonly labelsPath: string; ``` - *Type:* string Path to comma-separated labels string to use for runner. --- ##### `ownerPath`^Required ```typescript public readonly ownerPath: string; ``` - *Type:* string Path to repository owner name. --- ##### `registrationUrl`^Required ```typescript public readonly registrationUrl: string; ``` - *Type:* string Repository or organization URL to register runner at. --- ##### `repoPath`^Required ```typescript public readonly repoPath: string; ``` - *Type:* string Path to repository name. --- ##### `runnerNamePath`^Required ```typescript public readonly runnerNamePath: string; ``` - *Type:* string Path to desired runner name. We specifically set the name to make troubleshooting easier. --- ##### `runnerTokenPath`^Required ```typescript public readonly runnerTokenPath: string; ``` - *Type:* string Path to runner token used to register token. --- ## 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. ---