Forge

Abstract

1. Introduction

ForgeMT is a multi-tenant platform for self-hosted GitHub Actions runners on AWS. It gives platform teams an IaC-driven way to operate ephemeral EC2 runners and ARC/Kubernetes runner scale sets for many tenant repositories.

Think of ForgeMT as the runner control plane and operating model, not only a Terraform module. The platform team owns GitHub App integration, runner images, AWS placement, tenant configuration, lifecycle cleanup, and optional observability. Tenant teams consume approved runs-on labels and AWS role access from their workflow YAML.

Do not start by deploying every module. The smallest useful install is one GitHub.com organization, one tenant, one runner lane, and one smoke workflow. Add helpers, EKS, Splunk, Teleport, OpenCost, OpenTelemetry, and webhook relay modules only when your operating model needs them.

2. Objective

ForgeMT is a multi-tenant platform for self-hosted GitHub Actions runners on AWS. It gives platform teams an IaC-driven way to operate ephemeral EC2 runners and ARC/Kubernetes runner scale sets for many tenant repositories.

This project demonstrates how HCL, GitHub Actions, Terraform can be applied to a real-world Blockchain & Cloud Computing problem.

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/cisco-open/forge.git
cd forge

1. Read Platform Engineer Quick Start
2. Choose the first lane: EC2, ARC, or both.
3. Copy examples/deployments/platform into your operations IaC repo.
4. Replace the AWS, GitHub, VPC, runner image, and tenant values.
5. Create or register the GitHub App and store the private key in SSM.
6. Run terragrunt init, terragrunt plan, and terragrunt apply.
7. Queue one smoke workflow with the generated runner labels.
8. ForgeMT documentation

examples/deployments/platform

cd examples/deployments/platform/terragrunt/environments/prod/regions/eu-west-1/vpcs/main/tenants/acme
terragrunt init
terragrunt plan
terragrunt apply

---
name: Forge smoke

on:
  workflow_dispatch:

jobs:
  smoke:
    runs-on:
      - self-hosted
      - type:small
      - x64
      - ec2
      - tnt:acme
    steps:
      - run: echo "Forge runner is online"

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.

1. Why does this problem need a blockchain or cloud-native design?
2. Explain the smart contract / infrastructure components and how they interact.
3. How are gas costs or cloud costs kept under control?
4. How is the system secured (keys, IAM, access control)?
5. How would the solution scale to many more users?

9. Source Code & License

This project is developed by cisco-open and published on GitHub under the Apache License 2.0. Please follow the license terms and credit the original author when you use or modify this code.