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:Pkt-Line Protocol
Git uses a framing protocol called pkt-line to transmit data. Each line is prefixed with a 4-byte hexadecimal length:0000 is a special flush packet.
gitGost implements pkt-line parsing:
Push Processing Flow
When you rungit push gost my-branch:main, here’s what happens:
1
Client sends packfile
Your Git client sends a packfile containing:Source: internal/git/receive.go:61-140
- Ref update commands (old SHA → new SHA)
- Commit objects
- Tree objects
- Blob objects (file contents)
- Optional push-options (e.g.,
pr-hash=a3f8c1d2)
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 Source: internal/git/receive.go:204-225
index-pack command to unpack your commits:4
Update HEAD to new commit
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:Recursive Rewriting
What Gets Changed
- Commit message (this becomes your PR description)
- Tree hash (file contents are unchanged)
- Parent relationships (history structure is preserved)
- 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
Pushing to the Fork
Fork Cleanup
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.PR Structure
The created PR looks like this: Title: “Anonymous contribution via gitGost” Description:@gitgost-anonymous
Branch: gitgost-anonymous:gitgost-1709654321 → owner:main
Updating Existing PRs
gitGost supports updating PRs without creating duplicates using thepr-hash push-option.
PR Hash Generation
The PR hash is deterministic—it’s generated from the owner/repo/branch combination:Update Workflow
1
Client sends pr-hash
-o flag sends a push-option with the PR hash.2
gitGost looks up existing PR
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
Global Burst Detection
gitGost detects coordinated attacks across multiple IPs:Panic Mode
Operators can instantly suspend the service if abuse is detected: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
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:
- The gitGost operator (doesn’t add telemetry or log IPs)
- Your network provider (use VPN/Tor if concerned)
- GitHub (sees your IP during PR creation)
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
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