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 — открытая платформа от Cisco для запуска self-hosted раннеров GitHub Actions на собственных AWS-аккаунтах: эфемерные EC2-раннеры и наборы масштабирования Kubernetes ARC-раннеров, управляемые как код во множестве tenant-репозиториев.
То есть это хостинговый сервис или код на Terraform, который я развертываю сам?Вы развертываете его сами из кода: набор Terraform-модулей плюс копируемые примеры Terragrunt, которые вместе образуют управляющую плоскость раннеров. Никакого SaaS-интерфейса нет — команды tenant просто используют метки раннеров в YAML своих workflow.
Как выглядит самый минимальный рабочий вариант установки?Одна организация на GitHub.com, один tenant, одна дорожка раннеров и один smoke-workflow. На практике: скопируйте examples/deployments/platform в свой IaC-репозиторий, замените значения AWS, GitHub, VPC и tenant, сохраните ключ GitHub App в SSM, затем выполните terragrunt init, plan и apply.
Что нужно подготовить до развертывания?Организацию на GitHub.com или GHES с группой раннеров и правами на установку GitHub App, AWS-аккаунт с регионом, VPC и подсетями, S3-бакет и DynamoDB-таблицу блокировок для состояния, а также AMI или образ контейнера раннера для первой дорожки.
Нужно ли развертывать все модули, чтобы получить пользу?Нет — README прямо не рекомендует этого делать. Начните с одной дорожки; для установки только на EC2 полностью пропустите EKS, а модули Splunk, Teleport, OpenCost и OpenTelemetry оставьте на потом, пока операционная модель в них не нуждается.
ForgeMT написан с нуля или построен поверх существующих проектов?Поверх существующих: дорожки на EC2 строятся на terraform-aws-github-runner, а Kubernetes-дорожки — на actions-runner-controller (ARC). ForgeMT добавляет к ним многотенантную операционную модель, границы tenant и примеры Terragrunt.
Зачем для установки создавать GitHub App?Флот раннеров интегрируется с GitHub через GitHub App, принадлежащий платформенной команде; его приватный ключ хранится в SSM, а каждая граница tenant дополнительно задает область установки этого App.
Работает ли это с GitHub Enterprise Server или только с GitHub.com?И то, и другое. Чек-лист перед развертыванием начинается с выбора цели GitHub: URL GitHub.com или GHES, организация, группа раннеров и область установки 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