CloudExpat Cost Report Action

Automatically post cloud cost reports with savings insights, budget tracking, and carbon footprint to your Pull Requests.

Features

• Cost Health Score — A-F grade showing your cloud cost health at a glance
• Savings Opportunities — Top optimization insights ranked by potential savings
• Budget Tracking — Burn rate, projections, and overrun alerts
• Carbon Footprint — Environmental impact of your cloud usage
• Multi-Cloud — AWS, Azure, and GCP support

Usage

name: CloudExpat Cost Report

on:
  pull_request:
  workflow_dispatch:

permissions:
  pull-requests: write

jobs:
  cost-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: CloudExpat/cost-report@v1
        with:
          api-key: ${{ secrets.CLOUDEXPAT_API_KEY }}

That's it! The action will post a cost report comment on every PR.

Example Output

## ☁️ CloudExpat Cost Report

**Cost Health: C** · $4.3K/wk · ↑12.4% · 3 savings opportunities ($890/mo)

<details>
<summary>💰 Cost Summary ($4.3K this week, +$470 vs last week)</summary>

| Account | Provider | This Week | Change |
|---------|----------|----------:|-------:|
| Production | AWS | $3200.00 | +8.2% |
| Staging | Azure | $780.00 | +28.1% ⚠️ |
| Analytics | GCP | $300.00 | -2.0% |

</details>

<details>
<summary>🔍 Top Savings Opportunities — $890/mo potential</summary>

| # | Issue | Resource | Savings | Priority |
|---|-------|----------|--------:|----------|
| 1 | Oversized Instances | `i-0abc123` (m5.2xlarge) | $420/mo | 🔴 High |
| 2 | Dev/Test Always-On | `i-0def456` | $310/mo | 🟡 Medium |
| 3 | Unattached EBS Volumes | `vol-0789abc` | $160/mo | 🟡 Medium |

[View all insights →](https://app.cloudexpat.com/dashboard/optimization)

</details>

<details>
<summary>📊 Budget Status — $34,200 / $50,000 (68%)</summary>

**Monthly Budget**: $34,200 of $50,000 used (68.4%)
**Burn Rate**: $1,710/day · **Projected**: $51,200 (+$1,200 over budget)
**Days Remaining**: 12

</details>

<details>
<summary>🌱 Carbon Footprint (331 kgCO2e, +7.1%)</summary>

| Account | Current | Change |
|---------|--------:|-------:|
| Production | 245 kgCO2e | +11.4% |
| Staging | 34 kgCO2e | -10.5% |
| Analytics | 52 kgCO2e | +2.0% |

</details>

Setup

1. Get Your API Key

1. Log in to CloudExpat
2. Go to Settings > API Keys
3. Click Create API Key
4. Copy the key (starts with ce_live_)

2. Add the Secret

1. In your GitHub repository, go to Settings > Secrets and variables > Actions
2. Click New repository secret
3. Name: CLOUDEXPAT_API_KEY
4. Value: Paste your API key

3. Create the Workflow

Create .github/workflows/cloudexpat.yml with the usage example above.

4. (Optional) Add Config File

Create .cloudexpat.yml in your repo root to scope reports to a specific service:

service: payments-api
tags:
  service: payments
  environment: production

Inputs

Input	Description	Required	Default
api-key	Your CloudExpat API key	Yes	-
api-url	API URL (for testing)	No	https://data.cloudexpat.com
post-comment	Post as PR comment	No	true
service	Service name to scope the report	No	-
tags	Resource tags to filter (format: key:value,key:value)	No	-
config-file	Path to .cloudexpat.yml	No	.cloudexpat.yml

Outputs

Output	Description
report-file	Path to the generated report file
success	Whether the report was fetched successfully

Configuration Options

Scope by Service

- uses: CloudExpat/cost-report@v1
  with:
    api-key: ${{ secrets.CLOUDEXPAT_API_KEY }}
    service: payments-api

Filter by Tags

- uses: CloudExpat/cost-report@v1
  with:
    api-key: ${{ secrets.CLOUDEXPAT_API_KEY }}
    tags: 'environment:production,team:platform'

Run on Schedule

on:
  schedule:
    - cron: '0 9 * * 1'  # Weekly on Monday 9am UTC

Run on Push to Main

on:
  push:
    branches: [main]

Disable PR Comments

- uses: CloudExpat/cost-report@v1
  with:
    api-key: ${{ secrets.CLOUDEXPAT_API_KEY }}
    post-comment: 'false'

.cloudexpat.yml Reference

# Service name — scopes the report to resources tagged with this service
service: my-service

# Tag filters — only include resources matching these tags
tags:
  environment: production
  team: platform

Troubleshooting

"CloudExpat API key is required"

Add the CLOUDEXPAT_API_KEY secret to your repository settings.

"Failed to fetch report. HTTP 401"

Your API key is invalid or expired. Generate a new one at app.cloudexpat.com.

"Failed to fetch report. HTTP 403"

No cloud accounts connected. Add at least one AWS, Azure, or GCP account in CloudExpat.

No PR comment appears

Ensure your workflow has pull-requests: write permission.

No insights showing

Insights are generated after CloudExpat analyzes your resources. This happens automatically within 24 hours of connecting a cloud account.

Security

• Store API keys only in GitHub Secrets
• The action requires minimal permissions (pull-requests: write)
• Revoke API keys anytime from the CloudExpat dashboard

Note on Fork PRs: GitHub does not expose secrets to workflows triggered by PRs from forks. This action will only post comments on PRs from branches within the same repository.

Links

• CloudExpat Dashboard
• Documentation
• Report Issues

License

MIT License - see LICENSE for details.