CI Sizer

• 1: Configuration
• 2: Web Dashboard
• 3: Sizing Algorithm
• 4: OOM Detection & Confidence-Gated Sizing
• 5: Energy Estimation
• 6: API Reference
• 7: GitLab CI Integration
• 8: KPI Benchmark

┌─────────────────────────────────────────────┐       ┌──────────────────────────┐
│  CI/CD Pod (shared PID namespace)           │       │  Receiver Service        │
│                                             │       │                          │
│  ┌───────────┐  ┌────────┐  ┌───────────┐   │       │  POST /api/v1/metrics    │
│  │ collector │  │ runner │  │ sidecar   │   │       │         │                │
│  │           │  │        │  │           │   │  push │         ▼                │
│  │ reads     │  │        │  │           │   │──────▶│  ┌────────────┐          │
│  │ /proc for │  │        │  │           │   │       │  │  SQLite    │          │
│  │ all PIDs  │  │        │  │           │   │       │  └────────────┘          │
│  └───────────┘  └────────┘  └───────────┘   │       │         │                │
│                                             │       │         ▼                │
└─────────────────────────────────────────────┘       │  GET /api/v1/sizing/...  │
                                                      │  GET /ui                 │
                                                      └──────────────────────────┘

1 - Configuration

Collector Configuration

The collector runs alongside CI workloads, reads /proc, and pushes a run summary to the receiver on shutdown.

Collector Flags

Carbon Zone

The carbon zone determines which electricity grid is used for carbon intensity estimation.

Supported zones:

Example:

# French grid (nuclear-dominated, very low CI)
./collector --carbon-zone FR

# Or via environment variable
RUNNER_CARBON_ZONE=PL ./collector

Provider chain per zone:

• DE: Energy Charts → FfE blob projection → static (seasonal/weekday)
• All others: Energy Charts → static (seasonal/weekday table with 192 values)

FfE projection data is only available for Germany. For all other zones, the static fallback provides a seasonal/weekday/hourly profile (192 values) when Energy Charts is unavailable.

CI Context Environment Variables

These environment variables identify the CI run context. They are typically set automatically by GitHub Actions / Forgejo Actions.

CGROUP_LIMITS Format

{
  "runner": { "cpu": "2", "memory": "1Gi" },
  "sidecar": { "cpu": "500m", "memory": "256Mi" }
}

CPU supports Kubernetes notation ("2" = 2 cores, "500m" = 0.5 cores). Memory supports Ki, Mi, Gi, Ti (binary) or K, M, G, T (decimal).

Note: The collector reads GITHUB_REPOSITORY (e.g., my-org/my-repo) and automatically strips the organization prefix before pushing — the payload’s repository field contains only my-repo. When generating push tokens via POST /api/v1/token, the repository field must use the short name (without the org prefix).

Receiver Configuration

The receiver stores metric summaries, serves the web UI, and provides the sizing and query APIs.

Receiver Flags

OIDC / Authentication Flags

JWT Claim Mapping

GARM Integration Flags

OOM Detection & Notification Flags

Multi-Provider Flags

GitLab-Specific Variables

These variables are relevant when CI_PROVIDER=gitlab:

Set CGROUP_STRATEGY=exclusion for GitLab pods where the build container process name is unpredictable. See GitLab Integration for details.

Authentication Modes

CI Sizer supports three authentication modes, configured via --auth-mode:

When --auth-mode is not set, the receiver auto-detects: if --oidc-client-id is provided, it defaults to oidc; otherwise it defaults to none.

Kubernetes Deployment

Receiver Deployment

docker build -f Dockerfile --target receiver -t ci-sizer-receiver:local .

kubectl create namespace ci-sizer
kubectl -n ci-sizer create secret generic receiver-secrets \
  --from-literal=read-token=my-secret-token \
  --from-literal=hmac-key=my-hmac-key

apiVersion: apps/v1
kind: Deployment
metadata:
  name: receiver
spec:
  replicas: 1
  selector:
    matchLabels:
      app: receiver
  template:
    metadata:
      labels:
        app: receiver
    spec:
      containers:
      - name: receiver
        image: ci-sizer-receiver:local
        ports:
        - containerPort: 8080
        env:
        - name: RECEIVER_READ_TOKEN
          valueFrom:
            secretKeyRef:
              name: receiver-secrets
              key: read-token
        - name: RECEIVER_HMAC_KEY
          valueFrom:
            secretKeyRef:
              name: receiver-secrets
              key: hmac-key
        args: ["--addr=:8080", "--db=/data/metrics.db"]
        volumeMounts:
        - name: data
          mountPath: /data
      volumes:
      - name: data
        emptyDir: {}

