Abstract
Terraform AWS Github Runner is an open-source Blockchain & Cloud Computing project. Terraform module for scalable GitHub action runners on AWS. This Terraform module creates the required infrastructure needed to host GitHub Actions self-hosted, auto-scaling runners on AWS spot instances. It provides the required logic to handle the lifecycle for scaling up and down using a set of AWS Lambda functions. It is built using HCL, GitHub Actions, Terraform, Serverless, AWS. Key capabilities include: Scaling: Scale up and down based on GitHub events; Sustainability: Scale down to zero when no jobs are running; Security: Runners are created on-demand and terminated after use (ephemeral runners). The complete source code is publicly available on GitHub under the MIT License, making it a useful reference for students building a Blockchain & Cloud Computing mini project or final-year project.
1. Introduction
This Terraform module creates the required infrastructure needed to host GitHub Actions self-hosted, auto-scaling runners on AWS spot instances. It provides the required logic to handle the lifecycle for scaling up and down using a set of AWS Lambda functions. Runners are scaled down to zero to avoid costs when no workflows are active.
Check out the provided Terraform examples in the examples directory for different scenarios.
2. Objective
Terraform module for scalable GitHub action runners on AWS
This project demonstrates how HCL, GitHub Actions, Terraform can be applied to a real-world Blockchain & Cloud Computing problem.
3. Key Features / Modules
- Scaling: Scale up and down based on GitHub events
- Sustainability: Scale down to zero when no jobs are running
- Security: Runners are created on-demand and terminated after use (ephemeral runners)
- Cost optimization: Runners are created on spot instances
- Tailored software, hardware and network configuration: Bring your own AMI, define the instance types and subnets to use.
- OS support: Linux (x64/arm64) and Windows
- Multi-Runner: Create multiple runner configurations with a single deployment
- GitHub cloud, GitHub Cloud with Data Residency and GitHub Enterprise Server (GHES) support.
- Org and repo level runners. enterprise level runners are not supported (yet).
4. Technology Stack
5. System Requirements
General requirements for this technology stack — check the README for exact versions.
- Terraform CLI
- Cloud provider account (e.g. AWS) with CLI configured
- Git (to clone the repository)
6. Installation & Setup
git clone https://github.com/github-aws-runners/terraform-aws-github-runner.git
cd terraform-aws-github-runner- Setup your AWS account
- Create and configure a GitHub App
- Download or build the required lambdas
- Deploy the module using Terraform
- Install the GitHub App to your organization or repositories and add your repositories to the runner group(s).
Full setup instructions are in the project README.
7. Future Enhancements
Suggested extensions you can add to make this your own project.
- Add a CI/CD pipeline with GitHub Actions
- Deploy to a public test network or cloud free tier
- Add monitoring and cost alerts
8. Viva / Review Questions
Common questions examiners ask for projects in this domain.
- Why does this problem need a blockchain or cloud-native design?
- Explain the smart contract / infrastructure components and how they interact.
- How are gas costs or cloud costs kept under control?
- How is the system secured (keys, IAM, access control)?
- How would the solution scale to many more users?
9. Source Code & License
This project is developed by github-aws-runners and published on GitHub under the MIT License. Please follow the license terms and credit the original author when you use or modify this code.
Want to build this as your internship project?
Work on a Blockchain & Cloud Computing project like this with mentor guidance, weekly reviews and an internship certificate from Training Trains, Erode — online or offline.
Apply for Blockchain & Cloud Computing Internship