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"