forge README

The project's README from github.com/cisco-open/forge. As one markdown file: README.md.

ForgeMT

GitHub stars GitHub issues Release License Maintainer Docs OpenSSF Scorecard OpenSSF Best Practices CI Commits since latest release Contributors

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.

Architecture Diagram

What You Get

When To Use It

Use ForgeMT when you need:

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.

Before You Deploy

Have these answers before applying the examples:

Decision Minimum answer
GitHub target GitHub.com or GHES URL, organization, runner group, and GitHub App installation scope.
AWS placement Account, region, VPC, subnets, security groups, and tenant AWS role access.
State backend S3 bucket and DynamoDB lock table for Terraform or OpenTofu state.
First lane EC2, ARC on EKS, or both. Start with one lane and add the other after the first smoke workflow.
Runner image AMI owner/name for EC2 runners or reachable container images for ARC runners.
Tenant boundary Tenant name, generated labels, allowed repositories, IAM roles, and metadata ownership.
Integrations Which systems are mandatory now and which can be skipped until the runner path works.

Pick EC2 first when you already have a runner AMI or need VM-level isolation. Pick ARC first when EKS is already available and the first workloads fit a Kubernetes runner model. You can skip EKS for an EC2-only first deployment.

Module Layout

ForgeMT modules are grouped by operating responsibility:

Category Path Purpose
Platform modules/platform Forge runtime modules for EC2 and ARC tenant runners.
Infrastructure modules/infra EKS foundation for ARC/Kubernetes runner scale sets.
Helpers modules/helpers Account preparation and operations helpers such as AMI, ECR, S3.
Integrations modules/integrations Optional external systems such as Splunk, Teleport, and relays.
Examples examples/deployments/... Functional Terragrunt roots grouped like the module layout.

Splunk is optional. If your company does not use Splunk, skip the Splunk example folders, all modules/integrations/splunk_* modules, and modules/integrations/splunk_dependency_monitor.

Quick Start

Start with the platform path:

  1. Read Platform Engineer Quick Start and Minimal Install.
  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.

The first install path is the platform example:

examples/deployments/platform

After replacing the values and storing the real GitHub App PEM in SSM, run from the tenant folder:

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

For the full sequence, including backend bootstrap and GitHub App registration, use Bootstrap and Minimal Install.

Read next:

Tenant Usage

After the platform team onboards a tenant, repository owners request the runner with labels generated by ForgeMT:

---
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"

Tenant teams should use Tenant Usage for label, AWS role, ECR, and troubleshooting patterns.

Learn More

Technical background:

Implementation foundations:

Contributing

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

License

Apache 2.0. See LICENSE.

Contact

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

forge (cisco-open/forge)

Searching Database…

213 ·GitHub
Forge
What is this?ForgeMT is an open-source platform from Cisco for running self-hosted GitHub Actions runners on your own AWS accounts — ephemeral EC2 runners and Kubernetes ARC runner scale sets, operated as code across many tenant repos.
So is it a hosted service, or Terraform code I deploy myself?You deploy it yourself from code: a set of Terraform modules plus copyable Terragrunt examples that form a runner control plane. There is no SaaS UI — tenant teams just consume runner labels in their workflow YAML.
What does the smallest useful install look like?One GitHub.com org, one tenant, one runner lane and one smoke workflow. In practice: copy examples/deployments/platform into your IaC repo, replace the AWS, GitHub, VPC and tenant values, store the GitHub App key in SSM, then run terragrunt init, plan and apply.
What do I need to have in place before deploying?A GitHub.com or GHES org with a runner group and GitHub App scope, an AWS account with region, VPC and subnets, an S3 bucket plus DynamoDB lock table for state, and a runner AMI or container image for your first lane.
Do I need to deploy all the modules to get value?No — the README says not to. Start with a single lane; skip EKS entirely for an EC2-only install, and leave Splunk, Teleport, OpenCost and OpenTelemetry modules out until your operating model needs them.
Is ForgeMT built from scratch or on top of existing projects?On existing ones: EC2 lanes build on terraform-aws-github-runner, and Kubernetes lanes on actions-runner-controller (ARC). ForgeMT adds the multi-tenant operating model, tenant boundaries and Terragrunt examples on top of them.
Why does setup require creating a GitHub App?The runner fleet integrates with GitHub through a GitHub App owned by the platform team; its private key is stored in SSM, and each tenant boundary also defines the App's installation scope.
Does it work with GitHub Enterprise Server, or only GitHub.com?Both. The pre-deployment checklist starts from your GitHub target: a GitHub.com or GHES URL, organization, runner group and GitHub App installation scope.
What are similar projects?floci, encore, neckbeard, semaphore, terraformer, full-stack-data-engineering, yq, vcluster
Which topics is it in?ec2, platform-engineering, multi-tenancy, iam, devops-tools, multi-tenant, terraform, devsecops, infrastructure-as-code, oidc, ci-cd, aws
Creator
cisco-open
Size
6.3 MB
Stars
213
Updated
CommitOct 14Releasev4.18.0Oct 02
Age
1y
Commits · 90 Days