DEV Community: Grafikui

I built a carbon linter for Terraform PRs — here's the full stack

Grafikui — Mon, 04 May 2026 08:05:22 +0000

Most cloud sustainability tools are built for sustainability officers.

They pull three-month-old billing data, run it through a proprietary model, and produce a PDF that engineers never see.

By the time you know your us-east-1 cluster emits twice as much as us-west-2 would have, it's been running for a quarter. The architecture is locked in. The carbon is already burnt.

The only moment you can actually change what gets deployed is the pull request.

So I built a tool that lives there.

What GreenOps CLI does

It's a GitHub Action that reads a terraform show -json plan output and posts a carbon and cost diff directly on the PR, across AWS, Azure, and GCP, before anyone clicks merge.

Here's what it posted on a real PR this week:


🌱 GreenOps Infrastructure Impact

Metric                    Monthly Total
Scope 2 — Operational     21.23 kg CO₂e
Scope 3 — Embodied         4.17 kg CO₂e
Total Lifecycle           25.40 kg CO₂e
Water Consumption          22.5 L
Infrastructure Cost       $280.32/month

Potential savings: −20.75 kg CO₂e/month (97.7%)
💡 3 recommendations found

Resource               Type         Region     Action
aws_instance.web       m5.xlarge    us-east-1  → eu-north-1
aws_instance.api       m5.large     us-east-1  → eu-north-1
aws_db_instance.main   db.m5.large  us-east-1  → eu-north-1

That 97.7% saving exists because eu-north-1 (Stockholm) runs on near-zero carbon electricity at 8.8g CO₂e/kWh. us-east-1 sits at 384.5g CO₂e/kWh. The same infrastructure. Forty-four times the emissions. GreenOps surfaces that before you ship it.

The math is open

Every number comes from a static factors.json ledger you can read in ten minutes. The formula:

W_cpu    = W_idle + (W_max − W_idle) × utilisation
W_memory = memory_gb × 0.392 W/GB     ← CCF v3 standard
W_total  = W_cpu + W_memory
energy_kwh = W_total × PUE × 730h / 1000
co2e_g     = energy_kwh × grid_intensity_gco2e_per_kwh

For m5.large in us-east-1 at 50% utilisation this produces 5,308g CO₂e/month. That value is asserted in engine.test.ts. You can verify it yourself from factors.json in under five minutes.

PUE differs by provider: AWS 1.13, Azure 1.125, GCP 1.10. Memory power draw is constant, DRAM draws near-constant power regardless of CPU utilisation, which is why memory-optimised instances carry disproportionately higher emissions than their vCPU count suggests.

The full methodology is at getgreenops.com/methodology. MIT-licensed. If you disagree with an assumption, open a PR.

It also posts inline suggestions

With post-suggestions: true, GreenOps posts a committable suggestion directly on the instance_type line in the PR diff.

The developer sees the suggestion in the Files changed tab. One click on "Commit suggestion" and the instance type is updated in place. No separate PR. No separate ticket. The carbon reduction is captured at the same moment the infrastructure decision is made.

It tracks history on the dashboard

Every run posts to getgreenops.com via an optional API key. The dashboard shows:

Total lifecycle CO₂e saved across all PRs
Trend chart over the last 90 days
Per-repository leaderboard
Per-run resource breakdown — every instance, every recommendation, every skipped resource with the reason why

Two lines of YAML

- name: GreenOps Carbon Analysis
  uses: omrdev1/greenops-cli@v0.7.0
  with:
    plan-file: plan.json
    github-token: ${{ secrets.GITHUB_TOKEN }}
    post-suggestions: true
    api-key: ${{ secrets.GREENOPS_API_KEY }}   # optional — enables dashboard

Requires only pull-requests: write. No cloud credentials. No outbound network calls from the CLI. Works in air-gapped and SOC 2 environments where SaaS carbon tools cannot be deployed.

You can also enforce carbon budgets

Add .greenops.yml to your repo root:

version: 1
budgets:
  max_lifecycle_co2e_kg: 10
  max_pr_cost_increase_usd: 500
fail_on_violation: true

fail_on_violation: true exits with code 1. The merge is blocked. The PR comment shows which constraint was breached and by how much.

Why this matters for CSRD

