Server configuration is loaded from a YAML file (via --config flag or GHP_CONFIG env var). Environment variables with the GHP_ prefix override values from the config file.

Environment Variables

Core

Database

Server

GitHub

TLS

Tokens

Logging

Metrics

OpenTelemetry

ghp emits all logs as OpenTelemetry log records. They are always written to the console (per the Logging settings); enabling otel additionally exports every record to an OTLP collector. See Monitoring → Logging for the record format.

OAuth Broker

See OAuth Broker for integration details.

Border Policy

See Token Type Border Policy for details.

Release Controls

See Release Download Controls for details.

Codeload Redirect

See Codeload Redirect for details.

Git Cache

See Git Cache for details.

Full YAML Reference

# encryption_key: ""            # WARNING: prefer GHP_ENCRYPTION_KEY env var; never commit this to version control
                                 # Not required when database.driver is "vault" (Vault encrypts at rest)

github:
  client_id: ""
  client_secret: ""
  app_id: 0                    # GitHub App ID (enables gha_ agent tokens)
  private_key_file: ""         # path to PEM file for GitHub App authentication
  # private_key: ""            # or inline PEM content (useful in containers)
  enterprise_slug: ""
  # base_url: ""               # GHES API base URL (e.g. https://ghes.example.com/api/v3); omit for github.com
  # enterprise_exceptions:     # exempt targets from the enterprise access restriction header
  #                            # (YAML only — nested lists cannot be set via environment variables)
  #   - match:                 # account names ("torvalds", "kubernetes") or owner/repo pairs
  #       - torvalds
  #       - kubernetes/website
  #     teams:                 # optional: restrict who may use this exception (org/team-slug);
  #       - my-org/oss-team    #   requires the default app installed on the org with members:read
  #     identity:              # optional: substitute a managed credential for matching requests
  #       app_record_id: ""    #   database record ID of a GitHub App (see admin UI)

database:
  driver: "sqlite"             # "sqlite", "postgres", or "vault"
  dsn: "ghp.db"
  # vault_addr: ""             # Vault server address (vault driver only)
  # vault_mount: "secret"      # KV v2 mount path
  # vault_path: "ghp"          # key prefix within the mount
  # vault_auth_method: "approle"  # "approle" (default) or "kubernetes"
  # vault_role_id: ""          # AppRole role ID (auth_method=approle)
  # vault_secret_id: ""        # AppRole secret ID (auth_method=approle)
  # vault_k8s_role: ""         # Vault role to authenticate as (auth_method=kubernetes)
  # vault_k8s_mount: "kubernetes"  # auth mount path (auth_method=kubernetes)
  # vault_k8s_token_path: "/var/run/secrets/kubernetes.io/serviceaccount/token"

server:
  listen: ":8080"              # plain HTTP mode (development or behind reverse proxy)
  https_listen: ":443"         # TLS mode (recommended for production)
  http_listen: ":80"           # HTTP-to-HTTPS redirect server
  management_host: ""          # hostname for management UI (e.g. ghp.example.com)
  base_url: ""                 # public base URL (e.g. https://ghp.example.com)
  # trust_proxy_headers: false # honour Forwarded / X-Forwarded-Proto / X-Forwarded-Host
                                #   for URL construction when base_url is unset. Set true
                                #   only behind a trusted reverse proxy that strips and
                                #   rewrites these headers. Prefer setting base_url.
  # client_ip_header: ""       # the single forwarded header trusted for client
                                #   attribution in access logs, ghp_client_request_total,
                                #   and the per-IP auth rate limiter: "forwarded" (RFC 7239
                                #   for=), "x-real-ip", or "x-forwarded-for". Set to the
                                #   one header your reverse proxy sets; all other forwarded
                                #   headers are ignored so clients cannot spoof attribution
                                #   via a header the proxy passes through untouched. Empty
                                #   trusts no header: the peer address is always used.
  # systemd_socket_activation: false  # accept sockets from systemd

tls:
  certificates:
    - cert_file: "/path/to/cert.pem"
      key_file: "/path/to/key.pem"
  min_version: "1.2"           # minimum TLS version: "1.2" (default) or "1.3"