For persistent storage, replace the emptyDir volume with a PersistentVolumeClaim.

For plain HTTP deployments (local dev, port-forward), set RECEIVER_COOKIE_SECURE=false to prevent OIDC login failures caused by browsers rejecting Secure cookies over HTTP.

Collector Sidecar

The collector runs as a sidecar in CI pods with shareProcessNamespace: true. Generate a push token first, then deploy:

apiVersion: v1
kind: Pod
metadata:
  name: ci-run-test
spec:
  shareProcessNamespace: true
  restartPolicy: Never
  containers:
  - name: runner
    image: busybox:latest
    command: ["/bin/sh", "-c", "while true; do dd if=/dev/zero of=/dev/null bs=1M count=100 2>/dev/null; sleep 1; done"]
    resources:
      limits:
        cpu: "500m"
        memory: "256Mi"
  - name: collector
    image: ci-sizer-collector:local
    args: ["--interval=2s", "--top=5", "--push-endpoint=http://receiver.ci-sizer.svc.cluster.local/api/v1/metrics"]
    env:
    - name: COLLECTOR_PUSH_TOKEN
      value: "<PUSH_TOKEN>"
    - name: GITHUB_REPOSITORY_OWNER
      value: "my-org"
    - name: GITHUB_REPOSITORY
      value: "my-org/my-repo"
    - name: GITHUB_WORKFLOW
      value: "ci.yml"
    - name: GITHUB_JOB
      value: "build"
    - name: GITHUB_RUN_ID
      value: "test-run-001"
    resources:
      limits:
        cpu: "100m"
        memory: "64Mi"

2 - Web Dashboard

Overview

The receiver serves an embedded web UI at /ui for exploring runner metrics, sizing recommendations, energy consumption, and carbon footprint data. The dashboard is server-rendered with vanilla JavaScript — no build step or external dependencies are required.

Navigation

The dashboard uses a hierarchical drill-down model with card-based navigation:

1. Overview — global KPI summary with per-organization breakdown
2. Organization — per-repository summaries within an org
3. Repository — per-workflow summaries within a repo
4. Workflow/Job — charts showing resource usage, sizing, and energy data across runs
5. Run Details — detailed metrics for a single CI run, including sizing recommendations and energy impact

Each level displays entities as clickable cards. Click a card (or press Enter/Space when focused) to drill down to the next level. Use the Backspace key to navigate up one level.

Keyboard Shortcuts

Charts

At the workflow/job level, the dashboard displays interactive charts for:

• CPU usage — peak and average CPU cores per run
• Memory usage — peak and average memory per run
• Duration — run duration over time
• Success/failure — pass/fail statistics
• Energy consumption — estimated energy (Wh) per run
• Carbon footprint — estimated CO2 emissions (gCO2eq) per run

Charts support a time range selector to filter the displayed period. The x-axis can be toggled between run ID order and chronological time order.

Clicking a data point in any chart navigates to the run details view for that specific execution.

Run Details

The run details view shows comprehensive information for a single CI execution:

• Per-container CPU and memory metrics (peak, average, percentiles)
• Top CPU and memory consuming processes
• Sizing recommendations for each container (request and limit values)
• Energy consumption estimate with methodology and confidence level
• Carbon footprint estimate with carbon intensity source

Compare Feature

The compare feature allows side-by-side comparison of multiple entities (organizations, repositories, workflows, or jobs):

1. Press C to open the compare basket
2. Add entities to the basket from any navigation level
3. Press O or click the compare button to view a side-by-side comparison
4. Compare view shows KPIs, resource usage trends, and sizing recommendations across selected entities

Entity Search

Press / to focus the entity search field. Type to filter the visible cards by name. The search works at any navigation level — overview, org, repo, or workflow/job.

3 - Sizing Algorithm

Overview

CI Sizer analyses historical resource usage to recommend right-sized Kubernetes resource requests and limits for each container in a CI pod. The goal is to find the smallest allocation that safely completes the job — reducing waste without causing failures.

Methodology

The sizer computes recommendations by aggregating the N most recent clean (non-OOM) runs for a given workflow/job combination. The aggressiveness of the recommendation depends on the current confidence phase.

Confidence Phases

Every workflow/job progresses through three confidence phases as clean samples accumulate:

In the confident phase, the full algorithm below applies:

