# API Reference ## Constructs ### 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. | | 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. ##### ~~`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. ###### `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. | | 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. ##### ~~`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. ###### `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. | | 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. | --- ##### ~~`toString`~~ ```typescript public toString(): string ``` Returns a string representation of this construct. ##### ~~`getStepFunctionTask`~~ ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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:* use {@link CodeBuildRunnerProvider } ```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. | | 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. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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 ```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. | | 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. ##### ~~`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. ###### `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. | | 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. | --- ##### ~~`toString`~~ ```typescript public toString(): string ``` Returns a string representation of this construct. ##### ~~`getStepFunctionTask`~~ ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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.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. | | 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. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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.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. | | 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. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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. | | 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. --- ### 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. | | 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. | --- ##### ~~`toString`~~ ```typescript public toString(): string ``` Returns a string representation of this construct. ##### ~~`getStepFunctionTask`~~ ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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:* use {@link FargateRunnerProvider } ```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:* use {@link FargateRunnerProvider } ```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:* use {@link FargateRunnerProvider } ```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:* use {@link FargateRunnerProvider } ```typescript public readonly spot: boolean; ``` - *Type:* boolean Use spot pricing for Fargate tasks. --- ##### ~~`task`~~^Required - *Deprecated:* use {@link FargateRunnerProvider } ```typescript public readonly task: FargateTaskDefinition; ``` - *Type:* aws-cdk-lib.aws_ecs.FargateTaskDefinition Fargate task hosting the runner. --- ##### ~~`subnetSelection`~~^Optional - *Deprecated:* use {@link FargateRunnerProvider } ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection Subnets used for hosting the runner task. --- ##### ~~`vpc`~~^Optional - *Deprecated:* use {@link FargateRunnerProvider } ```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. | | 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. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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 ```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 ```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 ```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 ```typescript public readonly spot: boolean; ``` - *Type:* boolean Use spot pricing for Fargate tasks. --- ##### `task`^Required ```typescript public readonly task: FargateTaskDefinition; ``` - *Type:* aws-cdk-lib.aws_ecs.FargateTaskDefinition Fargate task hosting the runner. --- ##### `subnetSelection`^Optional ```typescript public readonly subnetSelection: SubnetSelection; ``` - *Type:* aws-cdk-lib.aws_ec2.SubnetSelection Subnets used for hosting the runner task. --- ##### `vpc`^Optional ```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. | | 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. ##### `createLogsInsightsQueries` ```typescript public createLogsInsightsQueries(): 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 ##### `failedImageBuildsTopic` ```typescript public failedImageBuildsTopic(): 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. ##### `metricFailed` ```typescript public metricFailed(props?: MetricProps): 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.MetricProps --- ##### `metricJobCompleted` ```typescript public metricJobCompleted(props?: MetricProps): 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.MetricProps --- ##### `metricSucceeded` ```typescript public metricSucceeded(props?: MetricProps): 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.MetricProps --- ##### `metricTime` ```typescript public metricTime(props?: MetricProps): 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.MetricProps --- #### 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. ###### `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[] | 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[]; ``` - *Type:* IRunnerProvider[] 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. | | 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. ##### ~~`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. ###### `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.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.ResourceEnvironment The environment this resource belongs to. For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that 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. | | 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. | --- ##### ~~`toString`~~ ```typescript public toString(): string ``` Returns a string representation of this construct. ##### ~~`getStepFunctionTask`~~ ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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:* use {@link LambdaRunnerProvider } ```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. | | 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. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function task(s) to start a new runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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 --- #### 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. ###### `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 ```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. | | 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. ##### `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. ###### `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. --- ### 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. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. #### 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. ###### `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 ### 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. | | 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. --- ##### `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** | | --- | --- | --- | | 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. | | dockerInDocker | boolean | Support building and running Docker images by enabling Docker-in-Docker (dind) and the required CodeBuild privileged mode. | | 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. | --- ##### `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. --- ##### `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. --- ##### `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** | | --- | --- | --- | | 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. | --- ##### `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. --- ##### `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** | | --- | --- | --- | | 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. | | 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. | | 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. | --- ##### `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. --- ##### `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. --- ##### `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** | | --- | --- | --- | | 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. | --- ##### `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. | | extraCertificates | string | Path to a directory containing a file named certs.pem containing any additional certificates required to trust GitHub Enterprise Server. Use this when GitHub Enterprise Server certificates are self-signed. | | 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[] | List of runner providers to use. | | 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. --- ##### `extraCertificates`^Optional ```typescript public readonly extraCertificates: string; ``` - *Type:* string Path to a directory containing a file named certs.pem containing any additional certificates required to trust GitHub Enterprise Server. Use this when GitHub Enterprise Server certificates are self-signed. You may also want to use custom images for your runner providers that contain the same certificates. See {@link CodeBuildImageBuilder.addCertificates }. ```typescript const imageBuilder = CodeBuildRunnerProvider.imageBuilder(this, 'Image Builder with Certs'); imageBuilder.addComponent(RunnerImageComponent.extraCertificates('path-to-my-extra-certs-folder/certs.pem', 'private-ca'); const provider = new CodeBuildRunnerProvider(this, 'CodeBuild', { imageBuilder: imageBuilder, }); new GitHubRunners( this, 'runners', { providers: [provider], extraCertificates: 'path-to-my-extra-certs-folder', } ); ``` --- ##### `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[]; ``` - *Type:* IRunnerProvider[] - *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. --- ##### `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. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: ISecurityGroup[]; ``` - *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[] Security groups attached to all management functions. Use this with to provide access to GitHub Enterprise Server hosted inside a VPC. --- ##### `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. 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. --- ##### `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** | | --- | --- | --- | | 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. | --- ##### `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. --- ### 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 | Base AMI from which runner AMIs will be built. | | baseDockerImage | string | 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; ``` - *Type:* string - *Default:* latest Ubuntu 22.04 AMI for Os.LINUX_UBUNTU, latest Amazon Linux 2 AMI for Os.LINUX_AMAZON_2, latest Windows Server 2022 AMI for Os.WINDOWS Base AMI from which runner AMIs will be built. This can be an actual AMI or an AWS Image Builder ARN that points to the latest AMI. For example `arn:aws:imagebuilder:us-east-1:aws:image/ubuntu-server-22-lts-x86/x.x.x` would always use the latest version of Ubuntu 22.04 in each build. If you want a specific version, you can replace `x.x.x` with that version. --- ##### `baseDockerImage`^Optional ```typescript public readonly baseDockerImage: string; ``` - *Type:* string - *Default:* public.ecr.aws/lts/ubuntu:22.04 for Os.LINUX_UBUNTU, 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. 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** | | --- | --- | --- | | logRetention | aws-cdk-lib.aws_logs.RetentionDays | The number of days log events are kept in CloudWatch Logs. | | retryOptions | ProviderRetryOptions | *No description.* | --- ##### `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 --- ### RunnerRuntimeParameters 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. #### Initializer ```typescript import { RunnerRuntimeParameters } from '@cloudsnorkel/cdk-github-runners' const runnerRuntimeParameters: RunnerRuntimeParameters = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | githubDomainPath | string | Path to GitHub domain. | | 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. --- ##### `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. --- ### 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) --- ## 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. --- ### 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. | | WINDOWS | Os | Windows. | --- ##### ~~`LINUX`~~^Required - *Deprecated:* use {@link LINUX_UBUNTU } or {@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. --- ##### `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. | | 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 the GitHub CLI. | | 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() ``` A component to install the AWS CLI. ##### `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() ``` 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). ##### ~~`dockerInDocker`~~ ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.dockerInDocker() ``` A component to install Docker-in-Docker. ##### `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. --- ###### `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() ``` A component to install the GitHub CLI. ##### `githubCli` ```typescript import { RunnerImageComponent } from '@cloudsnorkel/cdk-github-runners' RunnerImageComponent.githubCli() ``` A component to install the GitHub CLI. ##### `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 ### 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}. #### 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. | --- ##### `getStepFunctionTask` ```typescript public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable ``` Generate step function tasks that execute the runner. Called by GithubRunners and shouldn't be called manually. ###### `parameters`^Required - *Type:* RunnerRuntimeParameters 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. --- #### 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. | | 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. --- ##### `image`^Optional ```typescript public readonly image: IRunnerImageStatus; ``` - *Type:* IRunnerImageStatus Details about Docker image used by this runner provider. --- ##### `logGroup`^Optional ```typescript public readonly logGroup: string; ``` - *Type:* string Log group for runners. --- ##### `roleArn`^Optional ```typescript public readonly roleArn: string; ``` - *Type:* string Role attached to runners. --- ##### `securityGroups`^Optional ```typescript public readonly securityGroups: string[]; ``` - *Type:* string[] Security groups attached to runners. --- ##### `vpcArn`^Optional ```typescript public readonly vpcArn: string; ``` - *Type:* string VPC where runners will be launched. --- ## Enums ### RunnerImageBuilderType #### Members | **Name** | **Description** | | --- | --- | | CODE_BUILD | Build runner images using AWS CodeBuild. | | AWS_IMAGE_BUILDER | Build runner images using AWS Image Builder. | --- ##### `CODE_BUILD` Build runner images using AWS CodeBuild. Faster than AWS Image Builder, but can only be used to build Linux Docker images. --- ##### `AWS_IMAGE_BUILDER` Build runner images using AWS Image Builder. Slower than CodeBuild, but can be used to build any type of image including AMIs and Windows images. ---