Skip to main content

Overview

This page documents all environment variables used by gitGost, grouped by category. Variables are loaded from the environment or a .env file via internal/config/config.go.
All environment variables are optional with defaults, except GITHUB_TOKEN which is required for push operations.

GitHub Configuration

Variables related to GitHub API authentication and operations.
GITHUB_TOKEN
string
required
GitHub personal access token with repo permissions.Required for: All push operations, PR creation, fork management.How to get:
  1. Visit https://github.com/settings/tokens
  2. Generate a new token (classic)
  3. Select the repo scope (full control of private repositories)
  4. Copy the token
Security: Never commit this to version control. Store in .env or environment.Example:
GITHUB_TOKEN=ghp_1234567890abcdefghijklmnopqrstuvwxyz
Validation: The token must belong to an account with access to create forks and PRs. Recommended to use a dedicated bot account (e.g., gitgost-anonymous).

Server Configuration

Variables controlling the HTTP server behavior.
PORT
string
default:"8080"
Port on which the HTTP server listens.Valid values: Any valid port number (1-65535).Example:
PORT=3000
Note: If deploying behind a reverse proxy, ensure the proxy forwards to this port.Loaded in: internal/config/config.go:26
READ_TIMEOUT
duration
default:"30s"
Maximum duration for reading the entire request, including the body.Valid values: Any valid Go duration (e.g., 30s, 1m, 500ms).Example:
READ_TIMEOUT=60s
Recommendation: Increase for large repositories or slow networks.Loaded in: internal/config/config.go:27
WRITE_TIMEOUT
duration
default:"30s"
Maximum duration before timing out writes of the response.Valid values: Any valid Go duration (e.g., 30s, 1m, 500ms).Example:
WRITE_TIMEOUT=60s
Recommendation: Increase for large pushes that take longer to process.Loaded in: internal/config/config.go:28
LOG_FORMAT
string
default:"text"
Format for application logs.Valid values:
  • text - Human-readable text format (default)
  • json - Structured JSON format (recommended for production)
Example:
LOG_FORMAT=json
Recommendation: Use json in production for structured logging and easier parsing.Loaded in: internal/config/config.go:31

Authentication

Variables for API authentication (non-git endpoints).
GITGOST_API_KEY
string
default:""
Optional API key for authenticating non-git endpoints (no auth if empty).Behavior:
  • If not set (empty string): No authentication required for any endpoint.
  • If set: All non-git endpoints require the X-Gitgost-Key header with this value.
Git operations are always anonymous regardless of this setting.Example:
GITGOST_API_KEY=gitgost-secure-key-12345
Usage:
curl -H "X-Gitgost-Key: gitgost-secure-key-12345" \
  http://localhost:8080/api/stats
Affected endpoints:
  • /api/stats
  • /api/recent-prs
  • /api/pr-status/:hash
  • /metrics (if auth is enabled)
Not affected:
  • /v1/gh/:owner/:repo/git-receive-pack (always anonymous)
  • /v1/gh/:owner/:repo/git-upload-pack (always anonymous)
  • /v1/gh/:owner/:repo/info/refs (always anonymous)
  • /health (always public)
Loaded in: internal/config/config.go:29

Database (Supabase)

Variables for persistent statistics storage using Supabase.
SUPABASE_URL
string
default:""
Supabase project URL for storing PR statistics (disabled if empty).Format: https://your-project-id.supabase.coExample:
SUPABASE_URL=https://abcdefghijklmnop.supabase.co
How to get:
  1. Create a project at https://supabase.com/dashboard
  2. Navigate to Project Settings → API
  3. Copy the “Project URL”
Behavior if not set: Server starts with a warning: “Supabase not configured, stats will not be persisted”. Stats remain in memory only.Loaded in: internal/config/config.go:32Initialized in: cmd/server/main.go:43-48
SUPABASE_KEY
string
default:""
Supabase anonymous/public API key (disabled if empty).Example:
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
How to get:
  1. Create a project at https://supabase.com/dashboard
  2. Navigate to Project Settings → API
  3. Copy the “anon” or “public” key
Security: This key is safe to expose in client-side code. It only allows operations permitted by Row Level Security (RLS) policies.Note: Both SUPABASE_URL and SUPABASE_KEY must be set for Supabase to be enabled.Loaded in: internal/config/config.go:33

Notifications (ntfy)