1. Collect the N most recent runs (configurable via ?runs= query parameter, 1–100)
2. Per container, across runs:
   • CPU request — take the selected percentile (default: p95) of each run’s CPU usage, then take the maximum across runs
   • Memory request — take the peak memory of each run, then take the maximum across runs
3. Apply buffers to add headroom above observed values
4. Apply floor values to ensure minimum viable allocations
5. Apply a memory ceiling — no single container can exceed the total pod memory observed across all runs (plus buffer)
6. Round limits to clean values: CPU rounds up to the nearest 0.5 cores; memory rounds up to the next power of 2 in MiB

For full details on confidence phases and OOM recovery, see OOM Detection.

Query Parameters

Thresholds and Floors

Every container receives a minimum viable allocation even if it was completely idle in all observed runs:

Request and limit floors are intentionally asymmetric: a low request allows efficient scheduling bin-packing, while a higher limit prevents OOM kills or severe throttling if a previously-idle container becomes active.

Staircase Buffer

CPU uses a flat configurable buffer (default: 20%). Memory uses a staircase buffer — larger allocations are inherently more stable and over-provisioning them wastes more cluster resources:

CPU vs Memory Enforcement

Kubernetes treats CPU and memory differently, and the sizer reflects this:

• CPU is compressible — exceeding the limit causes throttling, not failure. The job continues, just slower.
• Memory is incompressible — exceeding the limit triggers an OOM kill. The job fails immediately.

Memory limits are therefore always enforced. CPU enforcement is opt-in via --cpu-sizing-mode:

Memory QoS

The --memory-qos flag controls the memory QoS class:

Sizing Overrides

Operators can pin CPU and/or memory values at any scope instead of relying on the algorithm. Overrides are useful for known-heavy jobs, cost caps, or bootstrapping new workflows before enough historical data exists.

Scope Hierarchy

Overrides resolve with most-specific wins:

job > workflow > repo > org

Fields left null in an override are inherited from the next parent scope (or the algorithm). This means you can override only memory at the org level and let CPU continue to be computed from data.

Override API

When an override is active, the sizing response includes override_scope in the meta block indicating which level matched (job, workflow, repo, org). When no override matched, the value is "global".

OOM-Aware Sizing

When OOM events are detected (via cgroup v2 memory.events or the 95%-of-limit heuristic), the sizer applies special handling:

• OOM-suspect samples are excluded from the clean sample count — they do not advance the confidence phase
• Exponential backoff on consecutive OOMs: limit × 2^consecutiveOOMs
• Node ceiling cap — backoff is bounded by the node ceiling (90% of node RAM or --max-memory)

This ensures the sizer recovers gracefully from memory exhaustion without unbounded growth. For full details, see OOM Detection.

For the full sizing API response format, see the API Reference.

4 - OOM Detection & Confidence-Gated Sizing

Overview

CI Sizer v0.7.0 introduces confidence-gated sizing — a system that adapts recommendation aggressiveness based on how much data is available for a given workflow/job. Combined with OOM detection, the sizer can automatically recover from memory exhaustion events by applying exponential backoff and notifying the source forge via commit status.

Confidence Phases

Every workflow/job combination progresses through three confidence phases as the sizer accumulates clean (non-OOM) samples:

OOM Detection

Cgroup v2 Detection

The collector sidecar reads the cgroup v2 memory.events file and monitors the oom_kill counter. When the counter increments during a run, the sample is marked as an OOM event.

Source: internal/cgroup/oom.go

Heuristic Detection

For environments where the oom_kill counter is not available (e.g., cgroup v1), the sizer applies a heuristic: if the observed peak memory reaches ≥95% of the configured limit, the sample is marked as OOM-suspect. OOM-suspect samples are excluded from the clean sample count used for confidence phase progression.

Exponential Backoff

When consecutive OOMs are detected for a workflow/job, the sizer applies exponential backoff to the memory limit:

new_limit = current_limit × 2^consecutiveOOMs

The backoff is capped at the node ceiling to prevent unbounded growth.

Node Ceiling

The maximum memory allocation is bounded by the node ceiling, which is determined by:

1. Auto-detection — reads /proc/meminfo and uses 90% of total node RAM
2. Manual override — configurable via --max-memory flag

Similarly, --max-cpu caps the maximum CPU allocation.

Commit Status Notifications

When an OOM event is detected, the receiver posts a commit status notification to the source forge, alerting developers that their CI run was killed due to memory exhaustion.

Forgejo / GitHub

POST /api/v1/repos/{owner}/{repo}/statuses/{sha}

GitLab

