This is a CDK project to construct ECS cluster of Github self-hosted runner.

This CDK project includes the following stacks.

• <clusterName>-vpc-stack
  • Create VPC and Subnets for ECS cluster
• <clusterName>-stack
  • Create ECS cluster and Autoscaling
• <clusterName>-funcs-stack
  • Create Lambda functions to start and to stop Github Actions Runner tasks.

Create a secret of AWS Secret Manager, which has the secret key named GITHUB_TOKEN which is setted value Github Personal Access Token.

If you want to connet EC2 node of ECS cluster by SSH, create key pair.

Create your configuration file in config/ directory. your configuration file overwrite config/default.ts.

Minimum configuration is the following.

import { ConfigDefinition } from '../lib/Config';

const config: Partial<ConfigDefinition> = {
  repo: {
    owner: 'owner',
    name: 'your-repo-name',
  },
  secretName: 'your-secret-name',
};

export default config;

See config/minimum-sample.ts.

Full configuration sample is config/maximum-sample.ts

When you want to deploy this CDK project, run the following commands. Set environment variable NODE_CONFIG_ENV to select your configuration file.

export NODE_CONFIG_ENV=<your-config-file-name(without extention)>
yarn cdk deploy --all

if you want to delete AWS resources of this CDK project, Run the following command.

export NODE_CONFIG_ENV=<your-config-file-name(without extention)>
yarn cdk destroy --all

This cdk application include lambda functions to operate Github actions runner tasks. To start task, run the following command.

# for start EC2 runners
aws lambda invoke --function-name <clusterName>-start-runners-ec2 /dev/null

# for start Fargate runners
aws lambda invoke --function-name <clusterName>-start-runners-fargate /dev/null

To stop task, run the following command.

aws lambda invoke --function-name <clusterName>-stop-runners /dev/null

You can pull Github runner image from ghcr.io/heromo/ecs-github-actions-runner:latest .

This image is configurable by the following environment variables.

• REPOSITORY_URL: [Required] Repository to add the runner to.
• TOKEN: [Required] Registration token.
• EPHEMERAL: [Optional] runner runs ephemeral mode, If yes setted.
• LABELS: [Optional] Extra labels in addition to the default labels.

REPOSITORY_URL is setted in ECS task definition. If you use lamba function to start runners, TOKEN is setted automatically.

• yarn build compile typescript to js
• yarn watch watch for changes and compile
• yarn test perform the jest unit tests
• yarn eslint check by eslint
• yarn cdk deploy deploy this stack to your default AWS account/region
• yarn cdk diff compare deployed stack with current state
• yarn cdk synth emits the synthesized CloudFormation template

MIT