Configuration reference

Where settings come from#

From highest to lowest precedence:

1. Dashboard settings, with an API key: thresholds, the BigQuery pricing model and Cost per TiB. The dashboard's pricing model and rate always win over the input and the file, so choose Editions in the dashboard, not only in the workflow. A dashboard threshold (for the repository, or the org-wide threshold) replaces the file's thresholds.
2. .diffcost.yml on the base branch.
3. Action inputs.

If the dashboard settings can't be fetched (the API key is rejected, the run is rate-limited, or the DiffCost service can't be reached), the run uses the file and the inputs. If the DiffCost service then accepts the results, its verdict (dashboard thresholds and your plan) still decides the status.

ignored_paths come only from .diffcost.yml, so file paths never reach the DiffCost service.

Action inputs#

What fail_on_error covers#

With fail_on_error: true, the step fails when:

• manifest_path or config_path is not a relative path without .., or base_ref is not a valid branch name, ref or SHA;
• on a merge-queue run, the queue branch has no PR number;
• .diffcost.yml can't be read or parsed, or has an invalid threshold;
• a git or dbt manifest error stops the analysis;
• the DiffCost service can't be reached, doesn't accept the results, or answers with something that isn't a DiffCost result (for example a proxy's page).

The step doesn't fail when the DiffCost service accepts the results but can't post the commit status (for example, the GitHub App is missing). DiffCost reports this in the comment and the log. Make diffcost/cost-check a required check so the PR waits in that case.

With false (the default), the step always passes, and DiffCost reports problems in the log, the PR comment and the job summary.

Action outputs#

Give the DiffCost step an id to use them in later steps; Monitoring has examples.

When policy_exceeded is evaluated#

• With an API key on Starter, Team or the trial.
• Whenever an API key is set but the dashboard settings couldn't be fetched (the key was rejected, the run was rate-limited, or the DiffCost service couldn't be reached). DiffCost then checks the .diffcost.yml thresholds on the runner, on any plan. If the DiffCost service then accepts the results, its verdict (dashboard thresholds and plan) replaces the local one, so a Free organization sees true only when the service also can't take the results.

Otherwise it is false: without an API key, and on the Free plan.

.diffcost.yml#

Place it in the repository root (or set config_path). DiffCost reads it from the PR's base commit, so editing the file in a PR doesn't change that PR's cost policy. After you merge an edit into the base branch, it applies to each open PR's next run triggered by a push (or by Update branch in GitHub); re-running an earlier job keeps the old file. To change the policy for a PR that's already blocked, merge the change in a separate PR first.

thresholds:
  absolute: 5.00   # USD per run, worst single query
  relative: 200    # percent, worst single query

# Runs per month used for the "≈$X/mo" projection (default 30)
default_runs_per_month: 30

ignored_paths:
  - "tests/**/*.sql"
  - "migrations/**/*.sql"

# Slack incoming webhook (paid plans), alerted when these thresholds are exceeded.
# GitHub does not expand ${{ }} inside repository files: DiffCost reads this variable
# from the DiffCost step's `env:` (see below).
slack_webhook: ${{ SLACK_WEBHOOK }}

# Optional overrides of the matching inputs
# bq_pricing_model: on_demand
# fail_on_error: false
# send_author: false

Thresholds in the file take effect only with an API key on a paid plan or the trial, and only when no dashboard threshold applies to the repository (see Which threshold applies). When the dashboard settings can't be fetched (key rejected, rate-limited or service unreachable), the Action also checks them on the runner, on any plan; that local check never posts a status. If the DiffCost service then accepts the results, its verdict applies (see When policy_exceeded is evaluated).

Passing secrets to the file#

GitHub doesn't expand ${{ }} in repository files. DiffCost replaces ${{ NAME }} in the slack_webhook value with the environment variable NAME from the DiffCost step (no other key is expanded), for these names only: SLACK_WEBHOOK, SLACK_WEBHOOK_URL and DIFFCOST_SLACK_WEBHOOK.

      - uses: diffcost/action@v1
        with:
          api_key: ${{ secrets.DIFFCOST_API_KEY }}
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}

Invalid values#

DiffCost ignores invalid values; most of them also produce a warning.

These make the cost policy weaker than configured. They appear in the log and in the cost report as "⚠️ Cost policy: …", and fail the step when fail_on_error: true:

• the file can't be read, isn't valid YAML, or isn't a mapping; thresholds isn't a mapping;
• a threshold that isn't a number or is outside its range (DiffCost drops it).

These only warn in the step's log, even with fail_on_error: true:

• default_runs_per_month outside 1 to 100,000 (DiffCost uses 30);
• a slack_webhook that isn't an https://hooks.slack.com/ URL, or that resolves to an empty value (no Slack alert is sent);
• an invalid bq_pricing_model (DiffCost uses on_demand, even over the input).

These are ignored without a warning: an ignored_paths that isn't a list, and a fail_on_error or send_author that isn't true or false.

Dashboard settings#

With an API key, the dashboard's Settings page sets the BigQuery pricing model, the Cost per TiB and the thresholds, and these win over the file and the inputs. See Using the dashboard.