GitHub PR Simulation Reports

How it works

When you install the Cloud World Model GitHub App on a repository and link it to your CWM API key, the app listens for pull request events. Each time a PR is opened or updated, the app:

1. Scans the changed files for Terraform/OpenTofu-compatible configuration and other infrastructure definitions (see supported formats below).
2. Resolves the immutable base and head commit SHAs and fetches the touched IaC scope, including required support files, at each commit.
3. Translates each ref's detected resource configuration into a canonical CWM simulation input.
4. Runs both snapshots through the same seeded 30-step workload for one flat 10-credit charge.
5. Posts a PR comment and informational GitHub Check with the Before / After / Impact table and links to the read-only snapshots.

If neither commit contains supported IaC in the touched scope, the app posts a brief note explaining that no simulation was run. If only one side contains supported IaC, the app still reports the addition or removal using the empty-side rules below.

What the report includes

Each PR comment and GitHub Check contains the same four-row comparison table. The Impact value is always After minus Before and is marked as favourable, unfavourable, or unchanged for that metric:

Base vs. head comparison

When a PR changes infrastructure, the report compares two snapshots side by side: the base (the target branch as it stands today) and the head (the branch with your PR applied). The read-only workspace linked from the PR comment shows a Before / After / Impact table plus commit links and a base/head snapshot toggle so you can inspect either configuration on the canvas without editing anything.

Deterministic by construction

Both sides run the same fixed 30-step simulation with the same seed. Because the only variable is the infrastructure defined in the diff, every delta shown in the Impact column is attributable to your change — not to run-to-run randomness. Re-running the same base and head commits produces the same numbers.

How to read the Impact column

The Impact column shows head − base, expressed in each metric's own unit — for example +$0.42/hr for cost, −35 ms for latency, or +8 pts for the resilience score. Deltas are coloured by whether the change is an improvement for that metric (lower cost, latency, and CPU are better; higher resilience is better). A delta is only shown when both sides have a value.

Scope of the comparison

The comparison covers only what CWM can model deterministically from the diff. Anything outside that scope — unmodeled resource types, request-based (per-invocation) pricing, or structural limitations of the detected configuration — is listed under an “Outside the comparison's scope” warning so reviewers do not over-trust the numbers. Treat those items as unmeasured, not as “no change”.

Simulation basis and provenance

Completed comparison reports include a compact Simulation basis that shows the before/after modeled resource counts, the fixed synthetic request rate, and the 30-step budget. The same compact basis appears in the GitHub Check so reviewers can see the context without opening the full PR comment.

The expandable “Simulation inputs, mappings and assumptions” details group the run information into Observed; peer mapping outcomes of Exact, Inferred, and Unsupported; then Assumed and Not evaluated. “Observed” refers to source files actually fetched for the comparison: selected IaC files at the immutable base and head commits and, for supported module chains, child-module source at the selected commits or pinned public refs. Resource-shape mappings, inferred connections, image-based Compose classification, and extractor defaults are identified separately rather than described as observed inputs.

These mapping labels describe two separate provenance dimensions. Exact means the source construct identity — its provider and CWM resource type — was preserved. Inferred means CWM added assumptions for modeled behavior, sizing, defaults, or topology. One source construct can therefore be Exact at the identity level while still having separate inferred modeling characteristics; this does not change its classification, simulation results, telemetry outcomes, or pricing behavior.

Repository scope is limited to the touched IaC files selected for each ref and the bounded support files needed for modeling or confirming formats such as Helm charts. Supported module-call chains may also fetch same-repo child modules at the selected commits or pinned public Registry/Git modules, as described below. CWM does not inspect live infrastructure, application code, production traffic, or provider APIs. The report is therefore a bounded model comparison, not a confidence score or a statement about the deployed environment.

Kubernetes workload capacity is inferred

Terraform infrastructure and Kubernetes workloads have deliberately different labels. For example, a Terraform aws_instance.cross_cloud change from t3.micro to t3.xlarge is shown as Exact — Terraform EC2: the source instance and its modeled SKU are both named. A Deployment that produces resources such as nymeria-aws and nymeria-aws-1 is shown as Inferred — Kubernetes workload capacity. Those names do not mean CWM discovered AWS instances, worker nodes, or pod placement in the repository.

For Kubernetes workload capacity, CWM uses AWS and us-east-1 as modeling defaults. A displayed t3.micro is a capacity-model shape, not an observed worker-node SKU. Replica count and CPU limits affect the capacity/performance model. CPU requests, memory, and ephemeral storage are explicitly disclosed when present, but are not evaluated as billable infrastructure.

Cost detail separates direct modeled resource charges from simulation-derived effects such as egress and data transfer. An egress delta emerges from the combined simulated topology and workload; it is non-additive and is never attributed to either a Terraform EC2 change or a Kubernetes manifest change alone.

PRs that add or remove infrastructure

When a PR adds new infrastructure there is no base configuration to compare against, so the base side is empty and its cost is shown as $0/hr. When a PR removes infrastructure the head side is empty and the table shows its cost as $0/hr. The cost impact remains a real signed After-minus-Before delta; p99 latency, Peak CPU, and Resilience are labelled N/A on the empty side instead of simulating a fallback server.

Credit usage

Each completed PR simulation deducts a flat 10 credits from the CWM API key you linked during setup. The cost is the same regardless of the number of resources in the diff — 30 steps are always run.

