Module Layout

ForgeMT organizes modules by operational intent. The goal is to make the install path obvious and keep optional systems out of the critical path.

---

Layout

modules/
  platform/      Forge runner runtime and internal platform building blocks.
  infra/         Foundational infrastructure for the platform.
  helpers/       Operational helper modules used to run and maintain Forge.
  integrations/  Optional external integrations and vendor-specific modules.

Use platform first, infra only for EKS/ARC foundations, helpers when you need operational support resources, and integrations only when your company uses those external systems.

For a full module-by-module map, see Module Catalog.

---

Platform Modules

Module	Purpose	Directly call it?
modules/platform/forge_runners	Tenant runner entry point. Wires EC2 and ARC runner specs, GitHub App behavior, trust validation, job logs, relay options, and service catalog data.	Yes. This is the normal tenant-facing module.
modules/platform/ec2_deployment	EC2 runner lane backed by terraform-aws-github-runner.	Usually through forge_runners.
modules/platform/arc_deployment	Tenant ARC runner lane wrapper.	Usually through forge_runners.
modules/platform/arc	Lower-level ARC controller and scale-set Helm wrapper.	No, unless building a custom platform wrapper.

---

Infrastructure Modules

Module	Purpose	Required?
modules/infra/eks	Builds the EKS foundation for ARC/Kubernetes runners, including Karpenter, Calico, EBS CSI, CoreDNS, and pod identity support.	Required only for ARC runners.

EC2-only Forge deployments can skip modules/infra/eks.

---

Helper Modules

Module	Purpose
modules/helpers/aws_config_recording	Records caller-selected AWS resource types with AWS Config.
modules/helpers/ami_policy	IAM policy support for Forge AMI usage.
modules/helpers/ami_sharing	Shares runner AMIs across accounts or regions.
modules/helpers/cloud_custodian	Runs cleanup and policy automation.
modules/helpers/cloud_formation	Creates CloudFormation admin and execution roles used by CloudFormation-backed setup paths.
modules/helpers/dedicated_mac_hosts	Allocates Mac Dedicated Hosts and configures host groups and licensing.
modules/helpers/ecr	Creates ECR repositories for runner, sidecar, Lambda, or operational images.
modules/helpers/forge_subscription	Creates tenant-side roles and access policies for Forge runner jobs.
modules/helpers/opt_in_regions	Enables AWS opt-in regions.
modules/helpers/service_linked_roles	Creates AWS service-linked roles used by services such as EC2 Spot.
modules/helpers/storage	Creates S3 buckets for artifacts, templates, logs, and operational data.

Helpers are useful, but they are not the runner runtime. Deploy them when your company's operating model requires them.

---

Integration Modules

Module family	Purpose	Required?
modules/integrations/splunk_dependency_monitor	Regional tenant dependency probes delivered to Splunk Cloud and Splunk Observability.	No.
modules/integrations/splunk_*	Splunk Cloud, Splunk Observability, dashboards, billing ingest, OpenTelemetry, OpenCost, secrets, and stuck-workflow redelivery.	No.
modules/integrations/teleport	Teleport agents and access/audit integration.	No.
modules/platform/forge_runners/github_webhook_relay/source	Internal GitHub webhook ingress used by the Forge tenant runner platform.	Yes.
modules/integrations/github_webhook_relay_*	GitHub webhook relay destination and receiver modules for external consumers.	No.

Splunk modules are intentionally optional. A company that uses another observability platform should skip the Splunk deployment example and provide its own log and metric ingestion path.

---

Release Metadata

Every deployment root should pin both the Forge ref and the module path in release_versions.yml or release_versions.yaml. Terragrunt stacks should read those values instead of rebuilding source addresses in every stack.

module_path: modules/helpers/storage
ref: <forge-release-tag-or-commit>