Cost Estimation in Pull Requests

Stategraph Orchestration shows the monthly cost change of each pull request in the plan comment, so reviewers see an expensive change before it is applied. Each plan computes an Infracost diff between the base branch and the pull request. The estimate needs no state in Stategraph, and every Orchestration edition has it.

Enabling Cost Estimation

Cost estimation is on by default. To turn it off, or to change the currency, set cost_estimation in .stategraph/config.yml:

cost_estimation:
  enabled: true
  provider: infracost
  currency: USD
  • enabled: true estimates the cost on each plan. false skips it.
  • provider: the estimation provider. The only value is infracost.
  • currency: the ISO 4217 code of the figures. Default USD.

For all keys, see the cost_estimation reference.

How It Works

  1. You open a pull request that changes Terraform code.
  2. Orchestration runs a plan on your runner. Before the plan, an infracost_setup step runs infracost breakdown on the base branch and then on the pull request branch, for the directories and workspaces in the run. Then it compares the two results.
  3. The plan comment gets a Cost Estimation section with the result.
  4. You review the estimate with the change. If the cost is too high, change the code. The next plan estimates it again.
  5. After the pull request is approved and applied, the real costs start.

The step adds time to each plan. To see how much, see Performance.

What the Comment Shows

The Cost Estimation section shows the total monthly difference in the configured currency. It expands to a table with one row per directory and workspace: the previous monthly cost, the new monthly cost, and the difference. The last row is the total.

Stategraph GitHub AppbotAccess token usercommented
Cost Estimation

Total Monthly Difference: 6.00 USD

Expand for cost estimation details
DirWorkspacePrevious (USD)New (USD)Diff (USD)
prod/volumedefault0.006.006.00
Total0.006.006.00
The Cost Estimation section of a plan comment.

When Infracost cannot make the estimate, the section shows Error calculating Cost Estimation and expands to the Infracost output. This error does not fail the plan.

Infracost API Key

Infracost gets its prices from a cloud pricing API. The runner reaches it in one of two ways, on GitHub Actions and GitLab CI runners alike:

  • Through the Stategraph server. On Stategraph Cloud, you need no key: the server has its own Infracost credentials. On a self-hosted deployment, this is off until you set INFRACOST_PRICING_API_ENDPOINT and SELF_HOSTED_INFRACOST_API_KEY on the server. See Environment variables.
  • With your own key. When INFRACOST_API_KEY is set, the runner uses the public Infracost API directly. Get a free key on the Infracost website, or use your Infracost Cloud account.

To give the runner your key:

  • GitHub: add a repository secret named INFRACOST_API_KEY, for example with gh secret set INFRACOST_API_KEY.
  • GitLab: in the project, open Settings > CI/CD > Variables, add a variable with the key INFRACOST_API_KEY, and select Mask variable.

For both procedures in full, see Secrets and variables.

What Infracost sees

No cloud credentials or secrets are sent to the pricing API, and Infracost makes no changes to your Terraform state or cloud resources.

Customizing Infracost

The runner reads these environment variables. Set them with an env hook, in a workflow, or as GitHub secrets or GitLab CI/CD variables.

Variable Description
INFRACOST_API_KEY Your Infracost API key. See Infracost API Key.
INFRACOST_CURRENCY An ISO 4217 currency code. Overrides currency in .stategraph/config.yml.
INFRACOST_CONFIG_FILE The path to your own Infracost config file, in place of the file that the runner generates for the directories and workspaces in the run. A relative path starts at the repository root.

Custom config file

Set INFRACOST_CONFIG_FILE in a pre-plan hook:

hooks:
  plan:
    pre:
      - type: env
        name: INFRACOST_CONFIG_FILE
        cmd: ["echo", "infracost.yml"]

When the file does not exist on a branch, for example on the base branch for the previous cost, the runner uses the generated file, and the estimate still runs.

Considerations

  • The estimate uses the Terraform plan and list prices, not usage. Actual costs change with usage and prices.
  • Infracost supports many cloud providers and resources, but not every resource type. It leaves out unsupported resources, so an estimate can be incomplete.
  • Disable cost estimation for Pulumi repositories.

Pull Request Estimate and Plan-Time Cost

Orchestration and Infrastructure as a Database each estimate a change, for different questions:

Pull request estimate Plan-time cost
Produced by Orchestration, on your CI runner Infrastructure as a Database, when stategraph tf plan submits a plan
Shown in The plan comment Under the plan diff, stategraph tx costs, and the API
Granularity Per directory and workspace, plus a total Per resource and per state, with provider, type, and tag breakdowns
Stored In the run's results As planned cost snapshots you can query with SQL
Requires Infracost pricing access Cost analysis enabled on the server and state stored in Stategraph

Both are list-price estimates with the same pricing model. When Orchestration runs the stategraph engine, you can use both: the comment gives the reviewer the total, and the cost snapshots give attribution and history after the apply.

Next Steps