Skip to content

Latest commit

 

History

History
1867 lines (1139 loc) · 65.9 KB

API.md

File metadata and controls

1867 lines (1139 loc) · 65.9 KB
Raw

API Reference

Constructs

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

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.

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.
label string Label associated with this provider.
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.

labelRequired 
public readonly label: string;
  • Type: string

Label associated with this provider.

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.

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(stack, '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(stack, 'vpc', { vpcId: 'vpc-1234567' });
const runnerSg = new ec2.SecurityGroup(stack, 'runner security group', { vpc: vpc });
const dbSg = ec2.SecurityGroup.fromSecurityGroupId(stack, 'database security group', 'sg-1234567');
const bucket = new s3.Bucket(stack, 'runner bucket');

// create a custom CodeBuild provider
const myProvider = new CodeBuildRunner(
   stack, '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(
   stack,
   'runners',
   {
     providers: [myProvider],
     defaultProviderLabel: 'my-codebuild',
   }
);

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
propsRequired

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.
defaultProvider IRunnerProvider Default provider as set by {@link GitHubRunnersProps.defaultProviderLabel}.
props GitHubRunnersProps No description.
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.

defaultProviderRequired 
public readonly defaultProvider: IRunnerProvider;

Default provider as set by {@link GitHubRunnersProps.defaultProviderLabel}.

propsRequired 
public readonly props: GitHubRunnersProps;
providersRequired 
public readonly providers: IRunnerProvider[];

Configured runner providers.

secretsRequired 
public readonly secrets: Secrets;

Secrets for GitHub communication including webhook secret and runner authentication.

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

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.

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

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

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.
runnerVersion RunnerVersion Version of GitHub Runners to install.
computeType aws-cdk-lib.aws_codebuild.ComputeType The type of compute to use for this build.
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.

runnerVersionOptional 
public readonly runnerVersion: RunnerVersion;

Version of GitHub Runners to install.

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.

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.

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.
runnerVersion RunnerVersion Version of GitHub Runners to install.
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.
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.
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.

runnerVersionOptional 
public readonly runnerVersion: RunnerVersion;

Version of GitHub Runners to install.

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.

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.

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
defaultProviderLabel string Label of default provider in case the workflow job doesn't specify any known label.
providers IRunnerProvider[] List of runner providers to use.
defaultProviderLabelOptional 
public readonly defaultProviderLabel: string;
  • Type: string
  • Default: 'codebuild'

Label of default provider in case the workflow job doesn't specify any known label.

A provider with that label must be configured.

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.

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.
runnerVersion RunnerVersion Version of GitHub Runners to install.
ephemeralStorageSize aws-cdk-lib.Size The size of the function’s /tmp directory in MiB.
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.

runnerVersionOptional 
public readonly runnerVersion: RunnerVersion;

Version of GitHub Runners to install.

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

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

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.

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.
runnerVersion RunnerVersion Version of GitHub Runners to install.
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.

runnerVersionOptional 
public readonly runnerVersion: RunnerVersion;

Version of GitHub Runners to install.

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

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

Protocols

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

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.