Forge Documentation¶
ForgeMT is a multi-tenant platform for self-hosted GitHub Actions runners on AWS. The open source project uses ForgeMT as the searchable product name; the docs sometimes use Forge as the short name. Platform teams use it to run ephemeral EC2 and ARC/Kubernetes runners, onboard tenants, and keep runner infrastructure out of application repos.
If you are new to Forge, read these pages first:
| Need | Page |
|---|---|
| Understand why Forge exists | Motivation |
| Understand the platform shape | Architecture |
| Install one working tenant | Minimal Install |
| Copy a real deployment example | Examples |
| Review the security model | Security |
The docs are organized by lifecycle:
| Stage | Start here | Outcome |
|---|---|---|
| Day 0 | Bootstrap | Prepare AWS profile, backend, GitHub App, secrets, and runner image. |
| Day 1 | Configure Platform | Deploy one working Forge tenant, then add EKS, helpers, or integrations. |
| Day 2 | Operations | Onboard tenants, manage images, rotate secrets, and troubleshoot jobs. |
| Day 365 | Upgrades | Keep module refs, runner images, AMIs, ECR, and cleanup jobs maintained. |
Platform Path¶
Deploy Forge in this order:
- Prepare AWS, GitHub App, state backend, secrets, and runner images.
- Use Minimal Install to prove one tenant runner lane before adding more categories.
- Configure helpers only when your account needs region opt-in, service-linked roles, AMI sharing, ECR, storage, or cleanup jobs.
- Configure infra only when Forge owns the EKS foundation for ARC runners.
- Configure platform to deploy one tenant and prove runner registration.
- Configure integrations only for systems your company actually uses.
Optional Integrations¶
Splunk, Teleport, OpenTelemetry, OpenCost, webhook relay destination modules, and vendor-specific dashboards are optional. If your company does not use one of those systems, skip its example folder, module family, and secrets.
Use Integrations only after the platform runner path is working.
Tenant Path¶
Tenant teams do not deploy Forge. They use the runner labels, GitHub App installation, and AWS access model provided by the platform team. Start with Tenant Usage.