Maintenance and updates

Update the Action#

DiffCost releases are tagged v1.2.3. The major tag v1 always points to the latest v1.x.y release, so a workflow with uses: diffcost/action@v1 gets fixes and new features automatically, without breaking changes. Pre-releases (such as v1.3.0-rc.1) never move v1. A new major version (v2) would need you to change the tag.

To control updates yourself, pin a release or a commit:

      - uses: diffcost/action@v1.2.3                                   # a fixed release
      - uses: diffcost/action@3f1c2a9e0d5b7c4e8a6f1b2d3c4e5f6a7b8c9d0e # a commit in diffcost/action

With a pin, let Dependabot propose updates:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly

The Action is a Docker action: GitHub builds it on the runner from its Dockerfile at each run, from a base image pinned by digest. Pinning a tag or a commit locks DiffCost's code, its base image and every Python package it installs: the build installs the exact versions in the Action's requirements.txt and checks each package's hash.

Every release is listed on the releases page.

Rotate an API key#

Several keys can be active at once, so you can rotate without a gap. Name each key after the secret that stores it (for example "warehouse repository: DIFFCOST_API_KEY"): GitHub secrets can't be read back, so the name is how you find where a key is used.

1. In the dashboard, open Settings → GitHub Action API keys and click Create API key, with the same repository scope as the old key.
2. Update the DIFFCOST_API_KEY secret (and the Dependabot secret) wherever the old key is used.
3. Re-run DiffCost on an open pull request (PR) and check that the new key's Last used updates. It updates at most every 5 minutes.
4. Click Revoke next to the old key.

A revoked key stops working at once: workflows still using it keep posting PR comments but get no diffcost/cost-check status. Keys don't expire, so rotate them on your own schedule, and whenever someone who handled a key leaves. If you can't tell which keys someone handled, rotate every key.

To change a key's repository scope, create a new key with the new scope and rotate as above.

Rotate Google Cloud credentials#

• Workload Identity Federation: nothing to rotate; each job gets short-lived credentials.

• Service account key:

  1. Create a new key: gcloud iam service-accounts keys create.
  2. Update the GCP_SA_KEY secret (and the Dependabot secret, if you added one).
  3. Re-run DiffCost on a PR and check that costs appear.
  4. Delete the old key: gcloud iam service-accounts keys delete.

  Consider switching to Workload Identity Federation instead.

If your SQL starts reading new datasets, grant the service account roles/bigquery.dataViewer on them, or those queries show "Access Denied".

Change thresholds and pricing#

• Dashboard thresholds and pricing apply from the next DiffCost run. DiffCost doesn't recompute past runs or their statuses: re-run the DiffCost job on an open PR to re-evaluate it.
• .diffcost.yml changes apply once they're merged into the base branch, because DiffCost reads the file from the PR's base commit. Make the change in a separate PR to the base branch. After it merges, an open PR picks it up on its next push (or when you click Update branch on GitHub). Re-running an old job keeps the base it ran with, and so the old file.
• Precedence: a dashboard threshold for the repository, or the org-wide threshold (scope *), replaces the file's thresholds. See Which threshold applies.

Add a repository#

1. Add the DiffCost workflow (see the Quickstart). For dbt, add the main-branch manifest workflow too.
2. Workload Identity Federation: add the roles/iam.workloadIdentityUser binding for the new repository (step 3).
3. API key: add the DIFFCOST_API_KEY secret, and the Dependabot secret. If your key lists specific repositories, create a key whose scope includes the new one (or use an organization secret with a * key).
4. GitHub App: if it's installed on selected repositories, add the new one.
5. Open a PR, check the comment and the status, then make diffcost/cost-check required for the new repository.

Keep the dbt baseline fresh#

• Keep the scheduled run in the main-branch manifest workflow: artifacts expire (90 days at most by default), and without a baseline, PRs that modify existing models show Cost unavailable.
• If you move the dbt project or rename the artifact, update both workflows together.
• After a failed main-branch run, run it again: PRs compare against the most recent artifact. GitHub only allows re-running recent runs; otherwise start the workflow from the Actions tab, or merge a change to the base branch.

People and access#

• Add someone: they sign in at diffcost.dev with GitHub, as a member of your GitHub organization. They get a seat if one is free. If your organization restricts OAuth App access, a GitHub organization owner approves DiffCost once first.
• Roles come from GitHub. Make someone a DiffCost admin by making them a GitHub organization owner; it applies at their next DiffCost sign-in. The same goes the other way: a demoted owner keeps admin rights until they sign in again (sessions last 72 hours), unless you remove them on the Team page.
• When someone leaves:
  1. Remove them from the GitHub organization.
  2. Click Remove next to them on the dashboard's Team page. This ends their access and frees their seat at once. Leaving the GitHub organization alone doesn't free the seat.
  3. If they created or copied API keys, rotate those keys. If you can't tell, rotate every key.
• Over the seat limit: remove members who no longer need the dashboard, or upgrade. See Seats.

Change plans#

Subscribe, switch between Starter and Team, or cancel from the dashboard's Billing page. See Plans and billing.

Remove DiffCost#

From one repository:

1. Remove diffcost/cost-check from the required checks first; otherwise open PRs wait for a status that never comes.
2. Delete the DiffCost workflow (and the dbt manifest workflow, if it only exists for DiffCost).
3. Delete the DIFFCOST_API_KEY and GCP_SA_KEY secrets, including the Dependabot secrets.
4. Workload Identity Federation: remove the repository's roles/iam.workloadIdentityUser binding on the service account.
5. GitHub App: if it's installed on selected repositories, remove the repository from the selection.

From the whole organization, also:

6. Revoke every API key on the dashboard's Settings page.
7. Cancel the subscription on the Billing page (or in the Google Cloud console for Marketplace).
8. Uninstall the DiffCost GitHub App in your GitHub organization's settings (GitHub Apps → DiffCost → Configure → Uninstall).
9. In the GitHub organization's settings, remove DiffCost's OAuth App approval (Third-party access → OAuth app policy). Each person can also revoke DiffCost's sign-in access under their own GitHub Settings → Applications → Authorized OAuth Apps.
10. In Google Cloud, delete the diffcost-ci service account and, if nothing else uses them, the workload identity pool and provider.
11. To have your organization's data deleted from DiffCost, email support@diffcost.dev from an admin's address.