Variables for admin notifications via ntfy.sh.
NTFY_BASE_URL
string
default:"https://ntfy.sh"
Base URL for ntfy notification service.Example (self-hosted):
NTFY_BASE_URL=https://ntfy.yourdomain.com
Default: Uses the public ntfy.sh service.Use case: Set this if you run a self-hosted ntfy instance for privacy.Loaded in: Extracted from .env.example:28 (not explicitly in config.go, may be loaded by handlers)
NTFY_ADMIN_TOPIC
string
default:""
ntfy topic name for admin alerts (disabled if empty).Example:
NTFY_ADMIN_TOPIC=gitgost-admin-alerts
Behavior if set: Admin events (rate limit exceeded, suspicious activity) are sent to this topic.How to receive:
  1. Subscribe to the topic: https://ntfy.sh/gitgost-admin-alerts
  2. Or via CLI: ntfy subscribe gitgost-admin-alerts
  3. Or via mobile app: https://ntfy.sh/docs/subscribe/phone/
Security: Choose a unique, random topic name to avoid unauthorized subscriptions.Loaded in: internal/config/config.go:35Initialized in: cmd/server/main.go:51
SERVICE_URL
string
default:"https://gitgost.leapcell.app"
Public-facing URL of the gitGost service.Example:
SERVICE_URL=https://gitgost.yourdomain.com
Use case: Used in ntfy notification action buttons (e.g., “Activate Panic”, “Deactivate Panic”).Recommendation: Set this to your actual domain in production.Loaded in: Extracted from .env.example:31 (not explicitly in config.go)

Admin & Security

Variables for administrative control and security features.
PANIC_PASSWORD
string
default:""
Password for the panic button endpoint (disabled if empty).Required for production: This password protects the /admin/panic and /admin/rollback endpoints.Example:
PANIC_PASSWORD=my-very-strong-random-password-12345
Security:
  • Use a strong, unique password (min 20 characters recommended).
  • Never use default values.
  • Store securely (e.g., in a password manager or secrets vault).
  • Rotate periodically.
Usage:
# Suspend service
curl -X POST https://gitgost.yourdomain.com/admin/panic \
  -H "Content-Type: application/json" \
  -d '{"password":"my-very-strong-random-password-12345","active":true}'

# Restore service
curl -X POST https://gitgost.yourdomain.com/admin/panic \
  -H "Content-Type: application/json" \
  -d '{"password":"my-very-strong-random-password-12345","active":false}'
Rate limiting: The /admin/panic endpoint is protected by strict per-IP rate limiting (10 requests/IP/minute, see internal/http/router.go:15-19).Loaded in: internal/config/config.go:34Initialized in: cmd/server/main.go:51

Build Information (Optional)

These are typically set at build time via -ldflags, but can also be environment variables.
COMMIT_HASH
string
default:"main"
Git commit hash of the build.Example:
COMMIT_HASH=abc1234
Typically set via:
go build -ldflags "-X main.commitHash=$(git rev-parse --short HEAD)" ./cmd/server
Exposed in: /health endpoint and build info.Loaded in: cmd/server/main.go:16-31

Configuration Summary Table

Required Variables

VariableTypeDescription
GITHUB_TOKENstringGitHub API token with repo permissions

Optional Variables

VariableTypeDefaultDescription
PORTstring8080Server listening port
READ_TIMEOUTduration30sHTTP read timeout
WRITE_TIMEOUTduration30sHTTP write timeout
LOG_FORMATstringtextLog format (text or json)
GITGOST_API_KEYstring""API key for non-git endpoints
SUPABASE_URLstring""Supabase project URL
SUPABASE_KEYstring""Supabase API key
PANIC_PASSWORDstring""Admin panic button password
NTFY_ADMIN_TOPICstring""ntfy topic for admin alerts
NTFY_BASE_URLstringhttps://ntfy.shntfy service URL
SERVICE_URLstringhttps://gitgost.leapcell.appPublic service URL

Environment File Example

Complete .env file with all variables:
.env
# ============================================
# gitGost Environment Configuration
# ============================================

# -------------------- REQUIRED --------------------

# GitHub personal access token with repo permissions
# Get from: https://github.com/settings/tokens
GITHUB_TOKEN=ghp_your_actual_token_here

# -------------------- SERVER --------------------

# Server port (default: 8080)
PORT=8080

# HTTP timeouts (default: 30s)
READ_TIMEOUT=30s
WRITE_TIMEOUT=30s

# Log format: "text" or "json" (default: text)
LOG_FORMAT=json