The EU Corporate Sustainability Reporting Directive requires large companies to report Scope 2 and Scope 3 emissions from 2024 onwards, with SMEs following from 2026.

Cloud infrastructure is one of the largest and fastest-growing sources of corporate Scope 2 emissions. Most companies have no mechanism to trace which team, which PR, which infrastructure decision drove which emission.

GreenOps creates that audit trail — per PR, per repository, per engineer — at the point where the decision was made. The methodology is CCF v3 aligned. Every formula is documented. Every number is testable.

Current coverage

✅ AWS — 40 instance types across 14 regions
✅ Azure — 16 instance types across 8 regions
✅ GCP — 15 instance types across 7 regions
✅ Scope 2 operational + Scope 3 embodied + water consumption
✅ ARM instance upgrade recommendations (Graviton, Ampere Altra, T2A)
✅ Region shift recommendations based on grid carbon intensity
⚠️ Lambda/serverless — flagged as unsupported, not silently ignored

Try it in 5 minutes

Fork github.com/omrdev1/greenops-e2e-demo — it has the workflow, a Terraform config with intentionally high-carbon instances, and runs without an AWS account. Open a PR and GreenOps runs automatically.

Or add it to any existing Terraform repo:

- name: GreenOps Carbon Analysis
  uses: omrdev1/greenops-cli@v0.7.0
  with:
    plan-file: plan.json
    github-token: ${{ secrets.GITHUB_TOKEN }}

No API key needed for the PR comment. The dashboard is optional.

→ github.com/omrdev1/greenops-cli
→ getgreenops.com
→ getgreenops.com/methodology

Built by Omar — Co-founder, Grafikui. Open source, MIT-licensed.

How I added carbon tracking to GitHub Actions (now with AWS, Azure, and GCP)

Grafikui — Fri, 20 Mar 2026 18:07:57 +0000

Updated March 2026: v0.5.x adds multi-cloud support (AWS + Azure + GCP), Scope 3 embodied carbon, water consumption tracking, inline PR suggestions, and policy budgets. Original post covered AWS-only v0.2.x.

Most carbon tracking tools are dashboards built for sustainability officers. They pull three-month-old billing data and produce a PDF. Engineers never see it.

This post is about shifting that left — into the pull request, before infrastructure is provisioned.

The problem with post-hoc measurement

By the time AWS's Carbon Footprint Tool tells you that your us-east-1 cluster emits twice as much as us-west-2 would have, it has been running for a quarter. The architecture is locked in, the carbon is burnt.

The only intervention point that changes what gets deployed is the PR.

What GreenOps CLI does

It's a GitHub Action that reads a terraform show -json plan output and posts a carbon and cost diff directly on the PR — across AWS, Azure, and GCP.

Here's what a developer sees on a multi-cloud plan:

🌱 GreenOps Infrastructure Impact

Metric                     | Monthly Total
Scope 2 — Operational CO2e | 12.27kg
Scope 3 — Embodied CO2e    | 3.13kg
Total Lifecycle CO2e       | 15.40kg
Water Consumption          | 12.8L
Infrastructure Cost        | $210.97/month

Potential Scope 2 Savings: -11.88kg CO2e/month (96.8%) | -$13.14/month
💡 Found 3 optimization recommendations.

Resource                           | Instance        | Region      | Scope 2 | Action
aws_instance.web                   | m5.large        | us-east-1   | 4.31kg  | UPGRADE
azurerm_linux_virtual_machine.api  | Standard_D2s_v3 | eastus      | 4.24kg  | UPGRADE
google_compute_instance.worker     | n2-standard-2   | us-central1 | 3.71kg  | UPGRADE

No cloud credentials required. No outbound network calls from the CLI. The emission factors are a static JSON file you can read in ten minutes.

How the math works

Three dimensions are tracked per resource.

Scope 2 — Operational (CPU power × grid intensity):

W = W_idle + (W_max - W_idle) × utilisation
energy_kwh = W × PUE × 730h / 1000
co2e_g = energy_kwh × grid_intensity_gco2e_per_kwh

PUE differs by provider: AWS 1.13, Azure 1.125, GCP 1.10.

Scope 3 — Embodied (hardware manufacturing, prorated):

embodied_g/month = (1,200,000g / 35,040h / 48 vCPUs) × vcpus × 730h
ARM discount: × 0.80  [Graviton, Ampere Altra, T2A]