A base-vs-head comparison is billed as a single 10-credit charge, not two. The one charge covers simulating both the base and head snapshots and producing the Before / After / Impact report — so a PR that runs a full comparison costs exactly the same as one that only has a head snapshot.

If your account has fewer than 10 credits when a PR event arrives, the simulation is skipped before either snapshot runs. If a required comparison run fails after the charge is reserved, the reservation is refunded and no partial result is published. You can monitor your balance on the Billing page.

Linking your installation

Install the Cloud World Model GitHub App and choose the repositories it can access before linking it below.

After installing the GitHub App, you are redirected to the setup page at /github/setup. Paste your CWM API key (starts with cwm_live_) and submit the form. The installation ID is pre-filled from the redirect URL.

The key is validated immediately and then discarded — only a hashed reference is stored. If you rotate your API key, re-submit the setup form with the new key.

Supported IaC formats

The app detects infrastructure resources from the following file types in a PR diff:

Terraform/OpenTofu compatibility boundary

CWM supports Terraform/OpenTofu-compatible configuration, not Terraform or OpenTofu execution. The GitHub App uses the existing bounded static extractor to inspect source text at immutable commits. It never runs terraform plan, terraform apply, tofu plan, or tofu apply; it does not initialize provider plugins or read Terraform/OpenTofu state.

Supported IaC coverage

Detecting an IaC file does not mean every resource in that file is faithfully modeled. Each recognized construct is classified in the report’s mapping audit as Exact, Inferred, or Unsupported. Exact preserves the source construct’s provider and CWM resource type identity. Inferred describes assumptions added for modeled behavior, sizing, defaults, or topology — for example, translating a Kubernetes CPU limit into a modeled shape. Unsupported is reported as unmodeled and is never treated as an AWS reference server. An exact Terraform compute mapping may still have inferred CWM sizing, provider, region, or topology characteristics; those are separate dimensions, not a correction to the exact identity mapping.

Terraform/OpenTofu-compatible module calls are a bounded coverage boundary. CWM can follow supported same-repo and pinned public module-call chains as described below, but it does not run terraform or tofu or evaluate arbitrary modules. Unresolved calls remain Unsupported; a neutral no-simulation result makes no claim about infrastructure inside them. Directly modeled Terraform resources in the same root module are still compared normally.

OCI Terraform support is explicitly limited to the catalog-backed families listed in the table: compute and Functions, Autonomous Database/MySQL HeatWave, Object/Block/File Storage, Load Balancing, Redis cache, Streaming/Queue, and a single directly related OKE node pool. VCN, subnet, IAM, attachment, listener, and mount-target resources provide relationship evidence only; unsupported OCI services, dynamic or computed values, unbounded collections, and ambiguous relationships remain Unsupportedand never become an AWS fallback or an invented OCI tier.

For supported chains, when every module call in a changed file has a source CWM can resolve — a same-repo relative path (./ or ../), a pinned public Terraform Registry address (<namespace>/<name>/<provider> with an exact version, no range operator), or a pinned GitHub-hosted Git address (git::https://github.com/<owner>/<repo>?ref=<tag-or-sha> or the github.com/... shorthand, with a full commit SHA or semantic-version tag) — CWM follows the module-call graph, as many hops as it actually contains up to a small bounded depth, fetching each hop’s directory and propagating each hop’s literal and var.<name> call arguments into the next hop’s variable scope using Terraform’s own name-matching rule. A same-repo hop fetches at the PR’s exact base and head commits; a registry or Git hop fetches the published module’s source at its pinned version/ref over the public internet (unauthenticated, public repositories only), and any further same-repo-relative calls inside that external module resolve against it, not the PR’s own repository. If the chain terminates in an already-covered resource, CWM simulates it and the report’s mapping detail names the resolved chain (the module labels/paths walked from the changed call to the modeled resource) and the specific propagated input(s) responsible — a chain that crossed into an external module is labeled distinctly (“registry/Git-resolved”) and names the exact published module fetched, so it is never confused with an ordinary same-module default or a purely same-repo chain. An unpinned version/ref, an HTTP or otherwise unrecognized source, a private or unreachable module, an ambiguous or cyclic call graph, a hop that cannot be fetched, or a chain that exceeds the bounded depth all fall back unchanged to the neutral module-boundary result above — CWM never simulates a partial or guessed chain, and sibling module calls not on the resolved path are never fetched.

Top-level Terraform/OpenTofu-compatible locals declarations are also an explicit Unsupported coverage boundary when no directly mapped resource is in the analyzed scope. CWM does not resolve local values into resources outside that scope, so the neutral result does not identify, infer, or simulate an unobserved resource. Directly modeled resources remain eligible for their normal comparison.

The audit resolves only the bounded Terraform/OpenTofu-compatible module chains and literal or directly propagated variable inputs described above. It does not evaluate arbitrary module expressions, remote state, Helm template rendering, provider lookups, live infrastructure, or application traffic. An unsupported construct is a limitation to investigate, not evidence that it has no cost or operational impact. This reference lists supported construct categories only; it never includes repository content, filenames, or configuration values from pull requests.

If your IaC format is not listed above, the PR comment will note that no infrastructure was detected rather than producing a misleading report.

Need help?

Check the getting started guide for API key setup, or visit the full API reference for the underlying simulation endpoints the app uses.