Troubleshooting gitGost

Quick solutions to common operational problems.

Push Errors

Error: rate limit exceeded

Symptom:

remote: Rate limit exceeded: max 5 PRs per hour per IP.
remote: Please try again later.
! [remote rejected] main -> main (push rejected: rate limit exceeded)
error: failed to push some refs

Cause:IP address has exceeded 5 PRs in the last hour (from internal/http/handlers.go:160-173).Solutions:

Wait for rate limit to reset (up to 1 hour)

Use different IP address:

# Via VPN
vpn connect
git push gost my-feature:main

# Via Tor (see README for setup)
torsocks git push gost my-feature:main

Verify you’re not in a loop:

# Check recent pushes
git log --oneline origin/main..HEAD

# Remove hook if causing repeated pushes
rm .git/hooks/pre-push

For operators:Rate limit is intentional abuse protection. Legitimate users rarely hit this limit. If seeing widespread complaints, consider increasing rateLimitMaxPRs in internal/http/handlers.go:562.

Error: service temporarily suspended

Symptom:

remote: SERVICE TEMPORARILY SUSPENDED
remote: The panic button has been activated. The service has been
remote: temporarily suspended due to detected bot activity
remote: sending mass PRs. Please try again in 15 minutes.

Cause:Service administrator activated panic mode due to abuse detection.Solutions:For users:

Wait 15-30 minutes and retry

Check service status:

curl https://gitgost.leapcell.app/api/status
# {"panic_mode": true} = suspended
# {"panic_mode": false} = active

For operators:Deactivate panic mode if threat has passed:

curl -X POST https://gitgost.leapcell.app/admin/panic \
  -H "Content-Type: application/json" \
  -d '{"password":"YOUR_PASSWORD","active":false}'

Error: failed to create fork

Symptom:

remote: gitGost: Creating fork...
remote: unpack ok
remote: error creating fork: API rate limit exceeded

Cause:GitHub API rate limit reached or @gitgost-anonymous account hit 40,000 repository cap.Solutions:For operators:

Check GitHub token rate limit:

curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
     https://api.github.com/rate_limit

Wait for reset (shown in X-RateLimit-Reset header)

Verify bot account status:

curl https://api.github.com/users/gitgost-anonymous/repos?per_page=1
# Check repository count

Clean up old forks:

# Manual cleanup script needed
# GitHub limits accounts to 40,000 repos (README.md:218)

Error: repository too large

Symptom:

error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413

Cause:Repository exceeds size limits:

Repo size: 500 MB max
Commit size: 10 MB max
Push size: 100 MB max

From README.md:213-215 and internal/http/router.go:49Solutions:

Reduce commit size:

# Find large files
git ls-files | xargs du -h | sort -h | tail -n 20

# Remove large files
git rm large-file.bin
git commit --amend

Use Git LFS for large files:

git lfs install
git lfs track "*.bin"
git add .gitattributes
git commit -m "Use LFS"

Split into smaller commits:

git reset HEAD~1
git add file1.txt
git commit -m "Part 1"
git add file2.txt  
git commit -m "Part 2"

Error: invalid ref name

Symptom:

remote: gitGost: Processing your anonymous contribution...
remote: unpack error: invalid ref name

Cause:Branch name contains invalid characters or Git protocol error.Solutions:

Use valid branch names:

# Valid
git checkout -b feature/fix-bug
git checkout -b hotfix-123

# Invalid (contains spaces, special chars)
git checkout -b "my feature"  # ❌
git checkout -b fix@bug       # ❌

Ensure clean push:

git push gost my-branch:main
# Format: local-branch:target-branch

Check for corruption:
```
git fsck
git gc
```

Authentication Issues

HTTP 401: Unauthorized

Symptom:

fatal: Authentication failed for 'https://gitgost.leapcell.app/'

Cause:Git credential helper trying to prompt for credentials (gitGost requires none).Solutions:

Disable credential helper temporarily:

git -c credential.helper= push gost my-branch:main

Remove stored credentials:

# Remove gitgost.leapcell.app from credential store
git credential reject <<EOF
protocol=https
host=gitgost.leapcell.app
EOF

Configure per-remote:

git config credential.https://gitgost.leapcell.app.helper ""

Note: GitGost is designed for anonymous access. No credentials are ever required.

Error: API key required

Symptom:

{"error": "API key required"}

