Skip to content

Latest commit

 

History

History
3936 lines (2403 loc) · 142 KB

API.md

File metadata and controls

3936 lines (2403 loc) · 142 KB
Raw

API Reference

Constructs

CodeBuildImageBuilder

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: FargateProvider.LINUX_X64_DOCKERFILE_PATH,
     runnerVersion: RunnerVersion.specific('2.293.0'),
     rebuildInterval: Duration.days(14),
});
builder.setBuildArg('EXTRA_PACKAGES', 'nginx xz-utils');
new FargateRunner(this, 'Fargate provider', {
     label: 'customized-fargate',
     imageBuilder: builder,
});

Initializers 

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.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

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.
bind Called by IRunnerProvider to finalize settings and create the image builder.
setBuildArg Adds a build argument for Docker.
toString 
public toString(): string

Returns a string representation of this construct.

addExtraCertificates 
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.

pathRequired
  • Type: string

path to directory containing a file called certs.pem containing all the required certificates.

addFiles 
public addFiles(sourcePath: string, destName: string): void

Uploads a folder to the build server at a given folder name.

sourcePathRequired
  • Type: string

path to source directory.

destNameRequired
  • Type: string

name of destination folder.

addPolicyStatement 
public addPolicyStatement(statement: PolicyStatement): void

Add a policy statement to the builder to access resources required to the image build.

statementRequired
  • Type: aws-cdk-lib.aws_iam.PolicyStatement

IAM policy statement.

addPostBuildCommand 
public addPostBuildCommand(command: string): void

Adds a command that runs after docker build and docker push.

commandRequired
  • Type: string

command to add.

addPreBuildCommand 
public addPreBuildCommand(command: string): void

Adds a command that runs before docker build.

commandRequired
  • Type: string

command to add.

bind 
public bind(): RunnerImage

Called by IRunnerProvider to finalize settings and create the image builder.

setBuildArg 
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.

nameRequired
  • Type: string

build argument name.

valueRequired
  • Type: string

build argument value.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { CodeBuildImageBuilder } from '@cloudsnorkel/cdk-github-runners'

CodeBuildImageBuilder.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
props CodeBuildImageBuilderProps No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

propsRequired 
public readonly props: CodeBuildImageBuilderProps;

CodeBuildRunner

GitHub Actions runner provider using CodeBuild to execute the actions.

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 

import { CodeBuildRunner } from '@cloudsnorkel/cdk-github-runners'

