Package: cloudsnorkel.cdk-github-runners
GitHub Self-Hosted Runners CDK ConstructsUse this CDK construct to create ephemeralself-hosted GitHub runnerson-demand inside your AWS account.Easy to configure GitHub integration with a web-based interfaceCustomizable runners with decent defaultsMultiple runner configurations controlled by labelsEverything fully hosted in your accountAutomatically updated build environment with latest runner versionSelf-hosted runners in AWS are useful when:You need easy access to internal resources in your actionsYou want to pre-install some software for your actionsYou want to provide some basic AWS API access (butaws-actions/configure-aws-credentialshas more security controls)You are using GitHub Enterprise ServerEphemeral (or on-demand) runners are therecommended way by GitHubfor auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.APIThe best way to browse API documentation is onConstructs Hub. It is available in all supported programming languages.ProvidersA runner provider creates compute resources on-demand and usesactions/runnerto start a runner.EC2CodeBuildFargateECSLambdaTime limitUnlimited8 hoursUnlimitedUnlimited15 minutesvCPUsUnlimited2, 4, 8, or 720.25 to 4Unlimited1 to 6RAMUnlimited3gb, 7gb, 15gb, or 145gb512mb to 30gbUnlimited128mb to 10gbStorageUnlimited50gb to 824gb20gb to 200gbUnlimitedUp to 10gbArchitecturex86_64, ARM64x86_64, ARM64x86_64, ARM64x86_64, ARM64x86_64, ARM64sudo✔✔✔✔❌Docker✔✔ (Linux only)❌✔❌Spot pricing✔❌✔✔❌OSLinux, WindowsLinux, WindowsLinux, WindowsLinux, WindowsLinuxThe best provider to use mostly depends on your current infrastructure. When in doubt, CodeBuild is always a good choice. Execution history and logs are easy to view, and it has no restrictive limits unless you need to run for more than 8 hours.EC2 is useful when you want runners to have complete access to the hostECS is useful when you want to control the infrastructure, like leaving the runner host running for faster startupsLambda is useful for short jobs that can work within time, size and readonly system constraintsYou can also create your own provider by implementingIRunnerProvider.InstallationInstall and use the appropriate packagePythonInstallAvailable onPyPI.pipinstallcloudsnorkel.cdk-github-runnersUsefromcloudsnorkel.cdk_github_runnersimportGitHubRunnersGitHubRunners(self,"runners")TypeScript or JavaScriptInstallAvailable onnpm.npmi@cloudsnorkel/cdk-github-runnersUseimport{GitHubRunners}from'@cloudsnorkel/cdk-github-runners';newGitHubRunners(this,"runners");JavaInstallAvailable onMaven.<dependency><groupId>com.cloudsnorkel</groupId><artifactId>cdk.github.runners</artifactId></dependency>Useimportcom.cloudsnorkel.cdk.github.runners.GitHubRunners;GitHubRunners.Builder.create(this,"runners").build();GoInstallAvailable onGitHub.gogetgithub.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunnersUseimport"github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners"NewGitHubRunners(this,jsii.String("runners")).NETInstallAvailable onNuget.dotnetaddpackageCloudSnorkel.Cdk.Github.RunnersUseusingCloudSnorkel;newGitHubRunners(this,"runners");UseGitHubRunnersconstruct in your code (starting with default arguments is fine)Deploy your stackLook for the status command output similar toaws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json✅  github-runners-test

✨  Deployment time: 260.01s

