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

OpenTelemetry tracing is experimental and subject to change.

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.

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

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_role_id: ""          # AppRole role ID
  # vault_secret_id: ""        # AppRole secret ID

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)
  # 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

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:                        # OpenTelemetry tracing (experimental)
#   enabled: false
#   endpoint: ""               # OTLP exporter endpoint (e.g. http://localhost:4317)
#   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"

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), and tokens.max_duration (captured at server startup).

# Reload configuration
kill -USR1 $(pidof ghp)