Water consumption (data centre cooling):

water_litres = (W × 730h / 1000) × WUE_litres_per_kwh

For m5.large in us-east-1 at 50% utilisation, Scope 2 produces 4,313.57g CO2e/month. That value is asserted in engine.test.ts. You can verify it yourself from factors.json in under five minutes.

The full methodology — every formula, every assumption, every data source — is in METHODOLOGY.md and MIT-licensed.

Adding it to your workflow

- name: Generate Terraform Plan
  run: |
    terraform init
    terraform plan -out=tfplan
    terraform show -json tfplan > plan.json

- name: GreenOps Carbon Lint
  uses: omrdev1/greenops-cli@v0
  with:
    plan-file: plan.json
    github-token: ${{ secrets.GITHUB_TOKEN }}

Works with AWS, Azure, and GCP plans — provider is detected automatically from resource types.

Optional: inline suggestion comments

With post-suggestions: true, GreenOps posts a one-click committable suggestion directly on the instance_type / size / machine_type line in the PR diff:

- name: GreenOps Carbon Lint
  uses: omrdev1/greenops-cli@v0
  with:
    plan-file: plan.json
    github-token: ${{ secrets.GITHUB_TOKEN }}
    post-suggestions: true

The developer clicks "Commit suggestion" and the change is applied without leaving the PR.

Optional: policy budgets

Add .greenops.yml to your repo root to block merges that exceed a carbon or cost threshold:

version: 1
budgets:
  max_pr_co2e_increase_kg: 10
  max_pr_cost_increase_usd: 500
fail_on_violation: true

fail_on_violation: true exits with code 1. The merge is blocked. The PR comment shows which constraint was breached and by how much.

Current limitations

EC2, RDS, Azure VMs, and GCP Compute only. No Lambda, no ECS, no AKS.
71 instance types across the three providers. Unsupported instances are flagged as ⚠ UNKNOWN rather than silently showing zero.
Provider alias regions may not resolve — affected resources skip with a known_after_apply reason.
Annual average grid intensity. No real-time marginal emissions.

All of the above are tracked in open issues.

Why open source the methodology

Every other tool in this space uses proprietary emission factors. That doesn't survive a CSRD audit where a compliance officer needs to trace exactly how a number was produced.

If you disagree with an assumption, open a PR and change it.

→ github.com/omrdev1/greenops-cli

Saga Engine Go: Type-Safe Distributed Transactions with Zero Infrastructure

Grafikui — Tue, 27 Jan 2026 21:05:15 +0000

The Go port of Saga Engine. Compile-time step safety via generics, PostgreSQL persistence, and a 15-minute hard limit. No Temporal cluster required.

After shipping Saga Engine for Node.js, the most common request was a Go version. Not a wrapper. A native implementation that leverages what Go actually gives you: generics, context propagation, and compile-time safety.

Saga Engine Go is that implementation. Same guarantees. Different language idioms.

What's Different from the Node.js Version

This isn't a line-by-line port. Go changes the design in meaningful ways:

Concern	Node.js	Go
Type Safety	Runtime validation	Compile-time via `Step[T]` generics
Cancellation	`AbortController` (optional)	`context.Context` (first-class)
Concurrency	Single-threaded event loop	Goroutines + race detector
Step Results	`any` with runtime checks	Generic type parameter `T`

The Go version catches an entire class of bugs at compile time that the Node version can only catch at runtime.

1. The Core API: Generic Steps

Every step is parameterized by its return type. No interface{} casting. No runtime type assertions.

err = tx.Run(ctx, func(ctx context.Context, tx *saga.Transaction) error {
    // Step 1: Reserve inventory (returns string)
    reservationID, err := saga.Step(ctx, tx, "reserve-inventory", saga.StepDefinition[string]{
        IdempotencyKey: "order-123-inv",
        Execute: func(ctx context.Context) (string, error) {
            return inventory.Reserve(ctx, sku, qty)
        },
        Compensate: func(ctx context.Context, id string) error {
            return inventory.Release(ctx, id)
        },
    })
    if err != nil {
        return err
    }

    // Step 2: Charge payment (returns string)
    _, err = saga.Step(ctx, tx, "charge-payment", saga.StepDefinition[string]{
        IdempotencyKey: "order-123-pay",
        Execute: func(ctx context.Context) (string, error) {
            return gateway.Charge(ctx, amount)
        },
        Compensate: func(ctx context.Context, chargeID string) error {
            return gateway.Refund(ctx, chargeID)
        },
    })
    return err
})