new CodeBuildRunner(scope: Construct, id: string, props: CodeBuildRunnerProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props CodeBuildRunnerProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
getStepFunctionTask Generate step function task(s) to start a new runner.
toString 
public toString(): string

Returns a string representation of this construct.

getStepFunctionTask 
public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable

Generate step function task(s) to start a new runner.

Called by GithubRunners and shouldn't be called manually.

parametersRequired

workflow job details.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { CodeBuildRunner } from '@cloudsnorkel/cdk-github-runners'

CodeBuildRunner.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • 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.
grantPrincipal aws-cdk-lib.aws_iam.IPrincipal Grant principal used to add permissions to the runner role.
image RunnerImage Docker image in CodeBuild project.
label string Label associated with this provider.
project aws-cdk-lib.aws_codebuild.Project CodeBuild project hosting the runner.
securityGroup aws-cdk-lib.aws_ec2.ISecurityGroup Security group attached to the task.
vpc aws-cdk-lib.aws_ec2.IVpc VPC used for hosting the project.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

connectionsRequired 
public readonly connections: Connections;
  • Type: aws-cdk-lib.aws_ec2.Connections

The network connections associated with this resource.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

Grant principal used to add permissions to the runner role.

imageRequired 
public readonly image: RunnerImage;

Docker image in CodeBuild project.

labelRequired 
public readonly label: string;
  • Type: string

Label associated with this provider.

projectRequired 
public readonly project: Project;
  • Type: aws-cdk-lib.aws_codebuild.Project

CodeBuild project hosting the runner.

securityGroupOptional 
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup

Security group attached to the task.

vpcOptional 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

VPC used for hosting the project.

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_PATHRequired 
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 "stsable".
  • 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_PATHRequired 
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 "stsable".
  • 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

An image builder that uses 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 CodeBuildRunner(this, 'CodeBuild provider', {
     label: 'windows-codebuild',
     imageBuilder: builder,
});

Initializers 

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.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsOptional

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.
bind Called by IRunnerProvider to finalize settings and create the image builder.
prependComponent Add a component to be installed before any other components.
toString 
public toString(): string

Returns a string representation of this construct.

addComponent 
public addComponent(component: ImageBuilderComponent): void

Add a component to be installed.

componentRequired
addExtraCertificates 
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.

pathRequired
  • Type: string

path to directory containing a file called certs.pem containing all the required certificates.

bind 
public bind(): RunnerImage

Called by IRunnerProvider to finalize settings and create the image builder.

prependComponent 
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.

componentRequired

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { ContainerImageBuilder } from '@cloudsnorkel/cdk-github-runners'

ContainerImageBuilder.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
architecture Architecture No description.
description string No description.
instanceTypes string[] No description.
logRemovalPolicy aws-cdk-lib.RemovalPolicy No description.
logRetention aws-cdk-lib.aws_logs.RetentionDays No description.
os Os No description.
platform string No description.
rebuildInterval aws-cdk-lib.Duration No description.
repository aws-cdk-lib.aws_ecr.IRepository No description.
runnerVersion RunnerVersion No description.
securityGroupIds string[] No description.
subnetId string No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

architectureRequired 
public readonly architecture: Architecture;
descriptionRequired 
public readonly description: string;
  • Type: string
instanceTypesRequired 
public readonly instanceTypes: string[];
  • Type: string[]
logRemovalPolicyRequired 
public readonly logRemovalPolicy: RemovalPolicy;
  • Type: aws-cdk-lib.RemovalPolicy
logRetentionRequired 
public readonly logRetention: RetentionDays;
  • Type: aws-cdk-lib.aws_logs.RetentionDays
osRequired 
public readonly os: Os;
  • Type: Os
platformRequired 
public readonly platform: string;
  • Type: string
rebuildIntervalRequired 
public readonly rebuildInterval: Duration;
  • Type: aws-cdk-lib.Duration
repositoryRequired 
public readonly repository: IRepository;
  • Type: aws-cdk-lib.aws_ecr.IRepository
runnerVersionRequired 
public readonly runnerVersion: RunnerVersion;
securityGroupIdsOptional 
public readonly securityGroupIds: string[];
  • Type: string[]
subnetIdOptional 
public readonly subnetId: string;
  • Type: string

FargateRunner

GitHub Actions runner provider using Fargate to execute the actions.

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 

import { FargateRunner } from '@cloudsnorkel/cdk-github-runners'

new FargateRunner(scope: Construct, id: string, props: FargateRunnerProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props FargateRunnerProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
getStepFunctionTask Generate step function task(s) to start a new runner.
toString 
public toString(): string

Returns a string representation of this construct.

getStepFunctionTask 
public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable

Generate step function task(s) to start a new runner.

Called by GithubRunners and shouldn't be called manually.

parametersRequired

workflow job details.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { FargateRunner } from '@cloudsnorkel/cdk-github-runners'

FargateRunner.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
assignPublicIp boolean Whether 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 used to start a new Fargate task.
label string Label associated with this provider.
spot boolean Use spot pricing for Fargate tasks.
task aws-cdk-lib.aws_ecs.FargateTaskDefinition Fargate task hosting the runner.
securityGroup aws-cdk-lib.aws_ec2.ISecurityGroup Security group attached to the task.
vpc aws-cdk-lib.aws_ec2.IVpc VPC used for hosting the task.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

assignPublicIpRequired 
public readonly assignPublicIp: boolean;
  • Type: boolean

Whether task will have a public IP.

clusterRequired 
public readonly cluster: Cluster;
  • Type: aws-cdk-lib.aws_ecs.Cluster

Cluster hosting the task hosting the runner.

connectionsRequired 
public readonly connections: Connections;
  • Type: aws-cdk-lib.aws_ec2.Connections

The network connections associated with this resource.

containerRequired 
public readonly container: ContainerDefinition;
  • Type: aws-cdk-lib.aws_ecs.ContainerDefinition

Container definition hosting the runner.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

Grant principal used to add permissions to the runner role.

imageRequired 
public readonly image: RunnerImage;

Docker image used to start a new Fargate task.

labelRequired 
public readonly label: string;
  • Type: string

Label associated with this provider.

spotRequired 
public readonly spot: boolean;
  • Type: boolean

Use spot pricing for Fargate tasks.

taskRequired 
public readonly task: FargateTaskDefinition;
  • Type: aws-cdk-lib.aws_ecs.FargateTaskDefinition

Fargate task hosting the runner.

securityGroupOptional 
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup

Security group attached to the task.

vpcOptional 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

VPC used for hosting the 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_PATHRequired 
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_PATHRequired 
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

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.

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.

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 CodeBuildRunner(
   this, 'codebuild runner',
   {
      label: 'my-codebuild',
      vpc: vpc,
      securityGroup: 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 

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.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsOptional

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { GitHubRunners } from '@cloudsnorkel/cdk-github-runners'

GitHubRunners.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
providers IRunnerProvider[] Configured runner providers.
secrets Secrets Secrets for GitHub communication including webhook secret and runner authentication.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

providersRequired 
public readonly providers: IRunnerProvider[];

Configured runner providers.

secretsRequired 
public readonly secrets: Secrets;

Secrets for GitHub communication including webhook secret and runner authentication.

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: [
     '$ErrorActionPreference = \'Stop\'',
     'Start-Process msiexec.exe -Wait -ArgumentList \'/i https://awscli.amazonaws.com/AWSCLIV2.msi /qn\'',
   ],
}

Initializers 

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.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

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.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
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).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
grantAssetsRead 
public grantAssetsRead(grantee: IGrantable): void

Grants read permissions to the principal on the assets buckets.

granteeRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable

Static Functions

Name Description
isConstruct Checks if x is a construct.
isResource Check whether the given construct is a Resource.
isConstruct 
import { ImageBuilderComponent } from '@cloudsnorkel/cdk-github-runners'

ImageBuilderComponent.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

isResource 
import { ImageBuilderComponent } from '@cloudsnorkel/cdk-github-runners'

ImageBuilderComponent.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • 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.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
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.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

arnRequired 
public readonly arn: string;
  • Type: string

Component ARN.

platformRequired 
public readonly platform: string;
  • Type: string

Supported platform for the component.

LambdaRunner

GitHub Actions runner provider using Lambda to execute the actions.

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 

import { LambdaRunner } from '@cloudsnorkel/cdk-github-runners'

new LambdaRunner(scope: Construct, id: string, props: LambdaRunnerProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props LambdaRunnerProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
getStepFunctionTask Generate step function task(s) to start a new runner.
toString 
public toString(): string

Returns a string representation of this construct.

getStepFunctionTask 
public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable

Generate step function task(s) to start a new runner.

Called by GithubRunners and shouldn't be called manually.

parametersRequired

workflow job details.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { LambdaRunner } from '@cloudsnorkel/cdk-github-runners'

LambdaRunner.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • 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.
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 used to start Lambda function.
label string Label associated with this provider.
securityGroup aws-cdk-lib.aws_ec2.ISecurityGroup Security group attached to the function.
vpc aws-cdk-lib.aws_ec2.IVpc VPC used for hosting the function.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

connectionsRequired 
public readonly connections: Connections;
  • Type: aws-cdk-lib.aws_ec2.Connections

The network connections associated with this resource.

functionRequired 
public readonly function: Function;
  • Type: aws-cdk-lib.aws_lambda.Function

The function hosting the GitHub runner.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

Grant principal used to add permissions to the runner role.

imageRequired 
public readonly image: RunnerImage;

Docker image used to start Lambda function.

labelRequired 
public readonly label: string;
  • Type: string

Label associated with this provider.

securityGroupOptional 
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup

Security group attached to the function.

vpcOptional 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

VPC used for hosting the function.

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_PATHRequired 
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_PATHRequired 
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.

Secrets

Secrets required for GitHub runners operation.

Initializers 

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.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { Secrets } from '@cloudsnorkel/cdk-github-runners'

Secrets.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • 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 authentication token.
githubPrivateKey aws-cdk-lib.aws_secretsmanager.Secret GitHub app private key. Not needed when using personal authentication 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.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

githubRequired 
public readonly github: Secret;
  • Type: aws-cdk-lib.aws_secretsmanager.Secret

Authentication secret for GitHub containing either app details or personal authentication 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.

githubPrivateKeyRequired 
public readonly githubPrivateKey: Secret;
  • Type: aws-cdk-lib.aws_secretsmanager.Secret

GitHub app private key. Not needed when using personal authentication 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.

setupRequired 
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.

webhookRequired 
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

CodeBuildImageBuilderProps

Properties for CodeBuildImageBuilder construct.

Initializer 

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.
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.
dockerfilePathRequired 
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.

architectureOptional 
public readonly architecture: Architecture;

Image architecture.

computeTypeOptional 
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.

logRemovalPolicyOptional 
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.

logRetentionOptional 
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.

osOptional 
public readonly os: Os;
  • Type: Os
  • Default: OS.LINUX

Image OS.

rebuildIntervalOptional 
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.

runnerVersionOptional 
public readonly runnerVersion: RunnerVersion;

Version of GitHub Runners to install.

securityGroupOptional 
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.

subnetSelectionOptional 
public readonly subnetSelection: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
  • Default: no subnet

Where to place the network interfaces within the VPC.

timeoutOptional 
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.

vpcOptional 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc
  • Default: no VPC

VPC to build the image in.

CodeBuildRunnerProps

Initializer 

import { CodeBuildRunnerProps } from '@cloudsnorkel/cdk-github-runners'

const codeBuildRunnerProps: CodeBuildRunnerProps = { ... }

Properties

Name Type Description
logRetention aws-cdk-lib.aws_logs.RetentionDays The number of days log events are kept in CloudWatch Logs.
computeType aws-cdk-lib.aws_codebuild.ComputeType The type of compute to use for this build.
imageBuilder IImageBuilder Provider running an image to run inside CodeBuild with GitHub runner pre-configured.
label string GitHub Actions label used for this provider.
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 launch the runners in.
logRetentionOptional 
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.

computeTypeOptional 
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.

imageBuilderOptional 
public readonly imageBuilder: IImageBuilder;
  • Type: IImageBuilder
  • Default: image builder with CodeBuildRunner.LINUX_X64_DOCKERFILE_PATH as Dockerfile

Provider running an image to run inside CodeBuild with GitHub runner pre-configured.

A user named runner is expected to exist with access to Docker-in-Docker.

labelOptional 
public readonly label: string;
  • Type: string
  • Default: 'codebuild'

GitHub Actions label used for this provider.

securityGroupOptional 
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.

subnetSelectionOptional 
public readonly subnetSelection: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
  • Default: no subnet

Where to place the network interfaces within the VPC.

timeoutOptional 
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.

vpcOptional 
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 

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.
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.
vpc aws-cdk-lib.aws_ec2.IVpc VPC to launch the runners in.
architectureOptional 
public readonly architecture: Architecture;

Image architecture.

instanceTypeOptional 
public readonly instanceType: InstanceType;
  • Type: aws-cdk-lib.aws_ec2.InstanceType
  • Default: m5.large

The instance type used to build the image.

logRemovalPolicyOptional 
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.

logRetentionOptional 
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.

osOptional 
public readonly os: Os;
  • Type: Os
  • Default: OS.LINUX

Image OS.

rebuildIntervalOptional 
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.

runnerVersionOptional 
public readonly runnerVersion: RunnerVersion;

Version of GitHub Runners to install.

securityGroupOptional 
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup
  • Default: default account security group

Security Group to assign to this instance.

subnetSelectionOptional 
public readonly subnetSelection: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
  • Default: default VPC subnet

Where to place the network interfaces within the VPC.

vpcOptional 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc
  • Default: default account VPC

VPC to launch the runners in.

FargateRunnerProps

Properties for FargateRunner.

Initializer 

import { FargateRunnerProps } from '@cloudsnorkel/cdk-github-runners'

const fargateRunnerProps: FargateRunnerProps = { ... }

Properties

Name Type Description
logRetention aws-cdk-lib.aws_logs.RetentionDays The number of days log events are kept in CloudWatch Logs.
assignPublicIp boolean Assign public IP to the runner task.
cluster aws-cdk-lib.aws_ecs.Cluster Existing Fargate cluster to use.
cpu number The number of cpu units used by the task.
ephemeralStorageGiB number The amount (in GiB) of ephemeral storage to be allocated to the task.
imageBuilder IImageBuilder Provider running an image to run inside CodeBuild with GitHub runner pre-configured.
label string GitHub Actions label 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.
spot boolean Use Fargate spot capacity provider to save money.
vpc aws-cdk-lib.aws_ec2.IVpc VPC to launch the runners in.
logRetentionOptional 
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.

assignPublicIpOptional 
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.

clusterOptional 
public readonly cluster: Cluster;
  • Type: aws-cdk-lib.aws_ecs.Cluster
  • Default: a new cluster

Existing Fargate cluster to use.

cpuOptional 
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)

ephemeralStorageGiBOptional 
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.

imageBuilderOptional 
public readonly imageBuilder: IImageBuilder;
  • Type: IImageBuilder
  • Default: image builder with FargateRunner.LINUX_X64_DOCKERFILE_PATH as Dockerfile

Provider running an image to run inside CodeBuild with GitHub runner pre-configured.

A user named runner is expected to exist.

The entry point should start GitHub runner. For example:

#!/bin/bash
set -e -u -o pipefail

/home/runner/config.sh --unattended --url "https://${GITHUB_DOMAIN}/${OWNER}/${REPO}" --token "${RUNNER_TOKEN}" --ephemeral --work _work --labels "${RUNNER_LABEL}" --disableupdate --name "${RUNNER_NAME}"
/home/runner/run.sh
labelOptional 
public readonly label: string;
  • Type: string
  • Default: 'fargate'

GitHub Actions label used for this provider.

memoryLimitMiBOptional 
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)

securityGroupOptional 
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup
  • Default: a new security group

Security Group to assign to the task.

spotOptional 
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.
vpcOptional 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc
  • Default: default account VPC

VPC to launch the runners in.

GitHubRunnersProps

Properties for GitHubRunners.

Initializer 

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.
providers IRunnerProvider[] List of runner providers to use.
securityGroup aws-cdk-lib.aws_ec2.ISecurityGroup Security group attached to all management functions.
vpc aws-cdk-lib.aws_ec2.IVpc VPC used for all management functions.
vpcSubnets aws-cdk-lib.aws_ec2.SubnetSelection VPC subnets used for all management functions.
allowPublicSubnetOptional 
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.

extraCertificatesOptional 
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}.

