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.

Total emissions: 2.847 gCO₂e
├── CPU:     1.923 gCO₂e
├── RAM:     0.412 gCO₂e
└── Scope 3: 0.512 gCO₂e (embodied carbon)

Quick Start

# Install globally
npm install -g gitgreen

# Initialize in your GitLab project
cd your-repo
gitgreen init

The wizard configures everything: provider credentials, carbon budgets, and CI/CD integration.

Table of Contents

• Installation
• Usage
• Advanced
  • Providers
  • Output Integrations
  • Database Schema
• Methodology
• Architecture
• Configuration
• FAQ
• Contributing
• References
• License

Installation

Prerequisites

| Requirement | Version | Notes | |-------------|---------|-------| | Node.js | 20+ | Download | | Git | Any | For GitLab project detection | | gcloud CLI | Any | Required for GCP (Install) | | AWS CLI | Any | Required for AWS (Install) | | glab CLI | Any | Optional, for easier GitLab auth (Install) |

Install

npm install -g gitgreen

API Keys

• Electricity Maps (required): Get free API key

Usage

Initialize a Project

gitgreen init

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

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.

Advanced

Providers

| Provider | Metrics Source | Status | |----------|---------------|--------| | GCP | Cloud Monitoring API | Full support | | AWS | CloudWatch API | Full support |

Output Integrations

Export carbon data to external databases for analytics and dashboards.

Supported Connectors

| Connector | Job Data | Runner Inventory | |-----------|----------|------------------| | MySQL | GITGREEN_JOB_MYSQL_* | GITGREEN_RUNNER_MYSQL_* | | PostgreSQL | GITGREEN_JOB_POSTGRES_* | GITGREEN_RUNNER_POSTGRES_* |

Database Migrations

gitgreen migrate --scope job      # Job emissions tables
gitgreen migrate --scope runner   # Runner inventory tables
gitgreen migrate --scope all      # Both

Migrations run automatically in CI pipelines.

Database Schema

| 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 |

| 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 |

| 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 |

Methodology

GitGreen's calculations are based on peer-reviewed methodologies from re:cinq and Teads.

Formula

E_total = E_operational + E_embodied

E_operational = (P_cpu + P_ram) × runtime_hours × PUE × carbon_intensity
E_embodied    = scope3_hourly × runtime_hours

| 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 |

CPU Power Model

CPU power is non-linear with utilization. We use cubic spline interpolation across measured data points:

| Utilization | Power (% of TDP) | |-------------|------------------| | 0% (idle) | 1.7% | | 10% | 3.4% | | 50% | 16.9% | | 100% | 100% |

VM Power Correction: Cloud VMs share physical CPUs. We scale power by the ratio of VM vCPUs to physical threads:

P_vm = TDP × ratio × (vm_vcpus / physical_threads)

| CPU | Cores | Threads | TDP | Source | |-----|-------|---------|-----|--------| | Intel Xeon Gold 6268CL | 24 | 48 | 205W | Intel | | Intel Xeon Platinum 8481C | 56 | 112 | 350W | TechPowerUp | | AMD EPYC 7B12 | 64 | 128 | 240W | AMD | | Ampere Altra Q64-30 | 64 | 64 | 180W | Ampere |

Scope 3 (Embodied Carbon)

Manufacturing emissions amortized over hardware lifespan (6 years):

| Component | Emissions | |-----------|-----------| | Base server | ~1000 kgCO₂eq | | Per CPU | ~100 kgCO₂eq | | Per 32GB DIMM | ~44 kgCO₂eq | | Per SSD | ~50-100 kgCO₂eq |

Source: Dell PowerEdge R740 Life Cycle Assessment

Accuracy & Limitations

Expected Accuracy:

• Relative comparisons: Excellent (comparing job A vs B)
• Absolute values: ±15-25% for CPU-bound workloads

Known Limitations:

| 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 |

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        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)      │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Configuration

Adding a New Provider

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

Source Data Files

| 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 |

FAQ

Yes. GitGreen stores all credentials in GitLab CI/CD variables (encrypted). Nothing is written to your local disk.

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)

GitGreen has no backend server.

No. GitGreen creates a backup before any changes, only appends content (never modifies existing jobs), and asks for confirmation.

Yes. Set CI/CD variables manually and run gitgreen with CLI options.

Contributing

1. Fork the repository
2. Create a feature branch
3. Run tests: npm test
4. Submit a pull request

References

Research & Methodology

| Source | Description | |--------|-------------| | re:cinq Cloud CPU Energy Consumption | CPU power modeling methodology | | re:cinq emissions-data | Machine power profiles and ratios | | Teads Engineering | Original research on cloud carbon | | Dell PowerEdge R740 LCA | Scope 3 embodied carbon data |

Data Sources

| Data | Source | |------|--------| | Real-time carbon intensity | Electricity Maps API | | GCP machine specifications | Google Cloud CPU Platforms | | GCP data center PUE | Google Data Center Efficiency | | Intel CPU specifications | Intel ARK | | AMD CPU specifications | AMD Product Pages | | Ampere CPU specifications | Ampere Product Briefs |

CPU Specifications Used

| CPU | Cores | Threads | TDP | Source | |-----|-------|---------|-----|--------| | Intel Xeon Gold 6268CL | 24 | 48 | 205W | Product Listing | | Intel Xeon Gold 6253CL | 18 | 36 | 205W | PassMark | | Intel Xeon Platinum 8481C | 56 | 112 | 350W | TechPowerUp | | Intel Xeon Platinum 8373C | 36 | 72 | 300W | Wikipedia | | AMD EPYC 7B12 | 64 | 128 | 240W | Newegg | | Ampere Altra Q64-30 | 64 | 64 | 180W | Ampere Brief |

License

MIT License - see LICENSE for details.