gitgreen 1.1.3 → 1.4.0

package/README.md

@@ -1,279 +1,383 @@
-# GitGreen CLI
+<p align="center">
+  <h1 align="center">GitGreen</h1>
+  <p align="center">
+    <strong>Carbon footprint tracking for GitLab CI/CD pipelines</strong>
+  </p>
+  <p align="center">
+    <a href="#quick-start">Quick Start</a> •
+    <a href="#installation">Installation</a> •
+    <a href="#usage">Usage</a> •
+    <a href="#methodology">Methodology</a> •
+    <a href="#faq">FAQ</a>
+  </p>
+</p>
+
+---
+
+[![npm version](https://img.shields.io/npm/v/gitgreen.svg)](https://www.npmjs.com/package/gitgreen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-20+-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+GitGreen measures the carbon emissions of your CI/CD jobs using real CPU/RAM metrics, grid carbon intensity data, and research-backed power models. Works with **GCP** and **AWS** runners.
 
-Self-contained carbon calculation CLI for GitLab jobs (no API server). It reuses the same power profiles and budget reporting as the existing implementation, pulls Electricity Maps intensity, and can post Merge Request notes via `CI_JOB_TOKEN`. Works with both GCP and AWS runners.
+```
+Total emissions: 2.847 gCO₂e
+├── CPU:     1.923 gCO₂e
+├── RAM:     0.412 gCO₂e
+└── Scope 3: 0.512 gCO₂e (embodied carbon)
+```
 
-## Prerequisites
+## Quick Start
 
-Before installing GitGreen CLI, ensure you have the following installed and configured:
+```bash
+# Install globally
+npm install -g gitgreen
 
-### Required
+# Initialize in your GitLab project
+cd your-repo
+gitgreen init
+```
 
-- **Node.js** (v20 or higher) - [Download](https://nodejs.org/)
-  - Required to run the CLI tool
-  - Check version: `node --version`
+The wizard configures everything: provider credentials, carbon budgets, and CI/CD integration.
 
-- **npm** or **pnpm** - Package manager (comes with Node.js)
-  - This project uses `pnpm@8.15.4` as the package manager
-  - Install pnpm: `npm install -g pnpm`
+## Table of Contents
 
-- **Git** - [Download](https://git-scm.com/)
-  - Required for detecting GitLab project information during initialization
-  - Check version: `git --version`
+- [Installation](#installation)
+- [Usage](#usage)
+- [Advanced](#advanced)
+  - [Providers](#providers)
+  - [Output Integrations](#output-integrations)
+  - [Database Schema](#database-schema)
+- [Methodology](#methodology)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+- [References](#references)
+- [License](#license)
 
-### Cloud Provider CLIs (Required based on provider)
+## Installation
 
-- **Google Cloud SDK (gcloud CLI)** - [Installation Guide](https://cloud.google.com/sdk/docs/install-sdk)
-  - Required for GCP provider setup and authentication
-  - After installation, authenticate: `gcloud auth login`
-  - Set default project: `gcloud config set project YOUR_PROJECT_ID`
-  - Check version: `gcloud --version`
+### Prerequisites
 
-- **AWS Credentials** - [AWS CLI Installation](https://aws.amazon.com/cli/) (optional, but recommended)
-  - Required for AWS provider (can use environment variables or AWS CLI config)
-  - Configure credentials: `aws configure`
-  - Or set environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | 20+ | [Download](https://nodejs.org/) |
+| Git | Any | For GitLab project detection |
+| gcloud CLI | Any | Required for GCP ([Install](https://cloud.google.com/sdk/docs/install-sdk)) |
+| AWS CLI | Any | Required for AWS ([Install](https://aws.amazon.com/cli/)) |
+| glab CLI | Any | Optional, for easier GitLab auth ([Install](https://docs.gitlab.com/cli/)) |
 
-### Optional (but recommended)
+### Install
 
-- **GitLab CLI (glab)** - [Installation Guide](https://docs.gitlab.com/cli/)
-  - Recommended for easier GitLab authentication and CI/CD variable management
-  - After installation, authenticate: `glab auth login`
-  - Check version: `glab --version`
-  - If not installed, you'll need to provide a GitLab Personal Access Token manually
+```bash
+npm install -g gitgreen
+```
 
 ### API Keys
 
-- **Electricity Maps API Key** - [Get free key](https://api-portal.electricitymaps.com)
-  - Required for carbon intensity data
-  - You'll be prompted for this during `gitgreen init`
+- **Electricity Maps** (required): [Get free API key](https://api-portal.electricitymaps.com)
 
-## Install
-- From npm (global CLI):
-  ```bash
-  npm install -g gitgreen
-  gitgreen --help
-  ```
+## Usage
 
-Run tests:
-```bash
-npm test
-```
+### Initialize a Project
 
-Stress test multiple live configs (build first, real APIs):
 ```bash
-npm build
-npm stress
+gitgreen init
 ```
 
-## Usage
+The wizard will:
+1. Configure your cloud provider (GCP/AWS)
+2. Set machine type and region
+3. Configure carbon budgets
+4. Set up database exports (optional)
+5. Append the tracking job to `.gitlab-ci.yml`
+6. Store credentials in GitLab CI/CD variables
 
-### Initializing a New GitLab Project
+**That's it!** Run your next pipeline and carbon emissions will be calculated automatically. Results appear as MR comments, in your configured database, and are stored in carbon job artifacts.
 
-To get started with carbon tracking in any GitLab project (any project with a remote pointing to a GitLab instance), run:
+---
 
-```bash
-# In your repo
-gitgreen init
-```
+## Advanced
 
-The initialization wizard will guide you through the setup process:
-- Configure provider/machine/region settings
-- Set carbon budgets
-- Configure MR note preferences
-- Choose to use an existing runner or spin up a new one with supported providers
+### Providers
 
-After initialization, the wizard will:
-- Append a ready-made job to your `.gitlab-ci.yml`
-- Print the CI/CD variable checklist (ELECTRICITY_MAPS_API_KEY, provider credentials, budget flags)
+| Provider | Metrics Source | Status |
+|----------|---------------|--------|
+| **GCP** | Cloud Monitoring API | Full support |
+| **AWS** | CloudWatch API | Full support |
 
-### How It Works
+### Output Integrations
 
-Once initialized, all subsequent pipelines will run on the configured runner, and their performance will be automatically measured. The carbon tracking is implemented using GitLab CI/CD components as a final step in your pipeline. The carbon tracking job itself is not computationally expensive, so it adds minimal overhead to your CI/CD workflows.
+Export carbon data to external databases for analytics and dashboards.
 
-Key environment variables:
-- `ELECTRICITY_MAPS_API_KEY` (required) - Get a free key from https://api-portal.electricitymaps.com
-- `GCP_PROJECT_ID` / `GOOGLE_CLOUD_PROJECT` (required for GCP) - Your GCP project ID
-- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (required for AWS CloudWatch) - Credentials with CloudWatch read access on the runner
-- `AWS_REGION` (for AWS) - Region of the runner EC2 instance
+#### Supported Connectors
 
-The `gitgreen init` wizard will automatically set all necessary GitLab CI/CD variables for you.
+| Connector | Job Data | Runner Inventory |
+|-----------|----------|------------------|
+| MySQL | `GITGREEN_JOB_MYSQL_*` | `GITGREEN_RUNNER_MYSQL_*` |
+| PostgreSQL | `GITGREEN_JOB_POSTGRES_*` | `GITGREEN_RUNNER_POSTGRES_*` |
 
-## Providers
+#### Database Migrations
 
-GitGreen supports multiple cloud providers:
+```bash
+gitgreen migrate --scope job      # Job emissions tables
+gitgreen migrate --scope runner   # Runner inventory tables
+gitgreen migrate --scope all      # Both
+```
 
-- **GCP**: Fully wired — the CLI parser expects GCP Monitoring JSON, the GitLab component polls GCE metrics, and `gitgreen init` provisions or reuses GCP runners.
-- **AWS**: CloudWatch-backed — the CLI can pull metrics directly via `--from-cloudwatch`, the GitLab component fetches CloudWatch CPU/RAM data, and `gitgreen init` can configure or provision EC2 runners.
+Migrations run automatically in CI pipelines.
+
+### Database Schema
+
+<details>
+<summary><strong>Job Table</strong> (per-job emissions)</summary>
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | BIGSERIAL | Primary key |
+| `ingested_at` | TIMESTAMPTZ | Insert timestamp |
+| `provider` | TEXT | `gcp` or `aws` |
+| `region` | TEXT | Cloud region/zone |
+| `machine_type` | TEXT | Instance type |
+| `runtime_seconds` | INT | Job duration |
+| `total_emissions` | DOUBLE | Total gCO₂eq |
+| `cpu_emissions` | DOUBLE | CPU gCO₂eq |
+| `ram_emissions` | DOUBLE | RAM gCO₂eq |
+| `scope3_emissions` | DOUBLE | Embodied gCO₂eq |
+| `carbon_intensity` | DOUBLE | Grid intensity (gCO₂eq/kWh) |
+| `pue` | DOUBLE | Power Usage Effectiveness |
+| `carbon_budget` | DOUBLE | Budget threshold |
+| `over_budget` | BOOLEAN | Budget exceeded |
+| `gitlab_project_id` | BIGINT | GitLab project |
+| `gitlab_pipeline_id` | BIGINT | Pipeline ID |
+| `gitlab_job_id` | BIGINT | Job ID |
+| `gitlab_job_name` | TEXT | Job name |
+| `payload` | JSONB | Full result JSON |
+
+</details>
+
+<details>
+<summary><strong>Timeseries Table</strong> (CPU/RAM metrics)</summary>
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | BIGSERIAL | Primary key |
+| `job_id` | BIGINT | Foreign key to job |
+| `metric` | TEXT | `cpu`, `ram_used`, `ram_size` |
+| `ts` | TIMESTAMPTZ | Timestamp |
+| `value` | DOUBLE | Metric value |
+
+</details>
+
+<details>
+<summary><strong>Runner Inventory Table</strong></summary>
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | BIGSERIAL | Primary key |
+| `runner_id` | TEXT | GitLab runner ID |
+| `machine_type` | TEXT | Instance type |
+| `provider` | TEXT | Cloud provider |
+| `region` | TEXT | Region |
+| `last_job_total_emissions` | DOUBLE | Last job emissions |
+| `payload` | JSONB | Full metadata |
+
+</details>
+
+## Methodology
+
+GitGreen's calculations are based on peer-reviewed methodologies from [re:cinq](https://re-cinq.com/blog/cloud-cpu-energy-consumption) and [Teads](https://github.com/re-cinq/emissions-data).
+
+### Formula
 
-## Architecture
-Runtime flow:
-```
-CPU/RAM timeseries (GCP Monitoring JSON or custom collector)
-        |
-        v
-+------------------+    +----------------------------+
-| CLI (gitgreen)   |--->| CarbonCalculator           |
-| - parse metrics  |    | - PowerProfileRepository   |<- machine data in data/*.json
-| - CLI/env opts   |    | - ZoneMapper (region→zone) |<- static + runtime PUE mapping
-+------------------+    | - IntensityProvider        |<- Electricity Maps API
-                         +-------------+------------+
-                                       |
-                                       v
-                        +-----------------------------+
-                        | Report formatter            |
-                        | - Markdown/JSON artifacts   |
-                        | - Budget evaluation         |
-                        +-------------+---------------+
-                                       |
-                                       v
-                        +-----------------------------+
-                        | GitLab client (optional)    |
-                        | - MR note via CI_JOB_TOKEN  |
-                        +-----------------------------+
 ```
+E_total = E_operational + E_embodied
 
-GitLab CI path:
-```
-Pipeline starts → component script fetches CPU/RAM timeseries from GCP Monitoring or AWS CloudWatch
-              → writes JSON files → runs `gitgreen --provider gcp|aws ...`
-              → emits `carbon-report.md` / `carbon-report.json`
-              → optional MR note when CI_JOB_TOKEN is present
+E_operational = (P_cpu + P_ram) × runtime_hours × PUE × carbon_intensity
+E_embodied    = scope3_hourly × runtime_hours
 ```
 
-## Output Integrations
+| Variable | Description | Source |
+|----------|-------------|--------|
+| `P_cpu` | CPU power (kW) | Interpolated from utilization |
+| `P_ram` | RAM power (0.5 W/GB) | Industry standard for DDR4 |
+| `PUE` | Data center efficiency | Google/AWS published data |
+| `carbon_intensity` | Grid emissions (gCO₂eq/kWh) | Electricity Maps API |
+| `scope3_hourly` | Embodied carbon rate | Dell R740 LCA study |
 
-During `gitgreen init` you can opt into exporting GitGreen data to external systems. The wizard includes an integration step with two optional sinks:
+### CPU Power Model
 
-- **Per-job carbon data** – emissions, runtime, and runner tags for every CI job.
-- **Runner inventory** – the machine catalog that powers your GitLab runners, including machine type and scope 3 estimates.
+CPU power is **non-linear** with utilization. We use cubic spline interpolation across measured data points:
 
-Built-in connectors today:
-- **MySQL** – populates `GITGREEN_JOB_MYSQL_*` / `GITGREEN_RUNNER_MYSQL_*` and inserts rows through a standard MySQL client.
-- **PostgreSQL** – captures host, port, credentials, schema, table, and SSL mode (`GITGREEN_JOB_POSTGRES_*` / `GITGREEN_RUNNER_POSTGRES_*`) for storage in Postgres.
+| Utilization | Power (% of TDP) |
+|-------------|------------------|
+| 0% (idle) | 1.7% |
+| 10% | 3.4% |
+| 50% | 16.9% |
+| 100% | 100% |
 
-When you select either connector, the wizard captures host, port, username, password, database, and target table names and stores them in CI/CD variables. It immediately connects with those credentials to ensure the database, schema, and table exist (job sinks also create a `<table>_timeseries` table linked via foreign key). During CI, the GitGreen CLI automatically detects those env vars and:
+**VM Power Correction:** Cloud VMs share physical CPUs. We scale power by the ratio of VM vCPUs to physical threads:
 
-- runs `gitgreen migrate --scope job|runner` to apply any pending migrations (tracked per DB via `gitgreen_migrations`);
-- writes each carbon calculation (typed summary columns plus CPU/RAM timeseries rows) and optional runner inventory snapshot into the configured sink.
+```
+P_vm = TDP × ratio × (vm_vcpus / physical_threads)
+```
 
-### Extending the interface
+| CPU | Cores | Threads | TDP | Source |
+|-----|-------|---------|-----|--------|
+| Intel Xeon Gold 6268CL | 24 | 48 | 205W | [Intel](https://www.ebay.com/p/2321792675) |
+| Intel Xeon Platinum 8481C | 56 | 112 | 350W | [TechPowerUp](https://www.techpowerup.com/cpu-specs/xeon-platinum-8481c.c3992) |
+| AMD EPYC 7B12 | 64 | 128 | 240W | [AMD](https://www.newegg.com/p/1FR-00G6-00026) |
+| Ampere Altra Q64-30 | 64 | 64 | 180W | [Ampere](https://amperecomputing.com/en/briefs/ampere-altra-family-product-brief) |
 
-Additional connectors can be added without touching the wizard logic. Each destination implements the `OutputIntegration` interface in `src/lib/integrations/output-integrations.ts`, which specifies:
+### Scope 3 (Embodied Carbon)
 
-1. Display metadata (`id`, `name`, `description`)
-2. The data target it handles (`job` vs `runner`)
-3. Prompted credential fields (label, env var key, input type, default, mask flag)
+Manufacturing emissions amortized over hardware lifespan (6 years):
 
-To add another sink (for example PostgreSQL or a webhook), create a new entry in that file with the fields your integration needs. Re-run `gitgreen init` and the option will automatically appear in the integration step.
+| Component | Emissions |
+|-----------|-----------|
+| Base server | ~1000 kgCO₂eq |
+| Per CPU | ~100 kgCO₂eq |
+| Per 32GB DIMM | ~44 kgCO₂eq |
+| Per SSD | ~50-100 kgCO₂eq |
 
-### Database migrations
+*Source: Dell PowerEdge R740 Life Cycle Assessment*
 
-Structured sinks rely on migrations tracked in `gitgreen_migrations`. Run them whenever you update GitGreen or change table names:
+### Accuracy & Limitations
 
-```bash
-gitgreen migrate --scope job      # apply job sink migrations (summary + timeseries)
-gitgreen migrate --scope runner   # apply runner inventory migrations
-gitgreen migrate --scope all      # convenience wrapper (used by the GitLab component)
-```
+**Expected Accuracy:**
+- Relative comparisons: Excellent (comparing job A vs B)
+- Absolute values: ±15-25% for CPU-bound workloads
 
-The GitLab component automatically runs `gitgreen migrate --scope job` and `--scope runner` before calculating emissions, so pipelines stay in sync even when you change versions.
+**Known Limitations:**
 
-## Adding a provider
-1. Extend `CloudProvider` and the provider guard in `src/index.ts` so the calculator accepts the new key.
-2. Add machine power data (`<provider>_machine_power_profiles.json`) and, if needed, CPU profiles to `data/`, then update `PowerProfileRepository.loadMachineData` to load it.
-3. Map regions to Electricity Maps zones and a PUE default in `ZoneMapper` (or via `data/runtime-pue-mappings.json` for runtime overrides).
-4. Parse that provider's metrics into the `TimeseriesPoint` shape (timestamp + numeric value) alongside RAM size/usage, and update the CLI/init/templates to pull those metrics.
-5. Wire any CI automation (runner tags, MR note flags) to pass the correct provider, machine type, and region strings.
+| Limitation | Impact | Notes |
+|------------|--------|-------|
+| No GPU modeling | High | GPU jobs underestimated |
+| Fixed RAM power | Low | 0.5 W/GB industry standard |
+| No network/storage I/O | Low | <5% of typical job power |
 
-## Publish
-- Ensure version bump in `package.json`
-- Run `pnpm -C node-module build && pnpm -C node-module test`
-- Publish: `pnpm -C node-module publish --access public`
+## Architecture
 
-## FAQ
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        GitLab Pipeline                      │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐    ┌──────────────────────────────────┐    │
+│  │ Your Jobs   │───▶│ GitGreen Carbon Tracking Job     │    │
+│  └─────────────┘    │  ├─ Fetch CPU/RAM metrics        │    │
+│                     │  ├─ Calculate emissions          │    │
+│                     │  ├─ Post MR comment              │    │
+│                     │  └─ Export to database           │    │
+│                     └──────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+         ┌────────────────────┼────────────────────┐
+         ▼                    ▼                    ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│ GCP Monitoring  │  │ Electricity Maps│  │ MySQL/Postgres  │
+│ AWS CloudWatch  │  │ API             │  │ (optional)      │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+```
 
-### Are my API keys and credentials secure?
+## Configuration
 
-Yes. GitGreen does not save your keys locally. During `gitgreen init`, all sensitive credentials (API keys, service account keys, AWS credentials) are stored only in GitLab CI/CD variables, which are encrypted and managed by GitLab. The CLI never writes credentials to disk on your local machine.
+### Adding a New Provider
 
-### Does GitGreen call any third-party APIs?
+1. Add machine power profiles to `data/<provider>_machine_power_profiles.json`
+2. Update `PowerProfileRepository.loadMachineData()`
+3. Map regions to Electricity Maps zones in `ZoneMapper`
+4. Parse metrics into `TimeseriesPoint` format
+5. Wire CI automation for provider-specific settings
 
-GitGreen only calls APIs that you explicitly configure and authorize:
+### Source Data Files
 
-- **Electricity Maps API** - For carbon intensity data (requires your API key)
-- **GitLab API** - Only when using `glab` CLI or providing a PAT, to set CI/CD variables
-- **GCP Monitoring API** - To fetch CPU/RAM metrics from your GCP project (requires your service account)
-- **AWS CloudWatch API** - To fetch CPU/RAM metrics from your AWS account (requires your AWS credentials)
+| File | Description |
+|------|-------------|
+| `data/cpu_physical_specs.json` | Physical CPU specs with sources |
+| `data/cpu_power_profiles.json` | TDP and power ratios |
+| `data/gcp_machine_power_profiles.json` | GCP machine mappings |
+| `data/aws_machine_power_profiles.json` | AWS instance mappings |
+| `data/source/*.csv` | Original re:cinq research data |
 
-GitGreen does not operate any backend services or call any APIs owned by the GitGreen project. All API calls are made directly from your environment or CI/CD pipeline using your credentials.
+## FAQ
 
-### How do I know GitGreen won't destroy my `.gitlab-ci.yml` file?
+<details>
+<summary><strong>Are my credentials secure?</strong></summary>
 
-GitGreen takes safety precautions when modifying your `.gitlab-ci.yml`:
+Yes. GitGreen stores all credentials in GitLab CI/CD variables (encrypted). Nothing is written to your local disk.
+</details>
 
-1. **Automatic backups** - Before making any changes, GitGreen creates a backup of your existing `.gitlab-ci.yml` file
-2. **Backup location** - The backup path is printed to the console (e.g., `/tmp/gitlab-ci-backup-{timestamp}.yml`)
-3. **Append-only changes** - GitGreen only appends new content to your CI file; it never removes or modifies existing jobs
-4. **Confirmation prompt** - You're asked to confirm before any changes are made
+<details>
+<summary><strong>What APIs does GitGreen call?</strong></summary>
 
-If something goes wrong, you can restore your file from the backup location that was printed.
+Only APIs you explicitly configure:
+- Electricity Maps API (carbon intensity)
+- GCP Monitoring API (metrics)
+- AWS CloudWatch API (metrics)
+- GitLab API (MR comments, via CI_JOB_TOKEN)
 
-### Can I use GitGreen without the `init` wizard?
+GitGreen has no backend server.
+</details>
 
-Yes. You can configure GitGreen manually by:
+<details>
+<summary><strong>Will it break my .gitlab-ci.yml?</strong></summary>
 
-1. Setting the required CI/CD variables in your GitLab project settings
-2. Adding the GitLab CI/CD component to your `.gitlab-ci.yml` manually
-3. Running `gitgreen` directly with command-line options instead of using the component
+No. GitGreen creates a backup before any changes, only appends content (never modifies existing jobs), and asks for confirmation.
+</details>
 
-The `init` wizard is a convenience tool, but all functionality is available through manual configuration.
+<details>
+<summary><strong>Can I run it without the wizard?</strong></summary>
 
-### What data does GitGreen collect?
+Yes. Set CI/CD variables manually and run `gitgreen` with CLI options.
+</details>
 
-GitGreen only collects:
+## Contributing
 
-- **CPU and RAM usage metrics** from your cloud provider (GCP Monitoring or AWS CloudWatch)
-- **Pipeline metadata** (start/end times) from GitLab CI/CD environment variables
+1. Fork the repository
+2. Create a feature branch
+3. Run tests: `npm test`
+4. Submit a pull request
 
-GitGreen does not collect any personal information, code, or data from your repositories. All calculations happen locally in your CI/CD pipeline.
+## References
 
-### Can I run GitGreen locally for testing?
+### Research & Methodology
 
-Yes. You can run `gitgreen` directly with your own metrics files:
+| Source | Description |
+|--------|-------------|
+| [re:cinq Cloud CPU Energy Consumption](https://re-cinq.com/blog/cloud-cpu-energy-consumption) | CPU power modeling methodology |
+| [re:cinq emissions-data](https://github.com/re-cinq/emissions-data) | Machine power profiles and ratios |
+| [Teads Engineering](https://engineering.teads.com/) | Original research on cloud carbon |
+| Dell PowerEdge R740 LCA | Scope 3 embodied carbon data |
 
-**GCP example:**
-```bash
-gitgreen --provider gcp \
-  --machine e2-standard-4 \
-  --region us-central1-a \
-  --cpu-timeseries cpu.json \
-  --ram-used-timeseries ram-used.json \
-  --ram-size-timeseries ram-size.json \
-  --out-md report.md
-```
+### Data Sources
 
-**AWS example:**
-```bash
-gitgreen --provider aws \
-  --machine t3.medium \
-  --region us-east-1 \
-  --cpu-timeseries cpu.json \
-  --ram-used-timeseries ram-used.json \
-  --ram-size-timeseries ram-size.json \
-  --out-md report.md
-```
+| Data | Source |
+|------|--------|
+| Real-time carbon intensity | [Electricity Maps API](https://www.electricitymaps.com/) |
+| GCP machine specifications | [Google Cloud CPU Platforms](https://cloud.google.com/compute/docs/cpu-platforms) |
+| GCP data center PUE | [Google Data Center Efficiency](https://www.google.com/about/datacenters/efficiency/) |
+| Intel CPU specifications | [Intel ARK](https://ark.intel.com/) |
+| AMD CPU specifications | [AMD Product Pages](https://www.amd.com/en/products/specifications/processors) |
+| Ampere CPU specifications | [Ampere Product Briefs](https://amperecomputing.com/briefs) |
 
-Or use `--from-cloudwatch` to fetch metrics directly from AWS CloudWatch:
-```bash
-gitgreen --provider aws \
-  --machine t3.medium \
-  --region us-east-1 \
-  --from-cloudwatch \
-  --out-md report.md
-```
+### CPU Specifications Used
 
-This is useful for testing before integrating into your CI/CD pipeline.
+| CPU | Cores | Threads | TDP | Source |
+|-----|-------|---------|-----|--------|
+| Intel Xeon Gold 6268CL | 24 | 48 | 205W | [Product Listing](https://www.ebay.com/p/2321792675) |
+| Intel Xeon Gold 6253CL | 18 | 36 | 205W | [PassMark](https://www.cpubenchmark.net/cpu.php?cpu=Intel+Xeon+Gold+6253CL) |
+| Intel Xeon Platinum 8481C | 56 | 112 | 350W | [TechPowerUp](https://www.techpowerup.com/cpu-specs/xeon-platinum-8481c.c3992) |
+| Intel Xeon Platinum 8373C | 36 | 72 | 300W | [Wikipedia](https://en.wikipedia.org/wiki/List_of_Intel_Xeon_processors_(Ice_Lake-based)) |
+| AMD EPYC 7B12 | 64 | 128 | 240W | [Newegg](https://www.newegg.com/p/1FR-00G6-00026) |
+| Ampere Altra Q64-30 | 64 | 64 | 180W | [Ampere Brief](https://amperecomputing.com/en/briefs/ampere-altra-family-product-brief) |
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>Built with care for a sustainable software future.</sub>
+</p>