Terraform Cost Estimation: Catch Spend in the PR

Cloud cost tools that read your bill are, by definition, retrospective — they tell you what a decision cost after it's been running for a billing cycle. By the time a monthly review flags an oversized instance or a duplicated NAT Gateway, fixing it means another PR, another review, another deploy. Catching the same issue in the original pull request costs a comment and a changed line.

This is the "shift-left" argument for FinOps: put the cost signal as close as possible to the decision that creates it. For infrastructure defined in Terraform, that decision point is the pull request, and the mechanism is Infracost — an open-source CLI that parses a Terraform plan, looks up current cloud pricing for every resource in it, and outputs a cost breakdown or a diff against what's currently deployed. No resources are created and no cloud credentials are needed for pricing lookups — it works entirely from the plan.

This tutorial is deliberately command-level: every snippet below is either the literal output of infracost --help on the current CLI (v0.10.x) or drawn directly from Infracost's and GitLab's published CI documentation. For the higher-level case on why to add guardrails and how to roll them out to a team without causing friction, see our companion post, Catch Cloud Costs Before You Deploy: CI/CD Cost Guardrails. This one is the step-by-step build.

Infracost ships prebuilt binaries and package-manager installs for macOS, Linux, and Windows. The install script is the fastest path on Linux/macOS/WSL:

curl -fsSL https://raw.githubusercontent.com/infracost/infracost/master/scripts/install.sh | sh

macOS users with Homebrew can use the tap instead:

brew install infracost

Windows users can install with Chocolatey, or download the release binary directly from the Infracost GitHub releases page. Verify the install with:

infracost --version

Infracost is free to use for the CLI and public pricing data. Registering for an API key (needed for pricing lookups and, later, for the GitHub/GitLab integrations) is a single command that opens a browser to sign up:

infracost auth login
# or set an existing key directly:
infracost configure set api_key MY_API_KEY

Once installed, running infracost --help lists the available commands. The three that matter for this tutorial are breakdown, diff, and comment.

infracost breakdown is the base command: point it at a Terraform directory or an existing plan, and it returns a full cost breakdown of every priced resource. Infracost supports two input modes. The simplest is pointing it straight at your Terraform directory, which runs terraform plan internally:

infracost breakdown --path /code --terraform-var-file my.tfvars

For CI pipelines, or anywhere you don't want Infracost invoking Terraform itself (HCP Terraform/Terraform Enterprise runs, Bitbucket Pipelines, or any setup where the plan is generated by a separate step), feed it a plan JSON instead — this is the pattern used throughout the rest of this tutorial:

terraform plan -out tfplan.binary
terraform show -json tfplan.binary > plan.json
infracost breakdown --path plan.json

Useful flags on breakdown: --format json|table|html controls output shape (table is the human-readable default), --out-file saves the result to disk instead of stdout, and --usage-file lets you supply expected usage (requests/month, data transfer GB, etc.) for resources Infracost can't price from the plan alone — Lambda invocations or S3 request counts, for example.

A total cost breakdown is useful, but the number that actually matters in a PR is the change: what does this specific commit add or remove from the monthly bill? That's what infracost diff is for — it compares the plan for your proposed change against a baseline and reports the delta.

