Forem: Grafikui

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