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 personal access token with Validation: The token must belong to an account with access to create forks and PRs. Recommended to use a dedicated bot account (e.g.,
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
reposcope (full control of private repositories) - Copy the token
.env or environment.Example:gitgost-anonymous).Server Configuration
Variables controlling the HTTP server behavior.Port on which the HTTP server listens.Valid values: Any valid port number (1-65535).Example:Note: If deploying behind a reverse proxy, ensure the proxy forwards to this port.Loaded in:
internal/config/config.go:26Maximum duration for reading the entire request, including the body.Valid values: Any valid Go duration (e.g., Recommendation: Increase for large repositories or slow networks.Loaded in:
30s, 1m, 500ms).Example:internal/config/config.go:27Maximum duration before timing out writes of the response.Valid values: Any valid Go duration (e.g., Recommendation: Increase for large pushes that take longer to process.Loaded in:
30s, 1m, 500ms).Example:internal/config/config.go:28Format for application logs.Valid values:Recommendation: Use
text- Human-readable text format (default)json- Structured JSON format (recommended for production)
json in production for structured logging and easier parsing.Loaded in: internal/config/config.go:31Authentication
Variables for API authentication (non-git endpoints).Optional API key for authenticating non-git endpoints (no auth if empty).Behavior:Usage:Affected endpoints:
- If not set (empty string): No authentication required for any endpoint.
- If set: All non-git endpoints require the
X-Gitgost-Keyheader with this value.
/api/stats/api/recent-prs/api/pr-status/:hash/metrics(if auth is enabled)
/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)
internal/config/config.go:29Database (Supabase)
Variables for persistent statistics storage using Supabase.Supabase project URL for storing PR statistics (disabled if empty).Format: How to get:
https://your-project-id.supabase.coExample:- Create a project at https://supabase.com/dashboard
- Navigate to Project Settings → API
- Copy the “Project URL”
internal/config/config.go:32Initialized in: cmd/server/main.go:43-48Supabase anonymous/public API key (disabled if empty).Example:How to get:
- Create a project at https://supabase.com/dashboard
- Navigate to Project Settings → API
- Copy the “anon” or “public” key
SUPABASE_URL and SUPABASE_KEY must be set for Supabase to be enabled.Loaded in: internal/config/config.go:33Notifications (ntfy)
Variables for admin notifications via ntfy.sh.Base URL for ntfy notification service.Example (self-hosted):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 topic name for admin alerts (disabled if empty).Example: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/
internal/config/config.go:35Initialized in: cmd/server/main.go:51Public-facing URL of the gitGost service.Example: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.Password for the panic button endpoint (disabled if empty).Required for production: This password protects the Security:Rate limiting: The
/admin/panic and /admin/rollback endpoints.Example:- 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.
/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:51Build Information (Optional)
These are typically set at build time via-ldflags, but can also be environment variables.
Git commit hash of the build.Example:Typically set via:Exposed in:
/health endpoint and build info.Loaded in: cmd/server/main.go:16-31Configuration 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
Validation Script
Create a script to validate your environment configuration: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
Variable is set but not recognized
Cause: The
.env file may not be in the working directory.Solution:- Ensure
.envis in the same directory as the binary - Or set the variable directly:
export GITHUB_TOKEN=... - Verify with:
env | grep GITHUB_TOKEN
Duration parsing error
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
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