Skip to main content

How gitGost Works

This page explains the technical implementation of gitGost, including the Git Smart HTTP protocol, metadata stripping process, and PR creation workflow.

Architecture Overview

gitGost acts as a transparent proxy between your Git client and GitHub, intercepting and rewriting commit metadata before creating pull requests through a bot account.

Git Smart HTTP Protocol

gitGost implements the Git Smart HTTP protocol, which GitHub uses for push/pull operations over HTTPS.

Protocol Endpoints

gitGost exposes four endpoints that mirror GitHub’s Smart HTTP protocol:
Source: internal/http/handlers.go

Pkt-Line Protocol

Git uses a framing protocol called pkt-line to transmit data. Each line is prefixed with a 4-byte hexadecimal length:
The length includes the 4-byte prefix itself. 0000 is a special flush packet. gitGost implements pkt-line parsing:
Source: internal/git/receive.go:20-50

Push Processing Flow

When you run git push gost my-branch:main, here’s what happens:
1

Client sends packfile

Your Git client sends a packfile containing:
  • Ref update commands (old SHA → new SHA)
  • Commit objects
  • Tree objects
  • Blob objects (file contents)
  • Optional push-options (e.g., pr-hash=a3f8c1d2)
Source: internal/git/receive.go:61-140
2

gitGost clones the target repository

To have the base objects for unpacking your commits, gitGost clones the target repository:
Source: internal/git/receive.go:143-167
3

Unpack the packfile

gitGost uses Git’s index-pack command to unpack your commits:
Source: internal/git/receive.go:204-225
4

Update HEAD to new commit

Source: internal/git/receive.go:228-240

Metadata Stripping

This is the core of gitGost’s anonymization. All commits in your push are rewritten to replace identifying metadata.

Commit Rewriting

gitGost recursively rewrites commits, preserving the tree (file contents) but replacing author and committer information:
Source: internal/git/receive.go:262-304

Recursive Rewriting

Source: internal/git/receive.go:306-368

What Gets Changed

What’s preserved:
  • Commit message (this becomes your PR description)
  • Tree hash (file contents are unchanged)
  • Parent relationships (history structure is preserved)
What’s changed:
  • Author name and email
  • Committer name and email
  • Commit timestamp (replaced with current time)
  • Commit hash (changes due to metadata changes)
The tree hash (file contents) remains identical. Only metadata changes. This ensures your code contribution is exactly what you intended.

Fork Creation and Management

After anonymizing commits, gitGost pushes them to a fork owned by the @gitgost-anonymous bot.

Creating or Reusing a Fork

Source: internal/github/pr.go:431-503

Pushing to the Fork

Source: internal/git/push.go:20-80

Fork Cleanup

Due to GitHub’s 40,000 repository limit per account, forks created by @gitgost-anonymous are manually deleted periodically. Your PR remains open, but the fork may be removed.
This is a GitHub platform constraint, not a gitGost limitation. Once your PR is merged or closed, the fork is no longer needed.

Pull Request Creation

The final step is creating a PR from the fork to the original repository.
Source: internal/github/pr.go:550-605

PR Structure

The created PR looks like this: Title: “Anonymous contribution via gitGost” Description:
Author: @gitgost-anonymous Branch: gitgost-anonymous:gitgost-1709654321 → owner:main

Updating Existing PRs

gitGost supports updating PRs without creating duplicates using the pr-hash push-option.

PR Hash Generation

The PR hash is deterministic—it’s generated from the owner/repo/branch combination:
Source: internal/github/pr.go:658-662

Update Workflow

1

Client sends pr-hash

The -o flag sends a push-option with the PR hash.
2

gitGost looks up existing PR

Source: internal/github/pr.go:666-729
3

Force-push to existing branch

If the PR exists, gitGost force-pushes to the same branch:
GitHub automatically updates the PR with the new commits.

Security and Abuse Prevention

gitGost implements multiple layers of protection:

Rate Limiting

Source: internal/http/handlers.go:733-759

Global Burst Detection

gitGost detects coordinated attacks across multiple IPs:
Source: internal/http/handlers.go:665-704

Panic Mode

Operators can instantly suspend the service if abuse is detected:
Source: internal/http/handlers.go:649-656, 142-157

Data Flow Summary

1

git push gost my-branch:main

Your Git client connects to gitgost.leapcell.app and sends a packfile over HTTPS.
2

Parse packfile (pkt-line protocol)

gitGost extracts ref updates, push-options, and the PACK data.
3

Clone target repo from GitHub

Provides base objects needed to unpack your commits.
4

Unpack commits (git index-pack)

Your commit objects are written to the temporary repository.
5

Rewrite commits recursively

All new commits are rewritten with anonymized author/committer/timestamp.
6

Create/reuse fork

Fork is created under @gitgost-anonymous (or reused if exists).
7

Push to fork

Anonymized commits are pushed to a unique branch in the fork.
8

Create PR

Pull request is opened from gitgost-anonymous:gitgost-NNNNNNNNNN to owner:main.
9

Return PR URL

Git client receives success message with PR URL.

Limitations and Trade-offs

gitGost makes implementation trade-offs for simplicity and performance. Understanding these limitations is critical for threat modeling.

What gitGost Cannot Hide

Network Identity

Your IP address is visible to the gitGost server and GitHub. Use Tor for IP anonymity.

Code Fingerprints

Coding style, variable naming, and domain knowledge can reveal identity through stylometry.

Timing Correlation

If you push and the PR appears immediately, observers can correlate timing.

Repository Size

Max 500 MB repositories, 10 MB commits. Not suitable for large contributions.

Trust Assumptions

You must trust:
  1. The gitGost operator (doesn’t add telemetry or log IPs)
  2. Your network provider (use VPN/Tor if concerned)
  3. GitHub (sees your IP during PR creation)
For zero-trust scenarios, self-host your own instance.

Source Code References

All code excerpts in this documentation are from the actual gitGost implementation:
  • Protocol handlers: internal/http/handlers.go
  • Git operations: internal/git/receive.go, internal/git/push.go
  • GitHub API: internal/github/pr.go
  • Threat model: THREAT_MODEL.md
  • Privacy guarantees: Privacy Guarantees.md
View the full source: github.com/livrasand/gitGost

Next Steps

Quickstart

Try gitGost with your first anonymous contribution

Threat Model

Understand what gitGost protects against

Self-Hosting

Run your own gitGost instance

API Reference

Complete API documentation

Transparency matters. All gitGost code is open source and auditable. If you find vulnerabilities, please report them via the security policy.