cost-guardrails 2.7.1

Cost Guardrails CI/CD validation CLI — shift-left cost governance for cloud infrastructure

Cost Guardrails CLI

Shift-left cost governance for CI/CD pipelines. One command validates your Terraform or CloudFormation plan against cost policies, budget limits, and guardrails — before infrastructure is deployed.

Note: A SKYXOPS subscription is required to use this CLI. This module can run as a standalone tool or be integrated into CI/CD pipelines.

Install

pip install cost-guardrails

Quick Start

# Set your API key
export COST_GUARDRAILS_API_KEY="your-api-key"

# Validate costs
cost-guardrails --plan plan.json --budget-code CS-FY2026-BU105-M03 --post-comment

Configuration

Env Variable	Description	Required
COST_GUARDRAILS_API_KEY	API authentication key	Yes
COST_GUARDRAILS_BUDGET_CODE	Budget code for validation (use --skip-budget for pricing-only)	No
COST_GUARDRAILS_TAG	Tag to identify this comment (e.g. production, staging)	No

API URL is built-in. Set COST_GUARDRAILS_API_URL only for custom deployments.

CI/CD Integration

Azure DevOps (Extension)

Install the Cost Guardrails extension from the VS Marketplace, then use the native task:

- task: Cost Guardrails@1
  inputs:
    planPath: plan.json
    budgetCode: $(COST_GUARDRAILS_BUDGET_CODE)
  env:
    COST_GUARDRAILS_API_KEY: $(COST_GUARDRAILS_API_KEY)
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

Full Azure DevOps Guide

GitHub Actions

- uses: skyxops-io/costguard-action@v1
  with:
    plan-path: plan.json
    api-key: ${{ secrets.COST_GUARDRAILS_API_KEY }}
    budget-code: ${{ secrets.COST_GUARDRAILS_BUDGET_CODE }}

Full GitHub Actions Guide

GitLab CI

include:
  - remote: 'https://gitlab.com/skyxops-io/cost-guardrails-templates/-/raw/v1/gitlab/cost-guardrails.yml'

cost-guardrails:
  extends: .cost-guardrails-review
  needs: [terraform-plan]

Full GitLab CI Guide

Any CI/CD Platform

- script: |
    pip install -q cost-guardrails
    cost-guardrails --plan plan.json --post-comment
  env:
    COST_GUARDRAILS_API_KEY: $(COST_GUARDRAILS_API_KEY)

Generic CI/CD Guide

Output Formats

Format	Flag	Use Case
Terminal	--format terminal	CI logs (default)
Markdown	--format markdown	PR/MR comments
HTML	--format html	Executive reports
JSON	--format json	Integrations

Exit Codes

Code	Decision	Pipeline Effect
0	ALLOW	Continues
1	BLOCK	Stops
2	WARN	Continues (use allow_failure: exit_codes: [2])
3	ERROR	Stops

Multi-Environment Tags

Use --tag to post separate comments for each Terraform root or environment in a single MR/PR:

cost-guardrails --plan prod/plan.json --tag production --post-comment
cost-guardrails --plan staging/plan.json --tag staging --post-comment

Each tag gets its own isolated comment. Without --tag, a single comment is posted. Set via env var: COST_GUARDRAILS_TAG.

Comment Behavior

--post-comment is idempotent: creates one comment on first run, updates it on re-push. No duplicates. Works on GitLab MRs, GitHub PRs, and Azure DevOps PRs.

How It Works

1. Reads plan file (Terraform plan.json or CloudFormation changeset)
2. Sends to Cost Guardrails API for pricing, budget validation, and guardrail checks
3. Displays cost breakdown, AI recommendations, and decision
4. Posts result as MR/PR comment (if --post-comment)
5. Exits with decision code so the pipeline can ALLOW, WARN, or BLOCK

No cloud credentials required — the CLI only reads the plan file.

Documentation

Doc	Description
Getting Started	Prerequisites, installation, quick start
CLI Reference	Complete flag and option reference
Architecture	Technical architecture, API flow, data model
Troubleshooting	Common issues across all platforms

Integration Guides

Platform	Guide
Azure DevOps	Native extension (Cost Guardrails@1 task)
GitHub Actions	Composite action (costguard-action@v1)
GitLab CI	Remote template (include: remote:)
Generic CI/CD	Raw CLI for any platform