const imageBuilder = new CodeBuildImageBuilder(this, 'Image Builder with Certs', {
     dockerfilePath: CodeBuildRunner.LINUX_X64_DOCKERFILE_PATH,
});
imageBuilder.addExtraCertificates('path-to-my-extra-certs-folder');

const provider = new CodeBuildRunner(this, 'CodeBuild', {
     imageBuilder: imageBuilder,
});

new GitHubRunners(
   this,
   'runners',
   {
     providers: [provider],
     extraCertificates: 'path-to-my-extra-certs-folder',
   }
);
providersOptional 
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.

securityGroupOptional 
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.

vpcOptional 
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.

vpcSubnetsOptional 
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.

ImageBuilderAsset

An asset including file or directory to place inside the built image.

Initializer 

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.
assetRequired 
public readonly asset: Asset;
  • Type: aws-cdk-lib.aws_s3_assets.Asset

Asset to place in the image.

pathRequired 
public readonly path: string;
  • Type: string

Path to place asset in the image.

ImageBuilderComponentProperties

Properties for ImageBuilderComponent construct.

Initializer 

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.
commandsRequired 
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.

descriptionRequired 
public readonly description: string;
  • Type: string

Component description.

displayNameRequired 
public readonly displayName: string;
  • Type: string

Component display name.

