CI/CD Integration

Add automatic cost estimation to every pull request. C3X integrates with all major CI/CD platforms. On GitHub, the comment shows the per-PR cost change versus the base branch; each example below includes the install step, estimate step, comment step, and a budget gate.

GitHub Actions

Add cost estimation to every pull request with two steps. No API key or secrets required.

name: Cost Estimation
on: [pull_request]

permissions:
  pull-requests: write
  contents: read

jobs:
  c3x:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: c3xdev/c3x@v0
        with:
          path: .

Branded PR Comments

By default the comment is posted by the github-actions bot. To post it as c3x-cloud[bot] with the C3X avatar instead, install the C3X Cloud GitHub App on the repository, add id-token: write to the workflow permissions, and set branded-comments: true. No secrets to store — the Action mints a short-lived, repo-scoped token over GitHub OIDC.

permissions:
  pull-requests: write
  id-token: write          # required for branded comments

jobs:
  c3x:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: c3xdev/c3x@v0
        with:
          path: .
          branded-comments: true

Per-PR Cost Delta

On a pull request the comment shows the cost change versus the base branch — not just the absolute total. The Action estimates the base branch automatically and renders a diff, e.g. Total: $533.16/mo → $1038.32/mo  🔺 +$505.16, with a per-resource breakdown of what changed. On a plain push (no base to compare against) it falls back to the absolute total.

Budget-Delta Gate

Use budget-delta to fail the check when a PR raises the monthly cost by more than a set amount versus the base branch — independent of the absolute budget cap. This catches expensive changes even when the project total is still under budget.

permissions:
  pull-requests: write
  id-token: write

jobs:
  c3x:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: c3xdev/c3x@v0
        with:
          path: .
          branded-comments: true
          budget-delta: "50"     # fail if this PR adds > $50/mo
          # budget: "1000"       # (optional) fail if the total exceeds $1000/mo

Outside the Action, the same gate is available directly from the CLI: c3x diff --baseline base.json --budget-delta 50 (save the baseline first with c3x estimate --save-baseline base.json).

GitLab CI

Add a cost-estimation stage to your .gitlab-ci.yml.

stages:
  - validate
  - cost-estimation
  - plan
  - apply

cost-estimation:
  stage: cost-estimation
  image: alpine:latest
  before_script:
    - apk add --no-cache curl tar
    - curl -fsSL https://c3x.dev/install.sh | sh
  script:
    # Posts the comment; project / MR / token auto-detect from GitLab CI
    - c3x comment gitlab --path .
    - c3x estimate --path . --budget 5000
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

The token is read from $GITLAB_TOKEN (or $CI_JOB_TOKEN) automatically — set a GITLAB_TOKEN variable with the api scope in Settings > CI/CD > Variables to write merge request comments.

Bitbucket Pipelines

Add a cost estimation step to your bitbucket-pipelines.yml.

pipelines:
  pull-requests:
    '**':
      - step:
          name: Cost Estimation
          image: alpine:latest
          script:
            # Install C3X
            - apk add --no-cache curl tar
            - curl -fsSL https://c3x.dev/install.sh | sh

            # Post PR comment (workspace / repo / PR auto-detect in CI)
            - c3x comment bitbucket --path .

            # Budget gate
            - c3x estimate --path . --budget 5000

Set BITBUCKET_USERNAME and BITBUCKET_APP_PASSWORD as repository or workspace variables (app password with pull-request read/write). c3x reads them automatically.

Azure Pipelines

Add a cost estimation job to your azure-pipelines.yml.

trigger: none

pr:
  branches:
    include:
      - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self

  - script: |
      curl -fsSL https://c3x.dev/install.sh | sh
    displayName: Install C3X

  - script: |
      c3x comment azuredevops --path .
    displayName: Post PR comment
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)

  - script: |
      c3x estimate --path . --budget 5000
    displayName: Budget gate

c3x reads the token from SYSTEM_ACCESSTOKEN (or AZURE_DEVOPS_TOKEN); org / project / repo / PR auto-detect from the Azure Pipelines environment. Ensure the build service account has Contribute to pull requests permission.

Atlantis

Run C3X as a custom workflow step in your atlantis.yaml (repo-level config). The cost estimate is posted as a comment alongside the Terraform plan.

version: 3
projects:
  - dir: .
    workflow: c3x

workflows:
  c3x:
    plan:
      steps:
        - init
        - plan
        - run: |
            c3x estimate --path $PLANFILE --format text
        - run: |
            c3x estimate --path $PLANFILE --budget 5000

Install C3X on the Atlantis server or use a custom Docker image that includes both Terraform and C3X. The $PLANFILE variable is set by Atlantis to point to the generated plan file.

Spacelift

Use C3X in a Spacelift before_apply hook to gate deployments on cost. You can also use before_plan to estimate costs before the plan runs.

# .spacelift/config.yml
version: "1"

before_plan:
  - |
    curl -fsSL https://c3x.dev/install.sh | sh

after_plan:
  - |
    c3x estimate --path . --format json > c3x.json

before_apply:
  - |
    c3x estimate --path . --budget 5000

The before_apply hook acts as a budget gate: if the estimate exceeds the threshold, C3X exits with code 1 and the apply is blocked. Cost data from the JSON output can be sent to external dashboards using Spacelift notifications.

Tips

• Use --format json > c3x.json to save the estimate for downstream steps or artifact storage.
• Use --budget for absolute cost gates and c3x diff --budget-delta for incremental cost gates.
• Provide a usage file for accurate estimates of variable-cost resources.
• For air-gapped CI environments, see the Self-Hosted & Offline guide.
• See the CLI Reference for the full list of flags available on each command.