Getting Started
Use this CDK construct to create ephemeral self-hosted GitHub runners on-demand inside your AWS account.
- 🧩 Easy to configure GitHub integration with a web-based interface
- 🧠 Customizable runners with decent defaults
- 🏃🏻 Multiple runner configurations controlled by labels
- 🔐 Everything fully hosted in your account
- 🔃 Automatically updated build environment with latest runner version
Self-hosted runners in AWS are useful when:
- You need easy access to internal resources in your actions
- You want to pre-install some software for your actions
- You want to provide some basic AWS API access (but aws-actions/configure-aws-credentials has more security controls)
- You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with just-in-time configurations)
Ephemeral (or on-demand) runners are the recommended way by GitHub for 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.
Installation
Install the package for your language
Available on npm.
bashnpm i @cloudsnorkel/cdk-github-runnersAvailable on PyPI.
bashpip install cloudsnorkel.cdk-github-runnersAvailable on Maven.
xml<dependency> <groupId>com.cloudsnorkel</groupId> <artifactId>cdk.github.runners</artifactId> </dependency>Available on NuGet.
bashdotnet add package CloudSnorkel.Cdk.Github.RunnersAvailable on GitHub.
bashgo get github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunnersUse
GitHubRunnersconstruct in your code (starting with default arguments is fine)tsimport { App, Stack } from 'aws-cdk-lib'; import { GitHubRunners } from '@cloudsnorkel/cdk-github-runners'; const app = new App(); const stack = new Stack(app, 'github-runners'); new GitHubRunners(stack, 'runners'); app.synth();pythonfrom aws_cdk import App, Stack from cloudsnorkel.cdk_github_runners import GitHubRunners app = App() stack = Stack(app, "github-runners") GitHubRunners(stack, "runners") app.synth()javaimport software.amazon.awscdk.App; import software.amazon.awscdk.Stack; import com.cloudsnorkel.cdk.github.runners.GitHubRunners; App app = new App(); Stack stack = new Stack(app, "github-runners"); new GitHubRunners(stack, "runners"); app.synth();csharpusing Amazon.CDK; using CloudSnorkel; var app = new App(); var stack = new Stack(app, "github-runners"); new GitHubRunners(stack, "runners"); app.Synth();goimport "github.com/aws/aws-cdk-go/awscdk" import "github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners" app := awscdk.NewApp() stack := awscdk.NewStack(app, jsii.String("github-runners")) cloudsnorkelcdkgithubrunners.NewGitHubRunners(stack, jsii.String("runners")) app.Synth()Deploy your stack
Look for the status command output similar to
aws --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 in
github.setup.urlfromstatus.jsonor manually setup GitHub integration as an app or with personal access tokenRun status command again to confirm
github.auth.statusandgithub.webhook.statusare OKTrigger a GitHub action that has a
self-hostedlabel withruns-on: [self-hosted, codebuild](or non-default labels you set in step 2)If the action is not successful, see troubleshooting