platformRequired 
public readonly platform: string;
  • Type: string

Component platform.

Must match the builder platform.

assetsOptional 
public readonly assets: ImageBuilderAsset[];

Optional assets to add to the built image.

LambdaRunnerProps

Initializer 

import { LambdaRunnerProps } from '@cloudsnorkel/cdk-github-runners'

const lambdaRunnerProps: LambdaRunnerProps = { ... }

Properties

Name Type Description
logRetention aws-cdk-lib.aws_logs.RetentionDays The number of days log events are kept in CloudWatch Logs.
ephemeralStorageSize aws-cdk-lib.Size The size of the function’s /tmp directory in MiB.
imageBuilder IImageBuilder Provider running an image to run inside CodeBuild with GitHub runner pre-configured.
label string GitHub Actions label 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.
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.
logRetentionOptional 
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.

ephemeralStorageSizeOptional 
public readonly ephemeralStorageSize: Size;
  • Type: aws-cdk-lib.Size
  • Default: 10 GiB

The size of the function’s /tmp directory in MiB.

imageBuilderOptional 
public readonly imageBuilder: IImageBuilder;
  • Type: IImageBuilder
  • Default: image builder with LambdaRunner.LINUX_X64_DOCKERFILE_PATH as Dockerfile

Provider running an image to run inside CodeBuild with GitHub runner pre-configured.

