Environment Variables Reference

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.

string

required

GitHub personal access token with repo permissions.Required for: All push operations, PR creation, fork management.How to get:

Visit https://github.com/settings/tokens
Generate a new token (classic)
Select the repo scope (full control of private repositories)
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.

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

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

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

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

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.

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:

Create a project at https://supabase.com/dashboard
Navigate to Project Settings → API
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

string

default:""

Supabase anonymous/public API key (disabled if empty).Example:

SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

How to get:

Create a project at https://supabase.com/dashboard
Navigate to Project Settings → API
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.

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)

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:

Subscribe to the topic: https://ntfy.sh/gitgost-admin-alerts
Or via CLI: ntfy subscribe gitgost-admin-alerts
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

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.

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.

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

Variable	Type	Description
`GITHUB_TOKEN`	`string`	GitHub API token with `repo` permissions

Optional Variables

Variable	Type	Default	Description
`PORT`	`string`	`8080`	Server listening port
`READ_TIMEOUT`	`duration`	`30s`	HTTP read timeout
`WRITE_TIMEOUT`	`duration`	`30s`	HTTP write timeout
`LOG_FORMAT`	`string`	`text`	Log format (`text` or `json`)
`GITGOST_API_KEY`	`string`	`""`	API key for non-git endpoints
`SUPABASE_URL`	`string`	`""`	Supabase project URL
`SUPABASE_KEY`	`string`	`""`	Supabase API key
`PANIC_PASSWORD`	`string`	`""`	Admin panic button password
`NTFY_ADMIN_TOPIC`	`string`	`""`	ntfy topic for admin alerts
`NTFY_BASE_URL`	`string`	`https://ntfy.sh`	ntfy service URL
`SERVICE_URL`	`string`	`https://gitgost.leapcell.app`	Public 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

Variable is set but not recognized

Cause: The .env file may not be in the working directory.Solution:

Ensure .env is in the same directory as the binary
Or set the variable directly: export GITHUB_TOKEN=...
Verify with: env | grep GITHUB_TOKEN

Duration parsing error

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

Supabase not initializing

Cause: Both SUPABASE_URL and SUPABASE_KEY must be set.Solution:

Check both variables are present: env | grep SUPABASE
Verify URL format: https://xxx.supabase.co (no trailing slash)
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

​Overview

​GitHub Configuration

​Server Configuration

​Authentication

​Database (Supabase)

​Notifications (ntfy)

​Admin & Security

​Build Information (Optional)

​Configuration Summary Table

​Required Variables

​Optional Variables

​Environment File Example

​Validation Script

​Best Practices

Use .env Files

Rotate Secrets

Use JSON Logs

Enable Supabase

​Troubleshooting

​Variable Not Loading

​Next Steps

Configuration Guide

Requirements

Docker Deployment

Overview

GitHub Configuration

Server Configuration

Authentication

Database (Supabase)

Notifications (ntfy)

Admin & Security

Build Information (Optional)

Configuration Summary Table

Required Variables

Optional Variables

Environment File Example

Validation Script

Best Practices

Troubleshooting

Variable Not Loading

Next Steps