POST /api/v4/projects/{id}/statuses/{sha}

Authentication is via the PRIVATE-TOKEN header for GitLab or Bearer token for Forgejo/GitHub.

Configuration

In most deployments, only --notify-token is required. The base URL and node ceiling are auto-detected.

Source: internal/receiver/notify/notify.go

Web UI Indicators

The web dashboard surfaces OOM information through several visual elements:

• Confidence badges — displayed per workflow/job showing the current phase (unknown, learning, confident)
• OOM banners — warning banners on affected workflow/job pages
• Red markers on charts — individual OOM’d runs are highlighted with red markers on the timeline chart

Sizing Response

When OOM detection is active, the sizing API response includes additional fields in the meta block:

{
  "meta": {
    "confidence_phase": "learning",
    "clean_samples": 3,
    "consecutive_ooms": 1,
    "node_ceiling_memory": "28Gi",
    "node_ceiling_cpu": "14"
  }
}

Source Files

5 - Energy Estimation

Overview

CI Sizer estimates the energy consumption and carbon footprint of CI/CD runner executions using established industry models. CPU utilization data collected by the collector sidecar (from /proc/stat) is combined with hardware power characteristics and grid carbon intensity to produce per-run energy scores.

These are statistical estimates, not real power measurements. They are suitable for trend analysis, cross-run comparison, and sustainability reporting.

Power Estimation Models

Teads SPECpower Curve (TDP-based)

When the hardware’s Thermal Design Power (TDP) is known and no per-vCPU min/max watt bounds are set, power is estimated using a 4-point piecewise linear interpolation derived from SPECpower benchmark data.

Power(u) = TDP x interpolate(u, [0, 10, 50, 100], [0.12, 0.32, 0.75, 1.02])

Between anchor points, values are linearly interpolated. The 1.02 coefficient at 100% accounts for turbo-boost overshoot above nominal TDP.

Source: Benjamin Davy, Teads Engineering (2021), standardized by the Green Software Foundation Impact Framework.

References:

• Teads Engineering: Estimating AWS EC2 Instances Power Consumption
• Green Software Foundation IF: CPU to Carbon Pipeline

CCF Linear Model (vCPU-based)

When only the vCPU count is known (or when per-vCPU min/max watt bounds are available), the Cloud Carbon Footprint linear interpolation model is used.

Power = vCPUs x (MinWatts + u x (MaxWatts - MinWatts))

Default coefficients (AWS average from SPECpower_ssj2008 benchmarks):

When a specific CPU is auto-detected, TDP-derived bounds replace the defaults:

MinWatts = TDP x 0.12 / vCPUs    (idle fraction from Teads curve)
MaxWatts = TDP x 1.02 / vCPUs    (max fraction from Teads curve)

Reference: Cloud Carbon Footprint Methodology

Model Selection

In practice, auto-detected CPUs derive min/max watts from TDP, so the CCF linear model is used for both generic and auto-detected profiles. The Teads curve is only used when a user provides a raw TDP-only hardware profile.

Energy Calculation

Energy_raw (kWh) = Power (W) x Duration (s) / 3600 / 1000
Energy_adjusted (kWh) = Energy_raw x PUE

Power Usage Effectiveness (PUE)

A PUE of 1.3 means the datacenter uses 30% more energy than the IT equipment alone. This is a conservative middle ground:

Provider-specific PUEs (from Cloud Carbon Footprint):

References:

• Uptime Institute: Global Data Center Survey Results 2024
• Cloud Carbon Footprint: Methodology — PUE

Carbon Intensity

Carbon emissions are calculated as:

Carbon (gCO2eq) = Energy (kWh) x CarbonIntensity (gCO2eq/kWh)

Carbon intensity is resolved through a 3-tier fallback chain. Each tier is tried in order; the first successful response wins. The methodology string always reflects which tier actually supplied the data.

Data Quality Comparison

Tier 1: Energy Charts Real-Time (default)

Direct carbon intensity calculation: Carbon intensity is calculated directly from the generation mix using IPCC AR5 lifecycle emission factors per fuel type: grid_intensity = Σ(fuel_MW × emission_factor) / Σ(generation_MW). Each 15-minute interval’s generation data is fetched from the /public_power endpoint. For each production type with a known emission factor, the MW output is multiplied by the factor; the weighted sum is divided by total generation to yield gCO₂eq/kWh. Negative values (storage consumption) and non-generation keys (Load, Battery Consumption, etc.) are excluded.

IPCC AR5 lifecycle emission factors used by CI Sizer:

For example, when the grid runs on 5000 MW lignite and 5000 MW gas: (5000×1054 + 5000×410) / 10000 = 732 gCO₂eq/kWh.

This approach calculates intensity directly from the actual fuel dispatch, providing more accurate values than the previous simplified formula.

Reference: Fraunhofer ISE — Energy Charts

Tier 2: FfE Projection Data (first fallback)

These are modeled projections, NOT actual measurements. The simulation uses weather reference year 2012 to produce a plausible hourly carbon intensity profile. This means:

• The same hour-of-year always returns the same value, regardless of when you query
• It captures realistic seasonal and diurnal patterns (e.g., midday solar dips, winter peaks)
• It cannot reflect today’s actual wind speed, cloud cover, or demand conditions

Note: FfE projection data is only available for Germany (zone DE). For other zones, Tier 2 is skipped and the chain falls through directly to Tier 3.

The data is produced under the InDEED research project (Integrating Decentralized Energy Data).

Reference: FfE OpenData (InDEED project)

Tier 3: Static Lookup Table (last resort)

A 192-value lookup table for all 13 supported zones, indexed by season (4), day type (weekday/weekend), and hour (24). Derived from Energy Charts /public_power data (2025–2026, IPCC AR5 emission factors).

Methodology string: static

Methodological basis:

• Kono, J., Ostermeyer, Y. & Wallbaum, H. (2017). “The trends of hourly carbon emission factors in Germany and investigation on relevant consumption patterns for its application.” International Journal of Life Cycle Assessment, 22, 1493–1501. DOI: 10.1007/s11367-017-1277-z
• Holzapfel, P., Bach, V. & Finkbeiner, M. (2023). “Increasing temporal resolution in greenhouse gas accounting of electricity consumption divided into Scopes 2 and 3.” International Journal of Life Cycle Assessment, 28, 1622–1639. DOI: 10.1007/s11367-023-02240-3

Last-Resort Fallback

Updated from 400 g/kWh in v0.2.x to reflect declining German grid intensity. Per Umweltbundesamt (UBA), the annual average was 386 g/kWh (2023) and 363 g/kWh (2024). The carbon_source field is set to "fallback" to flag this condition.

Reference: Umweltbundesamt — Strom- und Wärmeversorgung in Zahlen

Provider Selection

The --carbon-provider flag (or RUNNER_CARBON_PROVIDER env var) controls which providers are used:

Multi-Country Carbon Zones

CI Sizer supports 13 European electricity grid zones for carbon intensity estimation. The zone is configured via the --carbon-zone flag or RUNNER_CARBON_ZONE environment variable (default: DE).

Supported Zones

Configuration

# French grid (nuclear-dominated, very low CI)
./collector --carbon-zone FR

# Or via environment variable
RUNNER_CARBON_ZONE=PL ./collector

Provider Chain by Zone

The fallback chain differs depending on the selected zone:

• DE (Germany): Energy Charts → FfE blob projection → static (seasonal/weekday table with 192 values)
• All other zones: Energy Charts → static (seasonal/weekday table with 192 values)

FfE projection data (Tier 2) is only available for Germany. For all other zones, the provider chain skips FfE and falls back directly to the static table. All 13 supported zones have full 192-value static tables (4 seasons × 2 day types × 24 hours) derived from Energy Charts data. If all providers fail, the hardcoded 380 gCO₂/kWh fallback is used regardless of zone.

CPU TDP Database

A built-in database of 38 CPU models maps processor names to TDP (Thermal Design Power) values:

Sources:

• Intel ARK — Intel Xeon processors
• AMD Product Specifications — EPYC processors
• CodeCarbon cpu_power.csv (MIT license) — cross-validation
• Community estimates for AWS Graviton processors (no official TDP published by AWS)

Graviton TDP values (Graviton2 ~130 W, Graviton3 ~180 W, Graviton4 ~210 W) are engineering estimates based on ARM Neoverse power characteristics, not manufacturer specifications.

Confidence Levels

Each energy score includes a confidence field indicating the quality of the estimate:

The confidence level reflects the hardware profile quality. Carbon data source quality is captured separately in the carbon_source field (energy-charts, ffe-projection, static, or fallback).

Limitations

Verifying the Data

You can query the upstream carbon intensity sources directly to verify what CI Sizer is seeing.

Reading the Methodology String

Each energy score in CI Sizer includes a methodology string like:

ccf-linear+energy-charts+DE+pue-1.30

If the carbon source shows ffe-projection or static instead of energy-charts, the system fell back because Energy Charts was unavailable.