The default command (CMD) should be ["runner.handler"] which points to an included runner.js with a function named handler. The function should start the GitHub runner.

https://github.com/CloudSnorkel/cdk-github-runners/tree/main/src/providers/docker-images/lambda

labelOptional 
public readonly label: string;
  • Type: string
  • Default: 'lambda'

GitHub Actions label used for this provider.

memorySizeOptional 
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.

securityGroupOptional 
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.

subnetSelectionOptional 
public readonly subnetSelection: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
  • Default: no subnet

Where to place the network interfaces within the VPC.

timeoutOptional 
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.

vpcOptional 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc
  • Default: no VPC

VPC to launch the runners in.

RunnerImage

Initializer 

import { RunnerImage } from '@cloudsnorkel/cdk-github-runners'

const runnerImage: RunnerImage = { ... }

Properties

Name Type Description
architecture Architecture Architecture of the image.
imageRepository aws-cdk-lib.aws_ecr.IRepository ECR repository containing the image.
imageTag string Static image tag where the image will be pushed.
os Os OS type of the image.
logGroup aws-cdk-lib.aws_logs.LogGroup Log group where image builds are logged.
architectureRequired 
public readonly architecture: Architecture;

Architecture of the image.

imageRepositoryRequired 
public readonly imageRepository: IRepository;
  • Type: aws-cdk-lib.aws_ecr.IRepository