The compensate function receives the exact type returned by execute. If Execute returns (string, error), Compensate receives string. The compiler enforces this.

2. The Context Mandate

Go's context.Context is the mechanism for timeout enforcement. The engine cancels the context when deadlines are exceeded. This only works if your functions cooperate.

// This respects cancellation
Execute: func(ctx context.Context) (string, error) {
    req, _ := http.NewRequestWithContext(ctx, "POST", url, body)
    resp, err := client.Do(req)
    // ...
}

// This ignores cancellation (timeouts become lies)
Execute: func(ctx context.Context) (string, error) {
    resp, err := http.Post(url, "application/json", body)
    // ...
}

The 15-minute execution limit and per-step timeouts are enforced via context cancellation. If you pass ctx to every I/O call, it works. If you don't, the engine has no way to interrupt your function.

3. Hard Guarantees

Same as the Node.js version, enforced at the library level:

Guarantee	Enforcement
Idempotency	Required. Returns `ErrIdempotencyRequired` if keys are missing at transaction or step level.
Durability	State committed to PostgreSQL before the next step executes.
Concurrency	`pg_try_advisory_lock` prevents double-execution across processes.
Time-Boxed	15-minute hard limit, checked before every step.
Visibility	Failed compensations move to `dead_letter` for manual audit via `saga-admin` CLI.

4. The JSON Serialization Contract

On crash recovery, step results are reconstructed from PostgreSQL via json.Unmarshal. This means your result types must follow Go's JSON serialization rules:

// Works: exported fields survive round-trip
type OrderResult struct {
    ID     string  `json:"id"`
    Amount float64 `json:"amount"`
}

// Broken on resume: unexported fields are silently zeroed
type badResult struct {
    id string  // json.Unmarshal cannot see this
}

This is a hard requirement, not a suggestion. If your step returns a struct with unexported fields, those fields will be zero-valued after a crash recovery. The saga will continue with corrupted state.

5. Error Handling the Go Way

All errors support errors.Is() and errors.As():

if errors.Is(err, saga.ErrExecutionTimeout) {
    // Workflow exceeded 15-minute limit
}

var compErr *saga.CompensationFailedError
if errors.As(err, &compErr) {
    log.Printf("Compensation failed at step: %s", compErr.FailedStep)
    log.Printf("Original error: %s", compErr.OriginalError)
}

Seven sentinel errors, seven corresponding error types with structured fields. Standard Go error handling, no custom error-checking patterns to learn.

6. PgBouncer Compatibility

Advisory locks are session-scoped. This matters for connection pooling:

Connection Setup	Compatible
`*sql.DB` (direct)	Yes
PgBouncer (session mode)	Yes
PgBouncer (transaction mode)	No

If you run PgBouncer in transaction mode, lock ownership is lost between queries. The engine won't warn you. Your workflows will silently lose mutual exclusion.

7. Explicit Refusals

Same philosophy as the Node.js version:

No workflows > 15 minutes. Use Temporal for long-running processes.
No auto-recovery from dead letters. If compensation fails, a human investigates. saga-admin retry <id> is intentionally manual.
No distributed transactions. Single-process, single-database. We coordinate side effects; we don't replace your DB's ACID properties.

8. CLI: saga-admin

Operational visibility without a dashboard:

# Build the CLI
go build -o saga-admin ./cmd/saga-admin

# List dead letter workflows
saga-admin -db "$DATABASE_URL" dead-letter

# Investigate a specific workflow
saga-admin -db "$DATABASE_URL" show order-123

# Retry after fixing the root cause
saga-admin -db "$DATABASE_URL" retry order-123

# View aggregate stats
saga-admin -db "$DATABASE_URL" stats

Setup

import (
    "database/sql"
    "os"
    saga "github.com/grafikui/saga-engine-go"
    _ "github.com/lib/pq"
)

db, _ := sql.Open("postgres", os.Getenv("DATABASE_URL"))
storage, _ := saga.NewPostgresStorage(db, "transactions")
lock := saga.NewPostgresLock(db)