Cause:Instance has GITGOST_API_KEY configured and your request lacks the key (rare for public instances).Solution:Git operations never require API keys. This error only appears on non-git endpoints. If pushing:

# Ensure using correct URL format
git remote set-url gost https://gitgost.leapcell.app/v1/gh/owner/repo

From internal/http/router.go:95-126: Git endpoints bypass API key checks.

Network & Connectivity

Connection timeout

Symptom:

fatal: unable to access 'https://gitgost.leapcell.app/': 
Failed to connect to gitgost.leapcell.app port 443: Connection timed out

Cause:

Service is down
Network/firewall blocking
DNS resolution failure

Solutions:

Check service status:

curl -I https://gitgost.leapcell.app/health
# Should return HTTP/2 200

Test DNS resolution:

nslookup gitgost.leapcell.app
dig gitgost.leapcell.app

Check firewall/proxy:

# Test with verbose
curl -v https://gitgost.leapcell.app/health

# Test from different network
# (mobile hotspot, VPN, etc.)

Verify SSL/TLS:

openssl s_client -connect gitgost.leapcell.app:443

Slow push performance

Symptom:Push takes 5+ minutes or times out.Cause:

Large repository size
Slow network connection
Using Tor (expected slowness)

Solutions:

Check repository size:
```
du -sh .git
# Should be < 500 MB
```

Increase Git timeout:

git config --global http.postBuffer 524288000  # 500 MB
git config --global http.timeout 300           # 5 minutes

If using Tor:

# Tor is slow by design (3-hop routing)
# Expected: 2-5 minutes for large pushes
# README.md:296 mentions this is normal

Use shallow clone to reduce size:

git clone --depth 1 source-repo
cd source-repo
# Make changes
git push gost my-branch:main

SSL certificate errors

Symptom:

fatal: unable to access 'https://gitgost.leapcell.app/':
SSL certificate problem: unable to get local issuer certificate

Cause:Outdated CA certificates or corporate SSL interception.Solutions:

Update CA certificates:

# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# macOS
brew install ca-certificates

# Windows
# Download from https://curl.se/docs/caextract.html

Verify certificate:

curl -v https://gitgost.leapcell.app/health 2>&1 | grep -i "certificate"

Temporary workaround (NOT recommended for production):

GIT_SSL_NO_VERIFY=true git push gost my-branch:main

Service Health Issues

High memory usage

Symptom:

{
  "memory": {
    "alloc": 524288000,
    "sys": 1073741824
  }
}

Cause:Memory leak or sustained high traffic.Diagnosis:

Check goroutine count:

curl https://gitgost.leapcell.app/metrics | jq '.goroutines'
# Should be < 100 idle, < 500 busy

Monitor over time:

while true; do
  echo "$(date): $(curl -s https://gitgost.leapcell.app/metrics | 
    jq '.memory.alloc')" | tee -a memory.log
  sleep 60
done

Solutions:

Restart service (clears memory)

Increase memory limits:

# Leapcell: Adjust instance size
# Docker: Update container limits
docker run --memory=1g gitgost

Check for leaks in custom code

From internal/http/handlers.go:508-522: Metrics endpoint exposes runtime.MemStats.

Service won't start

Symptom:Service crashes immediately or fails health check.Diagnosis:

Check logs:

# Text format
tail -f app.log

# JSON format  
tail -f app.log | jq

Verify environment variables:

# Required:
echo $GITHUB_TOKEN       # Must be valid

# Optional but recommended:
echo $PANIC_PASSWORD
echo $NTFY_ADMIN_TOPIC
echo $SUPABASE_URL
echo $SUPABASE_KEY

Common Issues:

Missing GitHub token:
```
export GITHUB_TOKEN="ghp_..."
```

Invalid port binding:

# Use high port if permission denied
export PORT=8080

Database connection failure:

# Test Supabase connection
curl -H "apikey: $SUPABASE_KEY" "$SUPABASE_URL/rest/v1/"

Metrics endpoint returns errors

Symptom:

curl https://gitgost.leapcell.app/metrics
{"error": "internal server error"}

Cause:Rare runtime panic in metrics collection.Solutions:

Check health endpoint instead:

curl https://gitgost.leapcell.app/health

Review logs for panics:

grep -i "panic" app.log
grep -i "error" app.log | grep metrics

Restart service if persistent

PR Creation Issues