# -------------------- AUTHENTICATION --------------------

# API key for non-git endpoints (optional, no auth if empty)
GITGOST_API_KEY=gitgost-secure-key-12345

# -------------------- DATABASE --------------------

# Supabase configuration for persistent stats (optional)
# Get from: https://supabase.com/dashboard
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_supabase_anon_key_here

# -------------------- NOTIFICATIONS --------------------

# ntfy base URL (default: https://ntfy.sh)
NTFY_BASE_URL=https://ntfy.sh

# ntfy topic for admin alerts (optional)
NTFY_ADMIN_TOPIC=gitgost-admin-alerts

# Public service URL for ntfy action buttons
SERVICE_URL=https://gitgost.yourdomain.com

# -------------------- ADMIN & SECURITY --------------------

# Panic button password (REQUIRED for production)
# Use a strong, unique password
PANIC_PASSWORD=my-very-strong-random-password-12345

Validation Script

Create a script to validate your environment configuration:
validate-env.sh
#!/bin/bash
set -e

echo "=== gitGost Environment Validation ==="

# Load .env if it exists
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
fi

# Check required variables
if [ -z "$GITHUB_TOKEN" ]; then
    echo "❌ GITHUB_TOKEN is not set (REQUIRED)"
    exit 1
else
    echo "✅ GITHUB_TOKEN is set"
fi

# Check optional but recommended variables
if [ -z "$PANIC_PASSWORD" ]; then
    echo "⚠️  PANIC_PASSWORD is not set (recommended for production)"
else
    echo "✅ PANIC_PASSWORD is set"
fi

if [ -z "$SUPABASE_URL" ] || [ -z "$SUPABASE_KEY" ]; then
    echo "⚠️  Supabase is not configured (stats will not be persisted)"
else
    echo "✅ Supabase is configured"
fi

# Validate GitHub token
echo ""
echo "Testing GitHub API access..."
RESPONSE=$(curl -s -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user)
USERNAME=$(echo $RESPONSE | grep -o '"login":"[^"]*' | cut -d'"' -f4)

if [ -n "$USERNAME" ]; then
    echo "✅ GitHub token is valid (logged in as: $USERNAME)"
else
    echo "❌ GitHub token is invalid or lacks permissions"
    exit 1
fi

# Test Supabase connection if configured
if [ -n "$SUPABASE_URL" ] && [ -n "$SUPABASE_KEY" ]; then
    echo ""
    echo "Testing Supabase connection..."
    STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
        "$SUPABASE_URL/rest/v1/" \
        -H "apikey: $SUPABASE_KEY" \
        -H "Authorization: Bearer $SUPABASE_KEY")
    
    if [ "$STATUS" != "401" ]; then
        echo "✅ Supabase connection successful (HTTP $STATUS)"
    else
        echo "❌ Supabase authentication failed (HTTP $STATUS)"
    fi
fi

echo ""
echo "=== Validation Complete ==="
Usage:
chmod +x validate-env.sh
./validate-env.sh

Best Practices

Use .env Files

Store environment variables in .env files and add them to .gitignore.

Rotate Secrets

Rotate GITHUB_TOKEN and PANIC_PASSWORD periodically.

Use JSON Logs

Set LOG_FORMAT=json in production for structured logging.

Enable Supabase

Configure Supabase for persistent statistics and analytics.

Troubleshooting

Variable Not Loading

Cause: The .env file may not be in the working directory.Solution:
  1. Ensure .env is in the same directory as the binary
  2. Or set the variable directly: export GITHUB_TOKEN=...
  3. Verify with: env | grep GITHUB_TOKEN
Cause: Invalid duration format for READ_TIMEOUT or WRITE_TIMEOUT.Solution: Use valid Go duration strings:
  • ✅ Valid: 30s, 1m, 500ms, 1h30m
  • ❌ Invalid: 30, 1 minute, 30sec
Cause: Both SUPABASE_URL and SUPABASE_KEY must be set.Solution:
  1. Check both variables are present: env | grep SUPABASE
  2. Verify URL format: https://xxx.supabase.co (no trailing slash)
  3. Test connection manually: curl "$SUPABASE_URL/rest/v1/" -H "apikey: $SUPABASE_KEY"

Next Steps

Configuration Guide

Learn how to set up and configure gitGost

Requirements

Review system requirements

Docker Deployment

Deploy with Docker and Docker Compose

Build docs developers (and LLMs) love