ForgeMT

Commits since latest release

What is ForgeMT

ForgeMT is an enterprise-grade GitHub Actions runner platform for AWS. It provides:

Secure multi-tenancy using IAM/OIDC and network segmentation
Ephemeral EC2 and Kubernetes runners for cost-efficient scaling
Full automation for onboarding, GitHub App management, and lifecycle updates
Built-in observability and governance

ForgeMT allows organizations running thousands of CI/CD pipelines daily to scale without hitting performance, cost, or security limits.

Architecture Diagram

Who Should Use ForgeMT?

ForgeMT is ideal for organizations that:

Run 100+ CI/CD jobs daily across multiple teams
Need stricter security controls than GitHub hosted runners
Want to reduce runner costs while maintaining performance
Require custom environments or access to internal AWS resources

Key Benefits

Secure Multi-Tenant Isolation: Strong boundaries without fragmenting infrastructure. Short-lived IAM roles via OIDC replace static secrets.
Cost Optimization: Spot instances, scale-to-zero, warm pools, and optimized pod sizing.
Full Automation: Zero-touch operations for onboarding, updates, and configuration.
Open Source: Fully transparent, adaptable, and vendor-neutral.

How It Compares

| Solution | Cost | Security | Maintenance | Custom Env | | ----------------- | ---------------- | ------------ | ----------- | ---------- | | GitHub Hosted | High volume cost | Standard | None | Limited | | Basic Self-Hosted | EC2 costs | Manual setup | High | Full | | ForgeMT | Optimized | Enterprise | Low | Full |

Architecture Overview

ForgeMT separates the control plane from the tenant plane:

Control Plane: Manages the deployment, provisioning, scaling, and monitoring of all runners. Built with OpenTofu/Terraform, Helm (ARC), and centralized IAM/OIDC, it ensures automated and secure operations across tenants.
Tenant Plane: Runs ephemeral CI/CD jobs. Tenants access their AWS resources via short-lived IAM roles using OIDC trust relationships. All runners are automatically deployed by the control plane, and tenants do not manage them directly.

Supported runner types:
- EC2 runners: Full VM control, custom AMIs, per-tenant sandboxes.
- EKS runners (ARC): Containerized workloads in per-tenant namespaces. Uses Calico CNI to optimize IP allocation for large-scale deployments.

Architecture Diagrams:

Multi-Tenant Overview High-level view of ForgeMT multi-tenant architecture.

EC2 Runner Architecture Deployment and lifecycle of EC2 runners.

EKS Runner Architecture Deployment and lifecycle of EKS (ARC) runners.

Tenant Overview Tenant plane showing ephemeral runner usage and IAM/OIDC access.

Runner Types

| Type | Use Case | Isolation | Scaling | | ------------- | ----------------------------- | ------------------------------------------------------ | ------------------------ | | EC2 | Full VM control, custom AMIs | Per-tenant sandbox in shared AWS accounts via IAM/OIDC | EC2 ASG + Spot/On-Demand | | EKS (ARC) | Burst workloads in containers | Per-tenant namespace (optionally node-isolated) | Karpenter + ARC |

Two User Personas

🔧 Platform Administrator

Role: Deploy and maintain ForgeMT infrastructure
Responsibilities: AWS account setup, tenant provisioning, platform updates
Tools: OpenTofu, AWS CLI, kubectl, helm
Workflow: Deploy control plane → Onboard tenants → Monitor platform

👩‍💻 Development Team (Tenant)

Role: Use ForgeMT runners for CI/CD pipelines
Responsibilities: Configure workflows, manage GitHub Apps, consume runners
Tools: GitHub Actions YAML, GitHub CLI (optional)
Workflow: Request access → Configure workflows → Run CI/CD jobs

Quick Start

For Platform Administrators

Deploy and manage the ForgeMT infrastructure:

Deploy Your First Tenant — Minimal setup to bootstrap ForgeMT.
All Deployment Scenarios — Includes EKS, Splunk, BYO AMIs, and advanced patterns.

Prerequisites: AWS CLI configured, OpenTofu 1.11+, kubectl, helm

For Development Teams (Tenants)

Use ForgeMT runners in your GitHub Actions workflows:

Tenant Usage Guide — Onboarding, GitHub App setup, and day-2 operations.

Sample Tenant Usage

Once onboarded by an admin, tenants use ForgeMT runners like this:

# .github/workflows/ci.yml
name: CI Pipeline
on: [push, pull_request]

jobs:
  test:
    runs-on: forge-ec2-medium  # Your ForgeMT runner
    permissions:
      id-token: write  # Required for OIDC
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: us-west-2

      - name: Run tests with AWS access
        run: |
          # Your CI/CD commands here
          # Full access to AWS resources via OIDC
          aws s3 ls
          docker build -t myapp .

Key Benefits for Tenants:

🔒 Secure AWS access without storing secrets
⚡ Custom instance types (EC2) or fast container startup (EKS)
💰 Cost-efficient with auto-scaling and spot instances
🛠️ Zero maintenance - admins handle all infrastructure

Core Features

| Feature | Description | | ----------------------- | ------------------------------------------------ | | Ephemeral Runners | Auto-scaling EC2/EKS runners with zero idle cost | | Tenant Isolation | Secure IAM + OIDC + VPC per tenant/project | | Zero-Touch Operations | Automatic patching, upgrades, drift remediation | | Observability | Logs, metrics, dashboards per tenant | | Cost Optimization | Spot, scale-to-zero, warm pools | | Flexible Infrastructure | BYO AMIs, VPCs, subnets, instance types | | Multi-Runner Support | Mix EC2 and EKS in one deployment | | GitHub Cloud & GHES | Works with SaaS and on-prem GitHub setups |

Learn More

Contributing

Contributions are welcome via issues or pull requests. See CONTRIBUTING.md for details.

Acknowledgements

Built on top of:

License

Apache 2.0 — see LICENSE

Contact

Track progress or open issues on GitHub: https://github.com/cisco-open/forge/issues

Forge

Install / Use

README