github-api-proxy

GitHub REST API Proxy

A high-performance reverse proxy for the GitHub REST API that provides authentication balancing, rate limiting, caching, and monitoring capabilities.

Features

• Authentication Balancing: Distribute requests across multiple GitHub tokens/apps
• Rate Limiting: Built-in rate limiting with configurable requests per second
• Caching: Multiple storage backends (in-memory, BoltDB, S3) for response caching using bored-engineer/github-conditional-http-transport
• Monitoring: Prometheus metrics for rate limit tracking

Installation

go install github.com/bored-engineer/github-api-proxy@latest

Or build from source:

git clone https://github.com/bored-engineer/github-api-proxy.git
cd github-api-proxy
go build -o github-api-proxy .

Usage

Basic Usage

# Start with default settings (listens on 127.0.0.1:44879)
./github-api-proxy

# Start with custom listen address
./github-api-proxy --listen 0.0.0.0:8080

# Start with TLS
mkcert github-api-proxy.localhost
echo "127.0.0.1 github-api-proxy.localhost" | sudo tee -a /etc/hosts
./github-api-proxy --tls-cert ./github-api-proxy.localhost.pem --tls-key ./github-api-proxy.localhost-key.pem

Authentication

The proxy supports multiple authentication methods that can be used simultaneously:

Personal Access Tokens

./github-api-proxy --auth-token "ghp_your_token_here"

OAuth Apps

./github-api-proxy --auth-oauth "client_id:client_secret"

GitHub Apps

./github-api-proxy --auth-app "app_id:installation_id:private_key"

Multiple Authentication Methods

./github-api-proxy \
  --auth-token "ghp_token1" \
  --auth-token "ghp_token2" \
  --auth-oauth "client1:secret1" \
  --auth-app "app1:install1:key1"

Caching

In-Memory (Default)

./github-api-proxy

BoltDB

./github-api-proxy --bbolt-db /path/to/cache.db --bbolt-bucket my-bucket

S3

./github-api-proxy \
  --s3-bucket github-rest-api-proxy \
  --s3-region us-west-2 \
  --s3-prefix cache/

Rate Limiting

# Limit to 5000 requests per second per authentication token
./github-api-proxy --rps 5000

Custom GitHub API URL

# Use GitHub Enterprise
./github-api-proxy --url "https://github.company.com/api/v3/"

Configuration Options

API Endpoints

• / - Proxies all requests to the upstream GitHub REST API
• /metrics - Prometheus metrics endpoint

Monitoring

The proxy exposes Prometheus metrics at /metrics:

• github_rate_limit_remaining - Number of requests remaining in current rate limit window
• github_rate_limit_reset - Unix timestamp when rate limit window resets