Outputs:
github-runners-test.runnersstatuscommand4A30F0F5 = aws --region us-east-1 lambda invoke --function-name github-runners-test-runnersstatus1A5771C0-mvttg8oPQnQS status.jsonExecute the status command (you may need to specify--profiletoo) and open the resultingstatus.jsonfileOpen the URL ingithub.setup.urlfromstatus.jsonormanually setup GitHubintegration as an app or with personal access tokenRun status command again to confirmgithub.auth.statusandgithub.webhook.statusare OKTrigger a GitHub action that has aself-hostedlabel withruns-on: [self-hosted, linux, codebuild]or similarIf the action is not successful, seetroubleshootingCustomizingThe default providers configured byGitHubRunnersare useful for testing but probably not too much for actual production work. They run in the default VPC or no VPC and have no added IAM permissions. You would usually want to configure the providers yourself.For example:letvpc:ec2.Vpc;letrunnerSg:ec2.SecurityGroup;letdbSg:ec2.SecurityGroup;letbucket:s3.Bucket;//createacustomCodeBuildproviderconstmyProvider=newCodeBuildRunnerProvider(this,'codebuild runner',{labels:['my-codebuild'],vpc:vpc,securityGroups:[runnerSg],});//grantsomepermissionstotheproviderbucket.grantReadWrite(myProvider);dbSg.connections.allowFrom(runnerSg,ec2.Port.tcp(3306),'allow runners to connect to MySQL database');//createtherunnerinfrastructurenewGitHubRunners(this,'runners',{providers:[myProvider],});Another way to customize runners is by modifying the image used to spin them up. The image contains therunner, any required dependencies, and integration code with the provider. You may choose to customize this image by adding more packages, for example.constmyBuilder=FargateRunnerProvider.imageBuilder(this,'image builder');myBuilder.addComponent(RunnerImageComponent.custom({commands:['apt install -y nginx xz-utils']}),);constmyProvider=newFargateRunnerProvider(this,'fargate runner',{labels:['customized-fargate'],imageBuilder:myBuilder,});//createtherunnerinfrastructurenewGitHubRunners(this,'runners',{providers:[myProvider],});Your workflow will then look like:name:self-hosted exampleon:pushjobs:self-hosted:runs-on:[self-hosted,customized-fargate]steps:-run:echo hello worldWindows images can also be customized the same way.constmyWindowsBuilder=FargateRunnerProvider.imageBuilder(this,'Windows image builder',{architecture:Architecture.X86_64,os:Os.WINDOWS,});myWindowsBuilder.addComponent(RunnerImageComponent.custom({name:'Ninja',commands:['Invoke-WebRequest -UseBasicParsing -Uri "https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-win.zip" -OutFile ninja.zip','Expand-Archive ninja.zip -DestinationPath C:\\actions','del ninja.zip',],}),);constmyProvider=newFargateRunnerProvider(this,'fargate runner',{labels:['customized-windows-fargate'],imageBuilder:myWindowsBuilder,});newGitHubRunners(this,'runners',{providers:[myProvider],});The runner OS and architecture is determined by the image it is set to use. For example, to create a Fargate runner provider for ARM64 set thearchitectureproperty for the image builder toArchitecture.ARM64in the image builder properties.newGitHubRunners(this,'runners',{providers:[newFargateRunnerProvider(this,'fargate runner',{labels:['arm64','fargate'],imageBuilder:FargateRunnerProvider.imageBuilder(this,'image builder',{architecture:Architecture.ARM64,os:Os.LINUX_UBUNTU,}),}),],});ArchitectureTroubleshootingRunners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. Configuration issue related errors like pointing to a missing AMI will not be retried. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.Always start with the status function, make sure no errors are reported, and confirm all status codes are OKMake sureruns-onin the workflow matches the expected labels set in the runner providerDiagnose relevant executions of the orchestrator step function by visiting the URL introubleshooting.stepFunctionUrlfromstatus.jsonIf the execution failed, check your runner provider configuration for errorsIf the execution is still running for a long time, check the execution events to see why runner starting is being retriedIf there are no relevant executions, move to the next stepConfirm the webhook Lambda was called by visiting the URL introubleshooting.webhookHandlerUrlfromstatus.jsonIf it's not called or logs errors, confirm the webhook settings on the GitHub sideIf you see too many errors, make sure you're only sendingworkflow_jobeventsWhen using GitHub app, make sure there are active installations ingithub.auth.app.installationsAll logs are saved in CloudWatch.Log group names can be found instatus.jsonfor each provider, image builder, and other parts of the systemSome useful Logs Insights queries can be enabled withGitHubRunners.createLogsInsightsQueries()To getstatus.json, check out the CloudFormation stack output for a command that generates it. The command looks like:aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.jsonMonitoringThere are two important ways to monitor your runners:Make sure runners don't fail to start. When that happens, jobs may sit and wait. UseGitHubRunners.metricFailed()to get a metric for the number of failed runner starts. You should use this metric to trigger an alarm.Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. UseGitHubRunners.failedImageBuildsTopic()to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.Other useful metrics to track:UseGitHubRunners.metricJobCompleted()to get a metric for the number of completed jobs broken down by labels and job success.UseGitHubRunners.metricTime()to get a metric for the total time a runner is running. This includes the overhead of starting the runner.Other Optionsphilips-labs/terraform-aws-github-runnerif you're using Terraformactions/actions-runner-controllerif you're using Kubernetes