tokens:
  default_duration: "24h"
  max_duration: "168h"         # 7 days
  allow_no_expiry: false       # set true to allow tokens with no expiry (duration: "never")
  expired_token_retention_period: "720h"  # hard-delete expired/revoked tokens after 30 days (set to 0 to disable)

logging:
  output: "stdout"             # "stdout" or "file"
  level: "info"                # "debug", "info", "warn", "error"
  file:
    path: "/var/log/ghp/ghp.log"

metrics:
  enabled: true                # set to false to disable
  listen: ":9136"              # dedicated metrics server port

# otel:                        # Export OpenTelemetry log records to an OTLP collector
#   enabled: false             # logs are always written to the console regardless
#   endpoint: ""               # OTLP exporter endpoint (e.g. http://localhost:4317); http:// disables TLS
#   protocol: "grpc"           # "grpc" or "http"

auth:
  jwt_private_key_file: ""     # RSA private key for OAuth broker JWT signing (RS256)
  # jwt_private_key: ""        # or inline PEM content
  allowed_redirects:            # permitted redirect_uri values for broker flow
    - "https://app.example.com/auth/callback"
    - "*.internal.example.com"  # wildcard domain patterns supported

block:
  ghp: false                   # block GitHub personal access tokens (ghp_)
  gho: false                   # block GitHub OAuth access tokens (gho_)
  ghu: false                   # block GitHub user-to-server tokens (ghu_)
  ghs: false                   # block GitHub server-to-server tokens (ghs_)
  ghr: false                   # block GitHub refresh tokens (ghr_)
  anonymous_git: false         # block unauthenticated git smart HTTP traffic

releases:
  mode: ""                     # "block", "redirect", or "" (disabled)
  redirect_to: ""              # absolute URL base for redirect mode
  redirect_head_check: false   # HEAD-check redirect target; serve 404 page if target returns 404
  redirect_head_check_netrc: ""  # path to netrc file for HEAD check auth (optional)
  redirect_not_found_template: ""  # path to custom 404 HTML template (optional)
  allow:                       # org or org/repo entries exempt from policy
    - "myorg"
    - "trusted/tool"

codeload:
  redirect_to: ""              # absolute URL base for redirecting codeload archive requests; passthrough when empty
  allow:                       # org or org/repo entries that pass through to upstream codeload
    - "myorg"

cache:
  enabled: false               # enable git clone/fetch caching
  storage_path: "cache"        # local path for cached bare repos
  # s3_bucket: ""              # S3 bucket for shared cache storage (optional)
  # s3_region: ""              # AWS region
  # s3_endpoint: ""            # custom S3-compatible endpoint (MinIO, etc)

admins:
  - "alice"
  - "bob"

dev_mode: false                # enable test endpoints (never use in production)

Encryption Key

Generate an encryption key:

export GHP_ENCRYPTION_KEY=$(openssl rand -hex 32)

This key encrypts GitHub tokens at rest. Store it securely — if lost, stored tokens cannot be decrypted. Use an environment variable or secrets manager rather than putting it in the config file.

Hot Reloading

The following settings can be changed without restarting the server by sending SIGUSR1 to the ghp process:

• admins — admin user list (roles are re-synced immediately)
• tokens.default_duration — default token lifetime applied to new tokens
• auth.allowed_redirects — OAuth broker allowed redirects
• block — border policy settings (anonymous git, token type blocking)
• releases — release download policy and allow list (mode, redirect_to, redirect_head_check, allow); note that redirect_head_check_netrc and redirect_not_found_template are loaded once at startup and require a restart to change Settings that require a restart: database driver/DSN, server listen addresses, cache (enable/disable, storage path), TLS certificates, the encryption key, logging configuration, metrics enable/disable, OAuth broker enable/disable and signing key (auth.jwt_private_key / auth.jwt_private_key_file), tokens.max_duration, and tokens.allow_no_expiry (both captured at server startup).

# Reload configuration
kill -USR1 $(pidof ghp)