github_rate_limit_exporter

README

GitHub Rate Limit Exporter

Prometheus exporter for monitoring GitHub API rate limits across multiple users and tokens.

Features

• Export GitHub API rate limits as Prometheus metrics
• Monitor multiple users/tokens simultaneously
• Support for YAML, TOML, and HCL configuration
• Track Core, Search, GraphQL, and Integration Manifest limits
• Multi-arch Docker images (amd64, arm64, armv7)
• Secure, non-root execution
• Automatic releases on push to master

Quick Start

1. Get a GitHub Token

Create a Personal Access Token - no scopes required.

2. Install

Pre-built binary:

wget https://github.com/l13t/github_rate_limit_exporter/releases/latest/download/github_rate_limit_exporter-linux-amd64.tar.gz
tar -xzf github_rate_limit_exporter-linux-amd64.tar.gz
sudo mv github_rate_limit_exporter /usr/local/bin/

Docker:

docker pull ghcr.io/l13t/github_rate_limit_exporter:latest

Build from source:

git clone https://github.com/l13t/github_rate_limit_exporter.git
cd github_rate_limit_exporter
go build -o github_rate_limit_exporter ./cmd/exporter

3. Configure

Create config.yaml:

users:
  - name: "my-user"
    token: "ghp_your_token_here"

listen_addr: ":9101"
metrics_path: "/metrics"
poll_interval: 60

4. Run

./github_rate_limit_exporter -config config.yaml

5. Verify

curl http://localhost:9101/metrics | grep github_rate_limit

Configuration

Formats

Supports YAML, TOML, and HCL. See examples.

Options

Option	Type	Default	Description
users	array	required	GitHub users to monitor
users[].name	string	required	User identifier (metric label)
users[].token	string	required	GitHub PAT
listen_addr	string	:9101	Server address
metrics_path	string	/metrics	Metrics endpoint
poll_interval	int	60	Poll interval (seconds)

Multiple Users

users:
  - name: "personal"
    token: "ghp_personal_token"
  - name: "ci-bot"
    token: "ghp_bot_token"
  - name: "team-shared"
    token: "ghp_team_token"

Metrics

For each user, the following metrics are exported:

Core API

github_rate_limit_core_limit{user="username"}
github_rate_limit_core_remaining{user="username"}
github_rate_limit_core_used{user="username"}
github_rate_limit_core_reset_timestamp{user="username"}

Search API

github_rate_limit_search_limit{user="username"}
github_rate_limit_search_remaining{user="username"}
github_rate_limit_search_used{user="username"}
github_rate_limit_search_reset_timestamp{user="username"}

GraphQL API

github_rate_limit_graphql_limit{user="username"}
github_rate_limit_graphql_remaining{user="username"}
github_rate_limit_graphql_used{user="username"}
github_rate_limit_graphql_reset_timestamp{user="username"}

Docker

Run Container

docker run -d \
  -p 9101:9101 \
  -v $(pwd)/config.yaml:/config.yaml:ro \
  ghcr.io/l13t/github_rate_limit_exporter:latest \
  -config /config.yaml

Docker Compose

docker-compose up -d

Includes Prometheus (port 9090) and Grafana (port 3000).

Prometheus Integration

Add to prometheus.yml:

scrape_configs:
  - job_name: 'github_rate_limits'
    static_configs:
      - targets: ['localhost:9101']
    scrape_interval: 60s

Example Queries

# Remaining requests
github_rate_limit_core_remaining

# Usage percentage
(github_rate_limit_core_used / github_rate_limit_core_limit) * 100

# Time until reset (hours)
(github_rate_limit_core_reset_timestamp - time()) / 3600

Alerts

- alert: GitHubRateLimitLow
  expr: github_rate_limit_core_remaining < 1000
  for: 5m
  annotations:
    summary: "Rate limit low for {{ $labels.user }}"

- alert: GitHubRateLimitCritical
  expr: github_rate_limit_core_remaining < 100
  for: 1m
  annotations:
    summary: "Rate limit critical for {{ $labels.user }}"

See alerts.yml for complete examples.

Deployment

Kubernetes (Helm)

Deploy to Kubernetes with Prometheus Operator integration:

# Quick install
helm install github-rate-limit-exporter ./helm/github-rate-limit-exporter \
  --namespace monitoring \
  --create-namespace \
  --set githubTokens[0].name=my-user \
  --set githubTokens[0].token=ghp_your_token

Features:

• Automatic ServiceMonitor creation
• Pre-configured PrometheusRule with alerts
• Secure by default (non-root, network policies)
• High availability support

See HELM_INSTALL.md for complete guide.

Systemd

# Install binary
sudo cp github_rate_limit_exporter /usr/local/bin/

# Install service
sudo cp systemd/github_rate_limit_exporter.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now github_rate_limit_exporter

Kubernetes

apiVersion: v1
kind: Secret
metadata:
  name: github-tokens
stringData:
  config.yaml: |
    users:
      - name: "bot"
        token: "ghp_token"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: github-rate-limit-exporter
spec:
  replicas: 1
  selector:
    matchLabels:
      app: github-rate-limit-exporter
  template:
    metadata:
      labels:
        app: github-rate-limit-exporter
    spec:
      containers:
      - name: exporter
        image: ghcr.io/l13t/github_rate_limit_exporter:latest
        args: ["-config", "/config/config.yaml"]
        ports:
        - containerPort: 9101
        volumeMounts:
        - name: config
          mountPath: /config
      volumes:
      - name: config
        secret:
          secretName: github-tokens

Development

Build with Task

# Install Task
brew install go-task/tap/go-task

# Build
task build

# Run tests
task test

# Run locally
task run

Without Task

# Build
go build -o build/github_rate_limit_exporter ./cmd/exporter

# Test
go test ./...

# Run
go run ./cmd/exporter -config config.yaml

Security

• Never commit tokens to version control
• Use secrets management in production (Vault, AWS Secrets Manager)
• Set restrictive permissions: chmod 600 config.yaml
• Run as non-root user
• Rotate tokens regularly

Troubleshooting

No metrics appearing:

# Test token validity
curl -H "Authorization: token ghp_YOUR_TOKEN" \
  https://api.github.com/rate_limit

Config errors:

# Validate config syntax
./github_rate_limit_exporter -config config.yaml

Connection issues:

# Check if running
curl http://localhost:9101/health

# Check logs
journalctl -u github_rate_limit_exporter -f  # systemd
docker logs github_rate_limit_exporter  # docker

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT License - see LICENSE file.

Releases

This project uses automatic releases. When you push to master with conventional commit messages, a new release is automatically created.

Resources

• Changelog - Version history
• Quick Reference - One-page command reference
• Helm Installation - Kubernetes deployment guide
• Helm Chart - Helm chart with Prometheus Operator
• Alert Examples - Prometheus alerting rules
• Auto Release Guide - Automatic release documentation
• GitHub Releases - Download binaries