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
这是做什么的?ForgeMT 是思科开源的一个平台,用来在你自己的 AWS 账户上运行自托管的 GitHub Actions runner——包括临时性的 EC2 runner 和 Kubernetes 上的 ARC runner 弹性伸缩组,以代码方式管理,可覆盖多个租户仓库。
那它是一个托管服务,还是我自己部署的 Terraform 代码?需要你自己从代码部署:它由一组 Terraform 模块加上可直接复制的 Terragrunt 示例组成,构成一个 runner 控制平面。没有 SaaS 界面——各租户团队只需在自己的 workflow YAML 里使用对应的 runner 标签。
最小可用的安装是什么样的?一个 GitHub.com 组织、一个租户、一条 runner 通道和一个冒烟测试 workflow。实际操作:把 examples/deployments/platform 复制到你的 IaC 仓库,替换其中的 AWS、GitHub、VPC 和租户配置值,把 GitHub App 的私钥存进 SSM,然后依次运行 terragrunt init、plan 和 apply。
部署之前我需要准备些什么?需要一个 GitHub.com 或 GHES 的组织,并配备 runner 组和 GitHub App 授权范围;一个 AWS 账户,含区域、VPC 和子网;一个用于存放状态的 S3 存储桶加 DynamoDB 锁表;以及第一条 runner 通道所需的 runner AMI 或容器镜像。
我需要把所有模块都部署了才有用吗?不需要——README 明确说不必这么做。先从单条通道开始;只跑 EC2 的话可以完全跳过 EKS;在运维模式真正需要之前,Splunk、Teleport、OpenCost 和 OpenTelemetry 这些模块都可以先不装。
ForgeMT 是从零写的,还是在现有项目基础上做的?是在现有项目基础上做的:EC2 通道基于 terraform-aws-github-runner,Kubernetes 通道基于 actions-runner-controller(ARC)。ForgeMT 在它们之上增加了多租户的运维模式、租户边界和 Terragrunt 示例。
为什么部署时要创建一个 GitHub App?runner 资源池通过一个由平台团队拥有的 GitHub App 与 GitHub 集成;它的私钥保存在 SSM 里,而且每个租户边界也会定义这个 App 的安装范围。
它支持 GitHub Enterprise Server 吗,还是只支持 GitHub.com?两者都支持。部署前的检查清单第一步就是确认你的 GitHub 目标:GitHub.com 或 GHES 的 URL、组织、runner 组和 GitHub App 的安装范围。
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