Querying Energy Charts (Tier 1)

The Energy Charts API requires lowercase country codes and date-only format (no timestamps):

# German grid generation mix for today (replace dates with today/tomorrow)
curl -s "https://api.energy-charts.info/public_power?country=de&start=2026-05-20&end=2026-05-21" \
  | jq '{
    timestamps: (.unix_seconds | length),
    first: (.unix_seconds[0] | todate),
    last: (.unix_seconds[-1] | todate),
    fuels: [.production_types[] | .name]
  }'

# See actual MW per fuel type at a specific timestamp
curl -s "https://api.energy-charts.info/public_power?country=de&start=2026-05-20&end=2026-05-21" \
  | jq '{
    time: (.unix_seconds[40] | todate),
    generation_MW: [.production_types[] | select(.data[40] != null and .data[40] > 0) | {(.name): (.data[40] | round)}] | add
  }'

# French grid (nuclear-dominated, very low carbon)
curl -s "https://api.energy-charts.info/public_power?country=fr&start=2026-05-20&end=2026-05-21" \
  | jq '[.production_types[] | .name]'

The response contains unix_seconds[] (15-minute intervals) and production_types[{name, data[]}] with MW output per fuel type. CI Sizer multiplies each fuel’s MW by its IPCC AR5 emission factor and divides by total generation to compute gCO₂eq/kWh.

Important: Replace the dates in the examples with today’s date. The API returns data up to the most recent 15-minute interval.

Computing Grid Carbon Intensity

To replicate the exact calculation CI Sizer performs — weighted average of generation MW × emission factor:

# Compute current German grid carbon intensity (same formula as ci-sizer)
curl -s "https://api.energy-charts.info/public_power?country=de&start=$(date -u +%Y-%m-%d)&end=$(date -u -v+1d +%Y-%m-%d)" | jq '
  (.unix_seconds | length - 1) as $idx |
  (.unix_seconds[$idx] | todate) as $time |
  {"Fossil brown coal / lignite":1054,"Fossil hard coal":888,"Fossil gas":410,
   "Fossil oil":733,"Fossil coal-derived gas":850,"Fossil peat":1100,
   "Nuclear":12,"Biomass":230,"Geothermal":38,"Wind offshore":12,
   "Wind onshore":11,"Solar":45,"Hydro Run-of-River":24,
   "Hydro water reservoir":24,"Hydro pumped storage":24,
   "Waste":330,"Others":400,"Other renewables":30} as $f |
  [.production_types[] | select(.data[$idx]!=null and .data[$idx]>0) |
   {name,mw:.data[$idx]} | select($f[.name]!=null) |
   {name,mw,w:(.mw*$f[.name])}] as $g |
  {timestamp: $time,
   grid_carbon_intensity_gCO2_per_kWh: ([$g[]|.w]|add)/([$g[]|.mw]|add)|round,
   total_generation_MW: ([$g[]|.mw]|add)|round,
   top_contributors: [$g | sort_by(-.w)[0:5][] | {fuel:.name, MW:(.mw|round), share_pct:((.w/([$g[]|.w]|add)*100)*10|round/10)}]}'

This takes the most recent 15-minute interval, multiplies each fuel type’s MW output by its IPCC emission factor, sums the weighted values, and divides by total generation to get gCO₂eq/kWh. The top_contributors field shows which fuels are driving most of the carbon impact.

Note: On Linux, replace date -v+1d with date -d "+1 day". Or simply hardcode tomorrow’s date.

Querying FfE Projection (Tier 2)

The FfE blob contains 8760 hourly projection values for an entire year (DE only):

# Get 2025 projection metadata
curl -s "https://ffeopendatastorage.blob.core.windows.net/opendata/id_opendata_2/id_opendata_2_year_2025.json" \
  | jq '[.[] | select(.internal_id == [2,1,1])][0] | {
    year: .year,
    weather_reference_year: .year_weather,
    total_hours: (.values | length),
    annual_average_gCO2_per_kWh: (.value * 1000 | round),
    unit: "values are in kg/kWh, multiply by 1000 for g/kWh"
  }'

# Get projection for a specific hour (e.g., May 20 at 09:00 UTC = hour index 3345)
curl -s "https://ffeopendatastorage.blob.core.windows.net/opendata/id_opendata_2/id_opendata_2_year_2025.json" \
  | jq '[.[] | select(.internal_id == [2,1,1])][0] | {
    hour_index: 3345,
    carbon_intensity_gCO2_per_kWh: (.values[3345] * 1000 | round),
    note: "This is a modeled projection, not real-time data"
  }'