ECR repository containing the image.

imageTagRequired 
public readonly imageTag: string;
  • Type: string

Static image tag where the image will be pushed.

osRequired 
public readonly os: Os;
  • Type: Os

OS type of the image.

logGroupOptional 
public readonly logGroup: LogGroup;
  • Type: aws-cdk-lib.aws_logs.LogGroup

Log group where image builds are logged.

RunnerProviderProps

Common properties for all runner providers.

Initializer 

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.
logRetentionOptional 
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.

RunnerRuntimeParameters

Workflow job parameters as parsed from the webhook event. Pass these into your runner executor and run something like:.

./config.sh --unattended --url "https://${GITHUB_DOMAIN}/${OWNER}/${REPO}" --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 

import { RunnerRuntimeParameters } from '@cloudsnorkel/cdk-github-runners'

const runnerRuntimeParameters: RunnerRuntimeParameters = { ... }

Properties

Name Type Description
githubDomainPath string Path to GitHub domain.
ownerPath string Path to repostiroy owner name.
repoPath string Path to repository name.
runnerNamePath string Path to desired runner name.
runnerTokenPath string Path to runner token used to register token.
githubDomainPathRequired 
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.

ownerPathRequired 
public readonly ownerPath: string;
  • Type: string

Path to repostiroy owner name.

repoPathRequired 
public readonly repoPath: string;
  • Type: string

Path to repository name.

runnerNamePathRequired 
public readonly runnerNamePath: string;
  • Type: string

Path to desired runner name.

We specifically set the name to make troubleshooting easier.

runnerTokenPathRequired 
public readonly runnerTokenPath: string;
  • Type: string

Path to runner token used to register token.

Classes

Architecture

CPU architecture enum for an image.

Methods

Name Description
is Checks if the given architecture is the same as this one.
is 
public is(arch: Architecture): boolean

Checks if the given architecture is the same as this one.

archRequired

architecture to compare.

Properties

