github-actions-runner-exporter

More Drumandbytes projects

A small Go exporter that polls the GitHub API for an organization's self-hosted Actions runners, plus repo/CI health, PR counts and Dependabot alerts, and exposes it all as Prometheus metrics.

Why

GitHub doesn't publish any of this as metrics itself, and there's no single well-maintained community exporter that covers it. Runner up/busy state is real-time by nature; everything else (CI status, PR counts, Dependabot alerts, rate limit) is polled on a much slower cache TTL, deliberately - see Two cache tiers below.

CI status is tracked per active workflow, not per repo: checking only the single most recent run across a repo's whole Actions history would let a failing workflow hide behind a later, unrelated, successful one (e.g. a broken Validate masked by a subsequent green Build).

Deliberately not included: per-job duration/queue-time metrics or run history beyond the latest one (GitHub's REST API has no org-wide "all workflow runs" endpoint, only per-repo/per-workflow, so anything beyond "latest run" would mean pulling full run history for every workflow in every repo).

Two cache tiers

Metrics

Configuration

Token permissions

A fine-grained PAT needs:

• Repository access: All repositories — scoping it to a curated list means every repo-level metric (PRs, CI, Dependabot) silently only covers the repos you picked.
• Repository permissions: Metadata (read, auto-included), Pull requests (read), Actions (read), Dependabot alerts (read).
• Organization permissions: whatever GitHub's console offers for self-hosted runners (its REST API docs only document admin:org for the classic-PAT path to that endpoint — narrower fine-grained scoping isn't guaranteed available for every org plan).

Build / test / run

go build ./...
go vet ./...
go test ./...
docker build -t github-actions-runner-exporter .

CI (.github/workflows/validate.yml) gates on the drumandbytes/reusable-actions go-ci.yml lint job and a Docker smoke test (/healthz against fake credentials — never a real GitHub org). The Trivy image scan runs separately (security.yml, on PRs and weekly on main). build.yml pushes multi-arch images to GHCR with SLSA provenance attestation on push to main/tags.

Grafana dashboard

dashboards/github-actions-runner-exporter.json covers every metric above:

• runners online, offline and busy, with per-runner state timelines;
• both exporter polls' health, so a stale cache is visible;
• CI health per repo and workflow, open PRs, Dependabot alerts by severity, and the API rate limit.

Import it in Grafana (Dashboards → New → Import) and pick your Prometheus data source.

Alerting

alerts/github-actions-runner-exporter.rules.yml has ready-made Prometheus alerting rules. Add it under rule_files:, or paste its group into a PrometheusRule's spec.groups on kube-prometheus-stack.

GithubWorkflowFailing looks at each workflow's latest completed run on any branch, so it's info rather than paging. The thresholds are starting points. Every rule has unit tests in alerts/github-actions-runner-exporter.test.yml, run in CI with promtool test rules.

How it was made

Built with the help of an AI coding assistant (Claude). I review and test what gets published.