Note: Hour index = (day_of_year - 1) × 24 + hour_utc. These values are static projections based on weather year 2012 — they will return the same result regardless of when you query them.

Tier 3 (Static Table)

The static fallback table is compiled into the binary — there is no external API to query. It provides 192 values per zone (4 seasons × 2 day types × 24 hours) derived from Energy Charts historical data.

Related Standards

6 - API Reference

Overview

All endpoints are under /api/v1 unless noted otherwise. The OpenAPI specification is auto-generated and served live at /swagger on the receiver. The spec file is also available at docs/openapi.json in the repository.

Authentication

CI Sizer uses a two-tier token system:

• Read token (--read-token): Pre-shared admin credential for read/query endpoints. Used as Authorization: Bearer <read-token>.
• Push tokens (derived from --hmac-key): Scoped, time-limited HMAC-SHA256 tokens for collectors. Generated via POST /api/v1/token.

Authentication behaviour depends on the configured auth mode. See Configuration — Authentication Modes for details.

Authentication by Endpoint (OIDC Mode)

In oidc mode, endpoints use two tiers. The relaxed tier also accepts a Bearer read token, enabling programmatic access (e.g., from the GARM provider).

In gateway mode, replace “OIDC Session” with “Gateway JWT (X-Access-Token)”. In none mode, all protected endpoints accept the Bearer read token.

Health and Info

No authentication required.

Token and Metrics Ingest

Push Token Generation

curl -s -X POST http://localhost:8080/api/v1/token \
  -H "Authorization: Bearer <read-token>" \
  -H "Content-Type: application/json" \
  -d '{"organization":"my-org","repository":"my-repo","workflow":"ci.yml","job":"build"}'

The returned token is scoped to the specified org/repo/workflow/job combination and expires after the configured --token-ttl (default: 2 hours).

Metrics Query

Metrics Response Example

[
  {
    "id": 1,
    "organization": "my-org",
    "repository": "my-org/my-repo",
    "workflow": "ci.yml",
    "job": "build",
    "run_id": "run-123",
    "received_at": "2026-02-06T14:30:23.056Z",
    "payload": {
      "start_time": "2026-02-06T14:30:02.185Z",
      "end_time": "2026-02-06T14:30:22.190Z",
      "duration_seconds": 20.0,
      "sample_count": 11,
      "containers": [
        {
          "name": "runner",
          "cpu_cores": { "peak": 2.007, "avg": 1.5, "p50": 1.817, "p95": 2.004 },
          "memory_bytes": { "peak": 18567168, "avg": 18567168 }
        }
      ]
    }
  }
]

CPU metric distinction:

• cpu_total_percent — system-wide, 0–100%
• cpu_cores (containers) — cores used (e.g., 2.0 = two full cores)
• peak_cpu_percent (processes) — per-process, where 100% = 1 core

All memory values are in bytes.

Sizing

Query Parameters

Sizing Response Example

{
  "containers": [
    {
      "name": "runner",
      "cpu":    { "request": "960m", "limit": "1", "enforced": false },
      "memory": { "request": "1024Mi", "limit": "1024Mi", "enforced": true }
    }
  ],
  "total": {
    "cpu":    { "request": "970m", "limit": "1500m" },
    "memory": { "request": "647Mi", "limit": "1024Mi" }
  },
  "meta": {
    "runs_analyzed": 10,
    "buffer_percent": 20,
    "cpu_percentile": "p95",
    "cpu_sizing_mode": "observe",
    "memory_qos": "guaranteed"
  }
}

For details on the sizing algorithm, buffers, and enforcement modes, see Sizing Algorithm.

Energy and Carbon

Supports ?from= and ?to= time range filters (ISO 8601).

Aggregation and Dashboard

All aggregation endpoints support ?from=, ?to= (ISO 8601) and ?limit= / ?offset= pagination.

Sizing Overrides

Override hierarchy: job > workflow > repo > org (most-specific wins). Fields left null are inherited from the next parent scope. See Sizing Algorithm — Sizing Overrides for details.

OIDC UI Routes

Available when auth mode is oidc.

OpenAPI Specification

The OpenAPI spec is auto-generated from the receiver’s route definitions and served live at /swagger. The spec file is also committed to the repository at docs/openapi.json.

Note: The OpenAPI spec is generated code — do not edit it manually. Run make openapi in the ci-sizer repository to regenerate it after API changes.