Name Type Description
name string No description.
nameRequired 
public readonly name: string;
  • Type: string

Constants

Name Type Description
ARM64 Architecture ARM64.
X86_64 Architecture X86_64.
ARM64Required 
public readonly ARM64: Architecture;

ARM64.

X86_64Required 
public readonly X86_64: Architecture;

X86_64.

Os

OS enum for an image.

Methods

Name Description
is Checks if the given OS is the same as this one.
is 
public is(os: Os): boolean

Checks if the given OS is the same as this one.

osRequired
  • Type: Os

OS to compare.

Properties

Name Type Description
name string No description.
nameRequired 
public readonly name: string;
  • Type: string

Constants

Name Type Description
LINUX Os Linux.
WINDOWS Os Windows.
LINUXRequired 
public readonly LINUX: Os;
  • Type: Os

Linux.

WINDOWSRequired 
public readonly WINDOWS: Os;
  • Type: Os

Windows.

RunnerVersion

Defines desired GitHub Actions runner version.

Initializers 

import { RunnerVersion } from '@cloudsnorkel/cdk-github-runners'

new RunnerVersion(version: string)
Name Type Description
version string No description.
versionRequired
  • Type: string

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 
import { RunnerVersion } from '@cloudsnorkel/cdk-github-runners'

RunnerVersion.latest()

Use the latest version available at the time the runner provider image is built.

specific 
import { RunnerVersion } from '@cloudsnorkel/cdk-github-runners'

RunnerVersion.specific(version: string)

Use a specific version.

https://github.com/actions/runner/releases

versionRequired
  • Type: string

GitHub Runner version.

Properties

Name Type Description
version string No description.
versionRequired 
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 

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 
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.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
imageRequired
  • Type: string

Docker Hub image with optional tag.

architectureOptional

image architecture.

osOptional
  • Type: Os

image OS.

fromEcrRepository 
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.

repositoryRequired
  • Type: aws-cdk-lib.aws_ecr.IRepository

ECR repository.

tagOptional
  • Type: string

image tag.

architectureOptional

image architecture.

osOptional
  • Type: Os

image OS.

Protocols

IImageBuilder

Interface for constructs that build an image that can be used in {@link IRunnerProvider}.

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.

Methods

Name Description
bind ECR repository containing the image.
bind 
public bind(): RunnerImage

ECR repository containing the image.

This method can be called multiple times if the image is bound to multiple providers. Make sure you cache the image when implementing or return an error if this builder doesn't support reusing images.

IRunnerImageStatus

Interface for runner image status used by status.json.

Properties

Name Type Description
imageBuilderLogGroup string Log group name for the image builder where history of image builds can be analyzed.
imageRepository string Image repository where runner image is pushed.
imageTag string Tag of image that should be used.
imageBuilderLogGroupOptional 
public readonly imageBuilderLogGroup: string;
  • Type: string

Log group name for the image builder where history of image builds can be analyzed.

imageRepositoryOptional 
public readonly imageRepository: string;
  • Type: string

Image repository where runner image is pushed.

imageTagOptional 
public readonly imageTag: string;
  • Type: string

Tag of image that should be used.

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.
getStepFunctionTask 
public getStepFunctionTask(parameters: RunnerRuntimeParameters): IChainable

Generate step function tasks that execute the runner.

Called by GithubRunners and shouldn't be called manually.

parametersRequired

specific build parameters.

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.
image RunnerImage Image used to create a new resource compute.
label string GitHub Actions label associated with this runner provider.
securityGroup aws-cdk-lib.aws_ec2.ISecurityGroup Security group associated with runners.
vpc aws-cdk-lib.aws_ec2.IVpc VPC network in which runners will be placed.
connectionsRequired 
public readonly connections: Connections;
  • Type: aws-cdk-lib.aws_ec2.Connections

The network connections associated with this resource.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

The principal to grant permissions to.

imageRequired 
public readonly image: RunnerImage;

Image used to create a new resource compute.

Can be Docker image, AMI, or something else.

labelRequired 
public readonly label: string;
  • Type: string

GitHub Actions label associated with this runner provider.

securityGroupOptional 
public readonly securityGroup: ISecurityGroup;
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup

Security group associated with runners.

vpcOptional 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

VPC network in which runners will be placed.