PR not appearing on GitHub

Symptom:Push succeeds but no PR is visible on GitHub.Cause:

PR was created but closed by maintainer
Network error after push but before PR creation
GitHub API rate limit

Solutions:

Search for PR:

# Check if PR exists (even if closed)
gh pr list --repo owner/repo --state all --author gitgost-anonymous

Check push response:

git push gost my-branch:main
# Look for:
# remote: PR URL: https://github.com/owner/repo/pull/123

Verify fork exists:

curl https://api.github.com/repos/gitgost-anonymous/repo
# Should return 200 if fork succeeded

Retry push:
```
git push gost my-branch:main --force
```

PR created with wrong branch name

Symptom:PR has branch name like gitgost-a3f7b9c2 instead of your branch name.Cause:This is expected behavior. GitGost generates deterministic branch names for tracking.Explanation:From internal/http/handlers.go:245-252:

branchFromHash := fmt.Sprintf("gitgost-%s", receivedPRHash)

Branch names are based on PR hash to enable updates via push options.Not a bug: This enables the update workflow:

git push gost my-branch:main -o pr-hash=a3f7b9c2

Logging & Debugging

No logs appearing

Symptom:Log file empty or no output.Solutions:

Check log configuration:

echo $LOG_FORMAT  # Should be "text" or "json"

Verify logger initialization:

# Logs should start with:
# [gitGost] Privacy mode: Minimal logging enabled
# [gitGost] Server started - Ready for anonymous contributions

Check stdout/stderr:

# Logs go to stdout by default (logging.go:22-24)
# Redirect if needed:
./gitgost 2>&1 | tee app.log

Want more detailed logs

Issue:Logs are too minimal for debugging.Explanation:GitGost intentionally logs minimally to protect user privacy (from internal/utils/logging.go:27-29):

Log("Privacy mode: Minimal logging enabled")
Log("Server started - Ready for anonymous contributions")

For debugging:

Use JSON format for structure:
```
export LOG_FORMAT=json
```

Monitor metrics endpoint:

watch -n 5 'curl -s https://gitgost.leapcell.app/metrics | jq'

Add temporary debug logs (development only):
```
utils.Log("DEBUG: Step completed")
```

Privacy reminder: Never log IPs, user agents, or timing patterns that could deanonymize users.

Getting Help

Still stuck?

Check these resources:

Source code: Inspect handlers in internal/http/handlers.go
GitHub issues: Search existing issues at github.com/livrasand/gitGost
Security issues: Email [email protected] (see SECURITY.md:11)
Anonymous reporting: Use gitGost itself to submit a PR

When reporting issues:✅ Include: Error messages, steps to reproduce, expected behavior❌ Avoid: Logs with IPs, personal info, credentials

Diagnostic Commands Reference

# Service health
curl https://gitgost.leapcell.app/health
curl https://gitgost.leapcell.app/metrics
curl https://gitgost.leapcell.app/api/status

# Test push (dry-run)
git push --dry-run gost my-branch:main

# Verbose Git output
GIT_CURL_VERBOSE=1 GIT_TRACE=1 git push gost my-branch:main

# Check remote configuration
git remote -v
git config --get-regexp 'remote.gost.*'

# Network diagnostics
curl -v https://gitgost.leapcell.app/health
ping gitgost.leapcell.app
traceroute gitgost.leapcell.app

# GitHub API rate limits
curl -H "Authorization: token $GITHUB_TOKEN" \
     https://api.github.com/rate_limit

Deployment

Operations

Troubleshooting

Troubleshooting gitGost

Push Errors

Authentication Issues

Network & Connectivity

Service Health Issues

PR Creation Issues

Logging & Debugging

Getting Help

Still stuck?

Diagnostic Commands Reference

Next Steps

Monitoring

Moderation

Build docs developers (and LLMs) love

Deployment

Operations

​Troubleshooting gitGost

​Push Errors

​Authentication Issues

​Network & Connectivity

​Service Health Issues

​PR Creation Issues

​Logging & Debugging

​Getting Help

Still stuck?

​Diagnostic Commands Reference

​Next Steps

Monitoring

Moderation

Build docs developers (and LLMs) love

Troubleshooting gitGost

Push Errors

Authentication Issues

Network & Connectivity

Service Health Issues

PR Creation Issues

Logging & Debugging

Getting Help

Diagnostic Commands Reference

Next Steps