7 - GitLab CI Integration

Overview

CI Sizer supports GitLab CI through the gitlab-webhook-edge-connect component — a Kubernetes MutatingAdmissionWebhook that intercepts GitLab Runner executor pods and injects the CI Sizer collector sidecar.

Unlike Forgejo/GitHub Actions (which use GARM for runner lifecycle management), GitLab Runner uses its own Kubernetes executor. The webhook intercepts pods at admission time and mutates them to include the collector.

Repository: edp.buildth.ing/DevFW-CICD/gitlab-webhook-edge-connect

Architecture

┌──────────────────────────────────────────────────────────────────┐
│  Kubernetes API Server                                           │
│                                                                  │
│  MutatingAdmissionWebhook                                        │
│  ┌────────────────────────────────────┐                          │
│  │ gitlab-webhook-edge-connect        │                          │
│  │                                    │                          │
│  │  Intercepts pods with label:       │                          │
│  │  job.runner.gitlab.com/pod (Exists)│                          │
│  │                                    │                          │
│  │  Injects: collector sidecar        │                          │
│  │  Sets: shareProcessNamespace=true  │                          │
│  └────────────────────────────────────┘                          │
└──────────────────────────────────────────────────────────────────┘

Pod Targeting

The webhook targets GitLab Runner pods using a label selector (not annotation):

objectSelector:
  matchExpressions:
    - key: job.runner.gitlab.com/pod
      operator: Exists

This label is automatically applied by the GitLab Runner Kubernetes executor to all job pods.

Backends

The webhook supports two mutation backends:

Collector Injection

The collector is injected using the shared library ci-sizer/pkg/inject, which is common across all CI providers. The injection adds:

• A collector sidecar container
• shareProcessNamespace: true on the pod spec
• Appropriate environment variables for CI context

Cgroup Exclusion Strategy

GitLab Runner pods present a unique challenge: the build container’s process name varies by image (it could be sh, bash, pwsh, or any custom entrypoint). This makes positive identification by process name impossible.

CI Sizer solves this with an exclusion strategy:

1. Map all known containers by process name (e.g., gitlab-runner-helper, collector)
2. Any remaining cgroup paths that don’t match a known container are assigned to the build container

This is configured via:

CGROUP_STRATEGY=exclusion

Run Metadata

Run Index

For GitLab (non-GARM) providers, the run_index is assigned by the receiver using a MaxRunIndex+1 counter per org/repo/workflow combination. This provides sequential run numbering without requiring GARM lifecycle events.

Run URL

The run URL is propagated via the pod annotation job.runner.gitlab.com/url, which the collector reads at startup.

Runner Name

For GitLab, the runner_name is set to the pod name (pod.Name), since GitLab Runner pods are ephemeral and uniquely named per job.

Deployment

The webhook is deployed to the ci-sizer namespace with TLS provided by cert-manager using a self-signed issuer:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: gitlab-webhook-tls
  namespace: ci-sizer
spec:
  secretName: gitlab-webhook-tls
  issuerRef:
    name: ci-sizer-selfsigned
    kind: Issuer
  dnsNames:
    - gitlab-webhook-edge-connect.ci-sizer.svc
    - gitlab-webhook-edge-connect.ci-sizer.svc.cluster.local

GitLab-Specific Configuration

For commit status notifications to GitLab, see OOM Detection — Commit Status Notifications.

8 - KPI Benchmark

Overview

The KPI Benchmark validates CI Sizer’s effectiveness through a controlled experiment measuring resource utilization, energy consumption, scheduling density, and reliability across multiple workload types and sizing conditions.

Repository: edp.buildth.ing/DevFW/kpi-benchmark

Methodology

Experimental Design

The benchmark uses a factorial design:

• 5 conditions × 3 workloads × 30 runs = 450 total runs

Conditions

Workloads

Statistical Approach

• Bootstrap BCa confidence intervals for resource metrics
• Fisher’s exact test for OOM rate comparisons
• Paired Wilcoxon signed-rank tests for duration comparisons

Key Results

Resource Optimization

Baseline Waste

Without CI Sizer, typical CI workloads exhibit significant resource waste:

Energy

• Per-run energy: 0.095–0.323 mWh (measured via CCF methodology)
• Projected savings at scale: 65–90% energy reduction via node-hour reduction

Reliability

OOM without the sizer causes node eviction and collateral damage to co-located pods. With the sizer, failures are contained at the cgroup boundary.

Performance Overhead

Formal KPIs

The benchmark validates the following IPCEI-CIS work package objectives: