CI Sizer

Overview

CI Sizer is a two-binary Go application that monitors CI/CD runner resource usage and provides right-sizing recommendations, energy consumption estimates, and carbon footprint tracking. It consists of a collector (runs alongside runners, collects metrics from /proc) and a receiver (aggregates data, serves a web dashboard, and provides a REST API). The two components communicate via REST — the collector pushes a run summary to the receiver on shutdown.

CI Sizer reads /proc directly with zero instrumentation — no agent installation or code changes are required in CI jobs.

Supported CI Providers

The collector works identically across all providers — it reads /proc and pushes to the receiver. The injection mechanism (how the collector gets into the CI pod) differs per provider.

Key Features

• Multi-provider support — supports Forgejo Actions, GitHub Actions, and GitLab CI via provider-specific injection mechanisms
• Resource monitoring — collects CPU and memory metrics at configurable intervals via /proc/stat and /proc/<PID>/status
• Sizing recommendations — computes Kubernetes resource requests and limits from historical data, with configurable percentiles, buffers, and floors
• Confidence-gated sizing — adapts recommendation aggressiveness through three phases (unknown → learning → confident) based on available data
• OOM detection — detects out-of-memory events via cgroup v2 memory.events and applies exponential backoff recovery
• Commit status notifications — posts OOM alerts to Forgejo, GitHub, or GitLab commit status APIs
• Staircase memory buffer — applies decreasing headroom as observed memory grows (20% below 1 GiB, 10% for 1–4 GiB, 5% above 4 GiB)
• Energy estimation — models per-run energy consumption using the Teads SPECpower curve and Cloud Carbon Footprint linear model
• Carbon footprint — calculates gCO2eq per run using real-time FfE hourly emission factors for the German electricity mix, with static and fallback tiers
• Web dashboard — hierarchical drill-down from overview to individual run details, with charts, compare functionality, and keyboard navigation
• OIDC authentication — supports direct OIDC login (Dex, Keycloak, Entra ID) or API gateway JWT forwarding
• Scoped push tokens — HMAC-SHA256 tokens scoped to org/repo/workflow/job; a compromised token cannot read data
• GARM integration — automated runner sizing via WebSocket lifecycle events (Forgejo/GitHub)
• GitLab webhook integration — MutatingAdmissionWebhook for GitLab Runner Kubernetes executor pods
• Container-aware grouping — maps processes to containers via cgroup paths

Architecture

The collector runs as a sidecar in CI pods with shared PID namespace. It samples /proc on a configurable interval, groups processes by container via cgroup paths, and pushes a run summary to the receiver on shutdown (SIGINT/SIGTERM).

The receiver stores metric summaries in SQLite, exposes query and sizing APIs, and serves a web UI at /ui. Internally it is decomposed into focused subpackages: auth/ (OIDC, gateway JWT, middleware), store/ (SQLite persistence), sizing/ (algorithm and overview aggregation), reporting/ (dashboard KPIs and aggregation), garm/ (GARM WebSocket client), pushtoken/ (HMAC token generation), and web/ (embedded static assets and HTML templates).

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

Getting Started

1. Review the Configuration reference for all collector and receiver flags
2. Deploy the receiver as a central service and the collector as a sidecar in your CI pods
3. Generate scoped push tokens for each workflow/job combination
4. Access the Web Dashboard at /ui to explore metrics and sizing recommendations

For Kubernetes deployment examples, see the Configuration page.

Repository

• Source code: edp.buildth.ing/DevFW-CICD/ci-sizer

Documentation