The most direct pattern, from a Terraform plan JSON (works even when the plan already reflects the diff, e.g. a single PR's changes):

terraform plan -out tfplan.binary
terraform show -json tfplan.binary > plan.json
infracost diff --path plan.json

To diff two states explicitly — say, the base branch versus the head branch of a PR — generate a baseline breakdown first, then diff the new plan against it with --compare-to:

# On the base branch
infracost breakdown --path /code --format json --out-file infracost-base.json

# On the PR branch, after making Terraform changes
infracost diff --path /code --compare-to infracost-base.json

This is exactly the pattern the CI integrations below automate: check out the base branch, run a breakdown, check out the head branch, run a diff against that baseline JSON, and post the result as a comment.

Running Infracost locally is useful for spot-checking a change before you push. The real value of shift-left FinOps comes from automating it so every PR gets a cost comment with no one having to remember to run the CLI. Infracost publishes an official GitHub Action, infracost/actions, that installs the CLI in a workflow step so infracost commands run natively alongside your normal Terraform steps.

A minimal workflow that installs the CLI:

name: infracost-comment
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  infracost:
    runs-on: ubuntu-latest
    steps:
      - name: Setup Infracost
        uses: infracost/actions/setup@v3
        with:
          api-key: ${{ secrets.INFRACOST_API_KEY }}

      - name: Checkout base branch
        uses: actions/checkout@v4
        with:
          ref: '${{ github.event.pull_request.base.ref }}'
          path: base

      - name: Generate Infracost cost baseline
        run: |
          infracost breakdown --path=base \
                               --format=json \
                               --out-file=/tmp/infracost-base.json

      - name: Checkout PR branch
        uses: actions/checkout@v4

      - name: Generate Infracost diff
        run: |
          infracost diff --path=. \
                          --format=json \
                          --compare-to=/tmp/infracost-base.json \
                          --out-file=/tmp/infracost.json

      - name: Post Infracost comment
        run: |
          infracost comment github --path=/tmp/infracost.json \
                                    --repo=${{ github.repository }} \
                                    --github-token=${{ github.token }} \
                                    --pull-request=${{ github.event.pull_request.number }} \
                                    --behavior=update

Store INFRACOST_API_KEY as a repository secret (get one free with infracost auth login from Step 1). The --behavior=update flag means Infracost edits its existing comment on subsequent pushes to the same PR instead of spamming a new one every time — the other supported values are new, hide-and-new, and delete-and-new.

Infracost also ships newer, higher-level actions — infracost/actions/diff@v4 and infracost/actions/scan@v4 — that wrap the checkout/breakdown/diff/comment sequence above into two steps if you'd rather not assemble it manually. The manual version above is worth understanding first since it's the same three CLI commands you just ran locally in Steps 2 and 3, just scripted.

GitLab CI uses the same three commands — breakdown, diff, comment gitlab — inside a merge-request pipeline job. Set INFRACOST_API_KEY and a GITLAB_TOKEN (a project or group access token with api scope) as masked CI/CD variables, then add a job that runs only on merge request pipelines:

stages:
  - infracost

infracost_mr_comment:
  stage: infracost
  image:
    name: infracost/infracost:ci-latest
    entrypoint: [""]
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - infracost breakdown --path=/tmp/base/${TF_ROOT} \
                           --format=json \
                           --out-file=infracost-base.json
    - infracost diff --path=${TF_ROOT} \
                      --compare-to=infracost-base.json \
                      --format=json \
                      --out-file=infracost.json
    - infracost comment gitlab --path=infracost.json \
                                --repo=$CI_PROJECT_PATH \
                                --merge-request=$CI_MERGE_REQUEST_IID \
                                --gitlab-server-url=$CI_SERVER_URL \
                                --gitlab-token=$GITLAB_TOKEN \
                                --behavior=update

TF_ROOT is a CI/CD variable pointing at the relative path to your Terraform root module. The infracost/infracost:ci-latest image already has the CLI installed, which is why the job doesn't need a separate install step the way the GitHub Actions example does. Infracost's docs note the GitLab App integration as an alternative that's simpler to wire up than a hand-rolled job — worth checking if you'd rather not manage the token and job yourself.

A PR comment informs a reviewer; it doesn't stop a merge on its own. Once the team is used to seeing cost diffs, the next step is turning specific ones into enforcement — what Infracost and the wider FinOps community call cost policies or guardrails. There are two practical ways to implement this depending on how far you want to take it:

CI-native gating. Because infracost diff --format json outputs a machine-readable cost delta, a simple follow-up step in the same job can parse that JSON and fail the build if the total monthly delta exceeds a threshold you define — no additional product needed, just a small script (jq, Python, or your language of choice) reading fields like diffTotalMonthlyCost from the diff output and exiting non-zero when it's over budget.

Infracost Cloud policies. Infracost's hosted dashboard product (Infracost Cloud) adds policy-as-code checks on top of the CLI output — rules like "fail if a change adds more than $X/month" or "flag any new resource missing a required tag" — that run centrally rather than being hand-scripted per repo, and surface as pass/fail checks alongside the PR comment. If your team is already using Infracost's GitHub/GitLab integration and API key, this is the path of least resistance for org-wide policy consistency; see the current policy documentation at infracost.io/docs for the exact configuration format, since policy syntax has changed across CLI versions and is worth confirming against the version you're running.

Whichever mechanism you pick, calibrate thresholds so routine changes pass freely. A gate that blocks every third PR gets routed around; a gate that only fires on the genuinely expensive 5% of changes gets respected.

The posted comment shows, per project, the estimated monthly cost of the plan and — when run as a diff — the delta versus the baseline, broken down by resource. A reviewer scanning it should be able to answer three questions at a glance: what changed, how much it adds or removes per month, and which specific resource is driving the number. The resources that show up most often as the real cost driver are the same ones we flag in our cloud cost red flags post — oversized instances, redundant NAT Gateways, and databases provisioned above actual load.

If a resource in the plan isn't supported for pricing (a very new resource type, or one Infracost doesn't yet model), it's listed as skipped rather than silently omitted — pass --show-skipped to breakdown or diff to see that list explicitly, which matters when you're deciding whether to trust a "$0 change" result.

Every CLI command and flag in this tutorial was verified directly against a locally installed Infracost CLI (v0.10.x) via its own --help output, and against Infracost's and GitLab's published integration documentation. It deliberately avoids inventing exact dollar thresholds, specific policy-file syntax, or CLI flags that couldn't be confirmed — flag names and available commands do change across CLI versions, so run infracost breakdown --help, infracost diff --help, and infracost comment github --help yourself before wiring these into a production pipeline, and confirm current behavior against the docs below.

• Infracost documentation — infracost.io/docs
• infracost/actions (GitHub Action) — github.com/infracost/actions
• Infracost GitLab CI integration guide — infracost.io/docs/integrations/gitlab_ci
• Infracost CLI — github.com/infracost/infracost

Once a change is estimated and merged, tracking whether the actual bill matched the estimate is the next step — our cloud cost estimation guide covers that broader estimation workflow, and SpendArk's free cloud cost calculator is useful for modeling an architecture's cost before any Terraform exists at all.