tx, _ := saga.NewTransaction("order-123", storage, saga.TransactionOptions{
    IdempotencyKey: "order-123-v1",
    Lock:           lock,
    Input:          map[string]any{"orderId": "123"},
})

Single PostgreSQL table. No migrations framework required. The schema is in the README.

Conclusion

Saga Engine Go brings the same crash-resilient saga execution to the Go ecosystem. Type-safe generics, context-based cancellation, and a single PostgreSQL dependency.

If you're already using the Node.js version, the Go port follows the same mental model. If you're new to Saga Engine, pick whichever runtime your services are built on.

Links:

Star on GitHub

GitHub | pkg.go.dev

Sagas in Node.js Without the Heavy Lifting: Introducing Saga Engine

Grafikui — Tue, 27 Jan 2026 15:34:15 +0000

The Saga pattern is a lifesaver for data consistency across microservices, but implementation is often a choice between a mess of nested try/catch blocks or deploying a heavy orchestrator like Temporal.

Saga Engine is a crash-resilient, Postgres-backed executor for Node.js. It provides the core benefits of a distributed transaction coordinator with zero additional infrastructure.

1. The Logic: Clean, Atomic Workflows

We focus on the "No Magic" philosophy. You define steps; the engine guarantees execution or compensation.

await tx.run(async (t) => {
  // Step 1: Reserve inventory
  await t.step('reserve-inventory', {
    idempotencyKey: 'order-123-inv',
    execute: () => inventory.reserve(items),
    compensate: (res) => inventory.release(res.id),
  });

  // Step 2: Process payment via internal gateway
  await t.step('process-payment', {
    idempotencyKey: 'order-123-pay',
    execute: () => paymentGateway.charge(amount),
    compensate: (ch) => paymentGateway.refund(ch.transactionId),
  });
});

What Happens on Failure?
If process-payment fails:

process-payment execution stops immediately.
reserve-inventory.compensate() is automatically triggered using the result from its execute step.
The transaction is marked as failed.

2. Hard Guarantees

These aren't suggestions; they are enforced at the code level.

Guarantee	Enforcement
Idempotency	Required. Throws `IdempotencyRequiredError` if keys are missing.
Durability	State is persisted to Postgres before the next step starts.
Concurrency	Postgres advisory locks prevent double-execution across pods.
Time-Boxed	15-minute hard limit. Designed for high-integrity, short-lived workflows.
Visibility	Failed compensations move to a `dead_letter` state for manual audit.

3. Explicit Refusals

A professional tool is defined by its boundaries. Saga Engine is not for everything:

No Workflows > 15 Minutes: Use Temporal. We provide the upgrade path, not the bloat.
No Auto-Recovery from Dead Letters: If compensation fails, a human must investigate. Manual intervention via npx saga-admin retry prevents cascading failures.
No Distributed Transactions: We coordinate side effects; we do not replace your DB's native ACID properties.

"bin": {
  "saga-admin": "bin/saga-admin.js"
}

4. How It Compares

Feature	Saga Engine	Temporal	BullMQ
Infra	Postgres Only	Dedicated Cluster	Redis
Compensation	Native `compensate()`	Manual try/catch	Manual
Learning Curve	5 Minutes	1-2 Weeks	2 Days
Best For	API Orchestration	Long-running/Complex	Job Queues

5. Observability & Retries

Plug into your existing stack with 13 built-in hooks:

const tx = new Transaction('order-123', storage, {
  events: {
    onCompensationFailed: (name, err) => alerting.page(`Rollback failed: ${name}`),
    onDeadLetter: (id) => alerting.critical(`Manual intervention required: ${id}`),
  },
});

If a workflow enters dead_letter due to a downstream service outage, fix the issue and use the CLI:

npx saga-admin retry order-123

Quick Start: Setup

To keep your logic clean, move the initialization to your infrastructure layer.

import { Transaction, PostgresStorage, PostgresLock } from 'saga-engine';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const storage = new PostgresStorage(pool);
const lock = new PostgresLock(pool);

// Use this 'tx' instance in your services

Conclusion

Saga Engine v1.0.0 is production-ready. It fills the gap for teams that need saga semantics without the infrastructure tax.

Questions? Feedback? Found a bug?
Open an issue on GitHub or drop a comment below.

Star on GitHub

npm | GitHub | Docs