GitHub Self-Hosted Runners CDK Constructs
Use this CDK construct to create ephemeral self-hosted GitHub runners on-demand inside your AWS account.
- Easy to configure GitHub integration
- Customizable runners with decent defaults
- Supports multiple runner configurations controlled by labels
- Everything fully hosted in your account
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 (aws-actions/configure-aws-credentials has more security controls)
Ephemeral 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.
API
Documentation of available constructs and their interface is available on Constructs Hub in all supported programming languages.
Providers
A runner provider creates compute resources on-demand and uses actions/runner to start a runner.
Provider | Time limit | vCPUs | RAM | Storage | sudo | Docker |
---|---|---|---|---|---|---|
CodeBuild | 8 hours (default 1 hour) | 2 (default), 4, 8, or 72 | 3gb (default), 7gb, 15gb or 145gb | 50gb to 824gb (default 64gb) |
|
|
Fargate | Unlimited | 0.25 to 4 (default 1) | 512mb to 30gb (default 2gb) | 20gb to 200gb (default 25gb) |
|
|
Lambda | 15 minutes | 1 to 6 (default 2) | 128mb to 10gb (default 2gb) | Up to 10gb (default 10gb) |
|
|
The 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.
You can also create your own provider by implementing IRunnerProvider
.
Installation
- Confirm you're using CDK v2
- Install the appropriate package
- Python
pip install cloudsnorkel.cdk-github-runners
- TypeScript or JavaScript
npm i @cloudsnorkel/cdk-github-runners
- Java
<dependency> <groupId>com.cloudsnorkel</groupId> <artifactId>cdk.github.runners</artifactId> </dependency>
- Go
go get github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners
- .NET
dotnet add package CloudSnorkel.Cdk.Github.Runners
- Python
- Use
GitHubRunners
construct in your code (starting with default arguments is fine) - Deploy your stack
- Look for the status command output similar to
aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
- Execute the status command (you may need to specify
--profile
too) and open the resultingstatus.json
file - Setup GitHub integration as an app or with personal access token
- Run status command again to confirm
github.auth.status
andgithub.webhook.status
are OK - Trigger a GitHub action that has a
self-hosted
label withruns-on: [self-hosted, linux, codebuild]
or similar - If the action is not successful, see troubleshooting
Customizing
The default providers configured by GitHubRunners
are 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:
import * as cdk from 'aws-cdk-lib';
import { aws_ec2 as ec2, aws_s3 as s3 } from 'aws-cdk-lib';
import { GitHubRunners, CodeBuildRunner } from '@cloudsnorkel/cdk-github-runners';
const app = new cdk.App();
const stack = new cdk.Stack(
app,
'github-runners-test',
{
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION,
},
},
);
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',
}
);
app.synth();
Architecture
Troubleshooting
- Always start with the status function, make sure no errors are reported, and confirm all status codes are OK
- Confirm the webhook Lambda was called by visiting the URL in
troubleshooting.webhookHandlerUrl
fromstatus.json
- If it's not called or logs errors, confirm the webhook settings on the GitHub side
- If you see too many errors, make sure you're only sending
workflow_job
events
- Check execution details of the orchestrator step function by visiting the URL in
troubleshooting.stepFunctionUrl
fromstatus.json
- Use the details tab to find the specific execution of the provider (Lambda, CodeBuild, Fargate, etc.)
- Every step function execution should be successful, even if the runner action inside it failed
Other Options
- philips-labs/terraform-aws-github-runner if you're using Terraform
- actions-runner-controller/actions-runner-controller if you're using Kubernetes